Sauce Demo - Let's Test It!

[E2E] Automation tests for Sauce Labs shop using 🎭 Playwright framework. Tests are written using TypeScript language and Page Object Model (POM) design pattern.

Table of Contents

1. Project Overview
2. Installation and Setup
3. Folder Structure
4. Code Language and Framework
5. Design Pattern: Page Object Model (POM)
6. How to Run Tests
7. Reporting with Allure Report
8. Contributing
9. License

Project Overview

This repository contains end-to-end (E2E) automation tests for the Sauce Labs shop. The tests are built using the Playwright framework, ensuring robust and reliable testing for web applications.

Installation and Setup

1. Clone the repository:

   git clone https://github.com/empawlowski/sauce-demo-let-s-test-it.git
   cd sauce-demo-let-s-test-it

2. Install dependencies: This command will install all necessary dependencies listed in package.json.

   npm install

3. Install Playwright browsers: This command downloads the browser binaries for Playwright (Chromium, Firefox, WebKit).

   npx playwright install

4. Set up Husky pre-commit hooks: Husky is used to manage Git hooks. The prepare script in package.json (which runs automatically after npm install) should set this up. If not, you can initialize it manually:

   npx husky init

   This will ensure that linting and formatting checks are run before each commit.

Folder Structure

Here's an overview of the main directories and their contents:

• .github/workflows/: Contains GitHub Actions workflow configurations (e.g., playwright-allure.yml for CI).
• .husky/: Contains Git hooks, like pre-commit checks.
• src/: The main directory for all source code.
  • assets/: Stores static assets used by tests.
    • data/: Contains test data files (e.g., for accessibility, E2E).
    • documents/: For any necessary test documents.
    • images/: Stores UI screenshots and visual comparison baseline images.
  • components/: Reusable UI components (e.g., header, footer, sidebar) following the Page Object Model.
  • config/: Project configuration files, including configuration.ts for environment settings and global-setup.ts for Playwright's global setup.
  • download/: Directory for downloaded files during tests (if any).
  • factories/: Contains data factories (e.g., user.factory.ts) for generating test data.
  • fixtures/: Custom Playwright test fixtures for setting up test environments and dependencies.
  • helpers/: Utility functions and helper classes (e.g., axe.helper.ts for accessibility, logger.helper.ts).
  • modals/: Page Object Models for modal dialogs.
  • models/: Data models or interfaces (e.g., user.model.ts).
  • output/: Stores all outputs generated during test execution.
    • allure-reports/: Generated Allure reports.
    • allure-results/: Raw results data for Allure.
    • test-reports/: HTML reports generated by Playwright.
    • test-results/: Other test results, like Playwright traces and screenshots on failure.
  • pages/: Page Object Model classes for different application pages.
    • accessibility/: Pages specific to accessibility tests.
    • e2e/: Pages specific to end-to-end tests.
  • tests/: Contains all the test scripts.
    • accessibility/: Accessibility tests (e.g., using Axe).
    • e2e/: End-to-end test scenarios.
    • performance/: Performance tests (e.g., k6 load tests).
    • ui/: UI validation and visual regression tests.
  • upload/: Directory for files to be uploaded during tests (if any).
  • utils/: General utility functions.
  • views/: View-specific logic or components.
• playwright.config.ts: The main configuration file for Playwright, defining projects, reporters, and test settings.
• package.json: Lists project dependencies, scripts, and metadata.
• tsconfig.json: TypeScript compiler options.
• eslint.config.mjs: ESLint configuration for code linting.
• .prettierrc.json: Prettier configuration for code formatting.
• .env.local, .env.prod: Environment variable files (ensure .env.local is in .gitignore).

Code Language and Framework

This project is written in TypeScript, a strongly typed superset of JavaScript, which provides better tooling and type safety for large-scale projects. The testing framework used is Playwright, which is known for its fast and reliable end-to-end testing capabilities.

Design Pattern: Page Object Model (POM)

The project follows the Page Object Model (POM) design pattern to enhance test maintainability and readability. Each page or component of the application is represented as a class, encapsulating its elements and actions. This approach ensures:

• Reusability of code.
• Easier maintenance when UI changes occur.
• Improved readability and organization of test scripts.

The pages/ and components/ directories contain the implementation of the POM structure, while the tests/ directory contains the test cases that interact with these page objects.

How to Run Tests

