E2E Playwright Boilerplate

Overview

The E2E Playwright Boilerplate provides a comprehensive testing framework using Playwright. It supports GraphQL and REST API testing, as well as end-to-end UI testing, with built-in support for reporting, BDD, and various utilities for streamlined test development.

This boilerplate is perfect for teams looking to automate and simplify the testing process, improving both test quality and efficiency.

---

Table of Contents

• Project Structure
• Installation
• Configuration
• Documentation
• Utilities
• Running Tests
• Scripts
• License
• Author

Project Structure

The project is organized into a clear and modular directory structure. Below is a high-level view:

e2e-playwright-boilerplate
├── .gitignore
├── package-lock.json
├── package.json
├── playwright.config.js
├── README.md
├── docs/
│   ├── config/
│   │   └── readme.md
│   └── src/
│       ├── readme.md
│       └── utils/
│           ├── AccessibilityHelper.md
│           ├── ApiHelper.md
│           ├── BrowserStorageHelper.md
│           ├── CommonFunctions.md
│           ├── GraphqlHelper.md
│           ├── JsonHelper.md
│           └── PlaywrightActions.md
├── resources/
│   ├── config/
│   │   ├── env.config.js
│   │   └── globalEnv.config.js
│   ├── data/
│   │   ├── assertiveStrings.js
│   │   └── testData.js
│   ├── downloads/
│   │   └── .gitkeep
│   └── utils/
│       ├── AccessibilityHelper.js
│       ├── ApiHelper.js
│       ├── BrowserStorageHelper.js
│       ├── CommonFunctions.js
│       ├── GraphqlHelper.js
│       ├── JsonHelper.js
│       └── PlaywrightActions.js
└── src/
    └── tests/
        ├── api/
        │   ├── features/
        │   │   └── 05-apiFakeStorePostDelete.feature
        │   ├── pages/
        │   │   └── 05-apiFakeStorePostDelete_page.js
        │   └── step_definitions/
        │       └── 05-apiFakeStorePostDelete_steps.js
        ├── graphql/
        │   ├── features/
        │   │   └── 04-gqlGraphQLZeroGetDeleteAPost.feature
        │   ├── mutations/
        │   │   └── 04-gqlGraphQLZeroDeleteAPost.js
        │   ├── pages/
        │   │   └── 04-gqlGraphQLZero_page.js
        │   ├── queries/
        │   │   └── 04-gqlGraphQLZeroGetAPost.js
        │   └── step_definitions/
        │       └── 04-gqlGraphQLGetDeleteAPost_steps.js
        ├── shared/
        │   ├── contracts/
        │   │   ├── 04-GraphQLZeroGetAPost_contract.js
        │   │   └── 05-apiFakeStorePostDelete_contract.js
        │   └── models/
        │       ├── 04-gqlGraphQLZeroDeleteAPost_model.js
        │       └── 05-apiFakeStorePostDelete_model.js
        └── ui/
            ├── features/
            │   ├── 01-uiLetCodeInputBox.feature
            │   ├── 02-uiLetCodeButton.feature
            │   └── 03-uiLetCodeDropdown.feature
            ├── pages/
            │   ├── 01-uiLetCodeInputBox_page.js
            │   ├── 02-uiLetCodeButton_page.js
            │   └── 03-uiLetCodeDropdown_page.js
            └── step_definitions/
                ├── 01-uiLetCodeInputBox_steps.js
                ├── 02-uiLetCodeButton_steps.js
                └── 03-uiLetCodeDropdown_steps.js

🔑 Key Features

---

1. 🧩 Modular Directories
   Organize your project into distinct submodules (API, GraphQL, UI, shared components) to enhance maintainability and scalability.

2. ⚙️ Flexible Configuration
   Easily switch between different environments (dev, staging, production) with modular, environment-specific configurations.

3. 📝 BDD with Cucumber
   Write clear, readable test scenarios using Gherkin syntax to promote collaboration between technical and non-technical teams.

4. 🏗️ Page Object Model (POM)
   Use the Page Object Model design pattern to separate test logic from UI interactions, making updates and scaling tests easier.

5. ♿ Accessibility Testing Support
   Ensure compliance with WCAG standards, improving accessibility for users with disabilities.

6. 🔄 Contract Testing
   Verify that interactions between microservices and APIs follow predefined contracts, reducing integration risks.

7. 🛠️ Custom Action Library
   Leverage reusable, high-level Playwright actions for consistent, stable interactions across test scenarios.

8. 📊 Verbose Logging & Frame Handling
   Get detailed execution logs and advanced iframe handling for more thorough test coverage and easier debugging.

9. 🚀 Suite-Based Testing with Parallel Browsing
   Run test suites in parallel across different browsers to speed up test execution and improve cross-browser coverage.

10. 📑 Allure Reporting
    Access rich, interactive test reports with logs, screenshots, videos, and metrics for easier troubleshooting and insights.

11. 🗂️ Organized Test Structure
    Follow a clean, structured folder organization that enhances maintainability and readability of your code.

