playwright.config.js

Overview

This file serves as the configuration file for Playwright Test, a testing framework for end-to-end (E2E) testing of web applications. It defines how Playwright runs tests, manages the test environment, and reports results. The configuration is tailored for a Next.js application started on a local development server, with specific settings to optimize test execution both locally and on continuous integration (CI) environments.

Key functionalities include:

Starting and managing a local web server to host the application under test.
Specifying the directory structure for tests and test artifacts like snapshots.
Setting global timeouts and parallelization options for test runs.
Configuring retries and worker counts, conditional on whether tests run on CI.
Defining reporters for test results with different behaviors on CI vs local.
Applying shared test options, including browser/device emulation and tracing.

Detailed Explanation

Imported Modules

import { defineConfig, devices } from '@playwright/test'

defineConfig: Utility function to define and export the Playwright configuration with type safety and code completion.
devices: A set of predefined device descriptors for various browsers and devices, enabling easy emulation of different environments.

Default Export: Playwright Test Configuration Object

The file exports a single configuration object created with defineConfig. This object drives Playwright's behavior when running tests.

export default defineConfig({ ... })

Configuration Properties

1. webServer

webServer: {
  command: 'pnpm next start e2e/site --port 4000',
  reuseExistingServer: !process.env.CI,
  port: 4000
}

Purpose: Automatically start a local web server before running tests.
Properties:
- command: Shell command to start the server. Here, it runs the Next.js app from the e2e/site directory on port 4000 using pnpm.
- reuseExistingServer: Boolean flag to reuse an already running server if available (true when not on CI).
- port: Port number expected to be served by the server.
Usage: Ensures the application is running and accessible at http://localhost:4000 during tests.

2. testDir

testDir: './e2e'

Directory where Playwright looks for test files.
Relative to the config file.
Organizes all the E2E test code inside ./e2e.

3. snapshotDir

snapshotDir: './e2e/__snapshots__'

Base directory for storing snapshot files generated by snapshot-based assertions (toMatchSnapshot, toHaveScreenshot).
Helps with visual regression testing.

4. timeout

timeout: 10 * 1000

Maximum time (in milliseconds) allowed for a single test to run.
Set to 10 seconds.

5. fullyParallel

fullyParallel: true

Enables running tests within files in parallel.
Speeds up test execution by utilizing concurrency.

6. forbidOnly

forbidOnly: !!process.env.CI

Prevents committing tests marked with .only when running on CI.
Helps avoid accidentally skipping tests in the build pipeline.

7. retries

retries: process.env.CI ? 2 : 0

Number of retries for failed tests.
Retries twice on CI, none locally.

8. workers

workers: process.env.CI ? 1 : undefined

Number of parallel worker processes.
Limited to 1 on CI to avoid resource contention.
Defaults to Playwright's choice locally (usually CPU cores).

9. reporter

reporter: process.env.CI
  ? [['github'], ['html', { open: 'on-failure' }]]
  : [['html', { open: 'on-failure' }]]

Defines reporters for test results.
On CI: Uses GitHub Actions reporter (for annotation) + an HTML report opened on failure.
Locally: Only HTML report opened on failure.

10. use

use: {
  baseURL: 'http://localhost:4000',
  trace: process.env.CI ? 'on-first-retry' : 'on',
  ...devices['Desktop Chrome']
}

Shared settings applied to all tests.
baseURL: The root URL for tests; simplifies navigation.
trace: Enables Playwright tracing. On CI, only on first retry to reduce overhead; always on locally.
...devices['Desktop Chrome']: Emulates a desktop Chrome environment by default, including viewport size, user agent, etc.

Usage Examples

Running Tests Locally

Start tests with:

npx playwright test

Playwright starts the Next.js server on port 4000 (if not already running).
Tests run in parallel, using Desktop Chrome emulation.
HTML reports open automatically on test failures.
Tracing is enabled for all tests.

Running Tests in CI Environment

CI sets the CI environment variable (e.g., CI=true).
Playwright will:
- Reuse the server only if it's running.
- Run tests serially (workers: 1).
- Retry failed tests twice.
- Fail the build if .only tests are present.
- Use GitHub Actions reporter for test annotations.
- Collect trace only on the first retry.
Generates HTML reports accessible for diagnostics.

Important Implementation Details

Conditional behavior based on the CI environment variable: This allows optimization for CI pipelines vs local developer environments.
Server reuse: Avoids restarting the server unnecessarily during local development, speeding up test runs.
Device emulation: Uses Playwright's built-in device descriptors for consistent browser environments.
Trace collection: Helps debugging flaky tests by capturing browser interactions.
Parallelization: Fully parallel runs locally for speed, but restricted on CI for stability.

Interaction with Other Parts of the System

Next.js app (e2e/site): The web server command starts this application, which is the target under test.
E2E tests (./e2e): Test scripts and snapshot files reside here and depend on this config for environment setup.
CI/CD pipeline: Relies on this config to govern test execution behavior during automated builds.
Playwright Test Runner: This config file is consumed by Playwright CLI to control test lifecycle.

Visual Diagram

flowchart TD
    A[playwright.config.js] --> B[webServer]
    A --> C[testDir]
    A --> D[snapshotDir]
    A --> E[timeout]
    A --> F[fullyParallel]
    A --> G[forbidOnly]
    A --> H[retries]
    A --> I[workers]
    A --> J[reporter]
    A --> K[use]

    B --> B1[command: pnpm next start e2e/site --port 4000]
    B --> B2[reuseExistingServer: !CI]
    B --> B3[port: 4000]

    J --> J1[CI: github + html reporter]
    J --> J2[Local: html reporter]

    K --> K1[baseURL: http://localhost:4000]
    K --> K2[trace: on-first-retry (CI), on (local)]
    K --> K3[devices['Desktop Chrome']]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:1px
    style J fill:#bbf,stroke:#333,stroke-width:1px
    style K fill:#bbf,stroke:#333,stroke-width:1px

Summary

playwright.config.js is the central configuration for running Playwright E2E tests on a Next.js app. It defines how the app server is started, controls test directories, timeouts, retries, parallelism, and reporting, adapting behavior based on the environment (local or CI). It leverages Playwright's powerful device emulation and tracing features to ensure reliable and debuggable test executions. This file is crucial for maintaining a smooth and consistent test workflow within the project.