The following scripts are available in package.json to run tests:

• Run all tests: This is the default command to execute all test files found in the src/tests directory.

  npm test

  or

  npx playwright test

• Run tests in UI Mode: Opens the Playwright UI mode for a better debugging experience, allowing you to see test execution live and inspect failures.

  npm run test:ui

• Run tests for a specific environment (e.g., prod): Sets the ENV variable to prod and then runs all tests. This allows for environment-specific configurations (see Environment Configuration).

  npm run test:env:prod

• Run only failed tests: Executes only the tests that failed during the last run.

  npm run test:failed

• Run only changed tests: Runs tests related to changed files, based on Git history. Useful for pre-commit checks or CI.

  npm run test:changed

• Run tests by tags: Executes tests that are tagged with @smoke or @reg (regression).

  npm run test:tags

  To run only regression tests:

  npm run test:reg

• Show Playwright's HTML report: Opens the last generated Playwright HTML report.

  npm run show-report

For more details on Playwright's command-line options, refer to the Playwright CLI documentation.

Reporting with Allure Report

This project integrates Allure Report for generating detailed and interactive test reports. Allure Report provides rich insights into test execution, including:

• Test case status (passed, failed, skipped) with detailed steps.
• Execution time and duration for each test and suite.
• Attachments such as screenshots, logs, and videos for failed tests.
• Categorization of test failures.
• Environment information where the tests were run.

Playwright is configured to automatically generate Allure results in ./src/output/allure-results (as defined in playwright.config.ts).

How to Generate and View Allure Reports

1. Ensure tests have been run: First, run your tests (e.g., npm test). This will generate the raw Allure results in src/output/allure-results/.

2. Generate the Allure Report: This command processes the raw results and creates an HTML report. The --clean flag removes previous report data.

   npm run generate-report

   Alternatively, you can run the npx allure command directly:

   npx allure generate src/output/allure-results -o src/output/allure-reports --clean

3. Open/Serve the Allure Report: This command opens the generated report in your default web browser.

   npm run allure-report

   Alternatively, you can run the npx allure command directly:

   npx allure open ./src/output/allure-reports

The generated HTML report will be available in the src/output/allure-reports/ directory. You can also find a GitHub Actions workflow in .github/workflows/playwright-allure.yml that generates and publishes an Allure report when changes are pushed to the repository.

Code Quality and Linting

This project uses Prettier for code formatting and ESLint for static analysis to maintain code quality and consistency.

• Prettier: An opinionated code formatter that ensures a consistent code style across the entire codebase.

  • Configuration: .prettierrc.json
  • Ignore file: .prettierignore

• ESLint: A pluggable and configurable linter tool for identifying and reporting on patterns in JavaScript and TypeScript.

  • Configuration: eslint.config.mjs

Scripts

The following scripts are available in package.json for code quality checks:

• Format code with Prettier: Automatically formats all supported files in the project.

  npm run format

• Check formatting with Prettier: Checks if all files are formatted correctly without making changes. Useful for CI checks.

  npm run format:check

• Lint code with ESLint: Analyzes the code for potential errors and style issues.

  npm run lint

• Check TypeScript types: Performs a TypeScript type check across the project without emitting JavaScript files.

  npm run tsc:check

These checks are also configured to run as a pre-commit hook using Husky (see .husky/pre-commit), ensuring that code is formatted and linted before being committed to the repository.

Environment Configuration

This project supports environment-specific configurations using .env files. The base URL and other settings can be customized for different environments (e.g., local, development, production).

• .env.local: For local development overrides. This file is not committed to Git (and should be listed in .gitignore).
• .env.prod: For production-like environment configurations. This file can be committed if it contains non-sensitive, environment-specific defaults.

The configuration is loaded in src/config/configuration.ts.

Running Tests with a Specific Environment

You can run tests targeting a specific environment by setting the ENV variable before running Playwright. For example, the package.json includes a script to run tests with the production environment configuration:

npm run test:env:prod

This command effectively runs set ENV=prod && npx playwright test (or the equivalent for your shell). The configuration.ts file will then load settings from .env.prod.

To use a different environment (e.g., staging), you would typically:

1. Create a .env.staging file with the appropriate settings.
2. Update src/config/configuration.ts to recognize the staging environment.
3. Run tests with ENV=staging npx playwright test (or create a new npm script).

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Commit your changes with clear messages.
4. Submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.