12. 🌐 Powerful Playwright Configuration
    Configure Playwright tests with fine-grained control over browser contexts, timeouts, retries, and parallel execution.

13. 📅 ES6 Standards
    Stick to modern ES6+ standards (async/await, classes, destructuring) for cleaner, more maintainable code.

14. 🌍 Cross-Environment Compatibility
    Seamlessly switch between environments (dev, staging, production) for consistent results across your testing pipeline.

15. 🔄 CI/CD Ready
    Integrate effortlessly into your Continuous Integration/Continuous Delivery pipelines for faster releases and higher-quality software.

16. 🛠️ Robust Error Reporting
    Receive detailed error reports with stack traces, logs, screenshots, and videos to expedite the debugging process.

17. 📊 Test Data Management
    Generate and manage dynamic test data to reduce reliance on hardcoded values and improve coverage.

18. 🔄 Parallel Test Execution
    Maximize resource utilization and reduce test runtime by executing tests in parallel.

19. 🌍 Cross-Browser Testing
    Test your application across multiple browsers (Chromium, WebKit, Firefox) to ensure consistency across platforms.

20. 🔄 Retry Logic
    Handle flaky tests with automatic retries to improve the stability of your test suite.

21. 🏷️ Dynamic Test Execution Based on Tags
    Execute tests selectively based on tags (e.g., @smoke, @regression) to optimize your testing workflow.

22. 📸 Test Reports with Screenshots & Videos
    Capture screenshots and videos of failed tests for easy inspection and troubleshooting.

---

Installation

To get started quickly, follow these simple steps:

Step 1: Clone the Repository

git clone https://github.com/hexdee606/e2e-playwright-boilerplate.git
cd e2e-playwright-boilerplate

Step 2: Install Dependencies

npm install

Step 3: Install Playwright Browsers

npx playwright install

---

Configuration

The configuration files are organized in the resources/config/ directory. These allow you to manage environment-specific configurations and global settings.

• env.config.js: Environment-specific settings like API URLs and authentication tokens.
• globalEnv.config.js: Global settings shared across all environments and tests.

Example Configuration

module.exports = {
    env: process.env.E2E || 'staging',
    configs: {
        staging: {
            frontend: {
                url: 'https://staging.example.com',
            },
            backend: {
                api: 'https://api.staging.example.com',
                gql: 'https://gql.staging.example.com',
            },
        },
        production: {
            frontend: {
                url: 'https://prod.example.com',
            },
            backend: {
                api: 'https://api.prod.example.com',
                gql: 'https://gql.prod.example.com',
            },
        },
    },
};

---

Documentation

In-depth documentation for each component is available in the docs/ folder.

• Config Documentation
• Source Documentation

Utilities Documentation

Detailed documentation for the utilities:

• 🛠️ Accessibility Helper
• 💻 Api Helper
• 💾 Browser Storage Helper
• ⚙️ Common Functions
• 📊 Graphql Helper
• 📄 Json Helper
• 🎮 Playwright Actions

---

Utilities

Helper Functions

The src/utils/ directory houses several important helper utilities:

• ApiHelper: Functions for making API requests. This utility helps streamline interactions with external services, providing convenient methods to send HTTP requests and handle responses.
• PlaywrightActions: Functions for automating browser actions with Playwright. This utility simplifies common Playwright operations like clicking, typing, and waiting for elements in automated browser tests.
• CommonFunctions: Reusable functions for common tasks, such as data manipulation, validation, and other general-purpose utilities that are used across different parts of the codebase.
• AccessibilityHelper: Functions that help improve accessibility by offering tools for checking and managing accessibility-related issues in web applications, ensuring compliance with accessibility standards.
• BrowserStorageHelper: Utility functions to handle browser storage, including working with localStorage and sessionStorage. It provides an abstraction layer to simplify data management in the browser.
• GraphqlHelper: Utility for making GraphQL queries and mutations, providing convenient functions to handle GraphQL operations with ease.
• JsonHelper: Functions to assist with parsing, formatting, and manipulating JSON data, making it easier to work with structured data in JavaScript or TypeScript.

These utilities ensure that your tests are easy to write and maintain.

---

Running Tests

Run All Tests

To execute all tests in the project, simply run:

npx playwright test

---

Available Scripts

In the package.json, you can find several useful scripts for different testing purposes:

• Run End-to-End Tests:

npm run test:e2e

• Run Smoke Tests:

npm run test:smoke

• Generate Allure Reports:

npm run test:report-generate

---

License

This project is licensed under the CC0-1.0 License.

---

Author

Hexdee606
Date: 2024-10-11

💡 Special Thanks to JetBrains

I’d like to express my sincere gratitude to JetBrains for providing the incredible Aqua IDE. This powerful tool has significantly improved my development workflow by offering seamless integration with multiple languages and frameworks. It’s been an absolute game-changer, making coding faster, more efficient, and more enjoyable.

Thank you, JetBrains, for such a fantastic tool! 🙏

🔧 Tool used:

• Aqua IDE

---

Tagging JetBrains:

@JetBrains