playwright.config

Essential Config Sections

Top-level options set test directory, parallelism, retries, and reporters. The use block defaults options for all projects. projects array defines browser/device matrices and setup dependencies.

webServer starts your dev server before tests and shuts it down after — eliminating manual 'npm run dev' in another terminal.

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  reporter: [['html'], ['junit', { outputFile: 'results.xml' }]],
  use: { baseURL: 'http://localhost:3000', trace: 'on-first-retry' },
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    { name: 'chromium', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup'] },
  ],
});

webServer waits until URL responds before running tests.

High-Value Options

testMatch / testIgnore / grep
outputDir / snapshotPathTemplate
globalSetup / globalTeardown
expect: { timeout, toHaveScreenshot: { maxDiffPixels } }

• forbidOnly fails CI if test.only left in code.
• grep/grepInvert filter tests from CLI or config.
• globalSetup runs once before all workers — DB migrate, etc.
• snapshotPathTemplate organizes visual baselines by project.

Config Options Cheat Sheet

Most-edited config fields.

webServer Health Checks

Playwright polls url until HTTP 200. Increase timeout for slow webpack builds. Use stdout: 'pipe' to debug startup failures in CI logs.

Monorepo Patterns

// apps/web/playwright.config.ts
export default defineConfig({
  testDir: './e2e',
  use: { baseURL: 'http://localhost:3001' },
});

Common Mistakes

• No webServer in CI — tests run against dead URL.
• reuseExistingServer true in CI connecting to wrong stale server.
• One giant config for unrelated apps — split configs.
• Forgetting dependencies chain for auth setup project.

Key Takeaways

• Config drives browsers, URLs, CI behavior, and reporting.
• webServer automates app startup for local and CI.
• Projects enable setup dependencies and multi-browser runs.
• forbidOnly and retries protect CI quality.