Test Configuration

Configuration options for Playwright Test including projects, browsers, timeouts, and reporting

Test Configuration

Playwright Test is configured through a configuration file (playwright.config.ts or playwright.config.js) that defines how tests are run, which browsers to use, and various other options.

Importing

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

export default defineConfig({
  // Configuration options
});

Basic Configuration

Example Configuration

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

export default defineConfig({
  testDir: './tests',
  timeout: 30000,
  retries: 2,
  workers: 4,
  
  use: {
    baseURL: 'http://localhost:3000',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
  ],
});

Configuration Interface

TestConfig

Main configuration interface for Playwright Test.

interface TestConfig<TestArgs = {}, WorkerArgs = {}> {
  // Test execution
  testDir?: string;
  testMatch?: string | RegExp | Array<string | RegExp>;
  testIgnore?: string | RegExp | Array<string | RegExp>;
  timeout?: number;
  globalTimeout?: number;
  expect?: ExpectConfig;
  
  // Parallelization
  workers?: number | string;
  fullyParallel?: boolean;
  
  // Retries and failures
  retries?: number;
  maxFailures?: number;
  forbidOnly?: boolean;
  
  // Output and reporting
  outputDir?: string;
  reporter?: ReporterDescription[];
  reportSlowTests?: { max: number; threshold: number } | null;
  quiet?: boolean;
  preserveOutput?: 'always' | 'never' | 'failures-only';
  
  // Snapshots
  snapshotDir?: string;
  snapshotPathTemplate?: string;
  updateSnapshots?: 'all' | 'none' | 'missing';
  ignoreSnapshots?: boolean;
  
  // Filtering
  grep?: RegExp | RegExp[];
  grepInvert?: RegExp | RegExp[];
  
  // Projects
  projects?: Project<TestArgs, WorkerArgs>[];
  
  // Global hooks
  globalSetup?: string | string[];
  globalTeardown?: string | string[];
  
  // Web server
  webServer?: WebServer | WebServer[];
  
  // Options
  use?: UseOptions<TestArgs, WorkerArgs>;
  
  // Metadata
  metadata?: Metadata;
  name?: string;
  
  // Other
  shard?: { total: number; current: number } | null;
}

Test Execution Options

testDir

testDir · string · default: "."

Directory where test files are located. All test files matching testMatch pattern will be executed.

export default defineConfig({
  testDir: './e2e',
});

testMatch

testMatch · string | RegExp | Array<string | RegExp> · default: "**/*.@(spec|test).?(c|m)[jt]s?(x)"

Pattern(s) to match test files.

export default defineConfig({
  testMatch: '**/*.spec.ts',
  // or multiple patterns
  testMatch: ['**/*.test.ts', '**/*.spec.ts'],
});

testIgnore

testIgnore · string | RegExp | Array<string | RegExp> · default: "[]"

Pattern(s) to ignore when looking for test files.

export default defineConfig({
  testIgnore: '**/node_modules/**',
});

timeout

timeout · number · default: "30000"

Maximum time in milliseconds for a single test. Use 0 to disable timeout.

export default defineConfig({
  timeout: 60000, // 60 seconds
});

globalTimeout

globalTimeout · number · default: "0"

Maximum time in milliseconds for the entire test run. Use 0 to disable.

export default defineConfig({
  globalTimeout: 3600000, // 1 hour
});

Parallelization Options

workers

workers · number | string · default: "'50%'"

Maximum number of concurrent worker processes. Can be a number or percentage string.

export default defineConfig({
  workers: 4,
  // or
  workers: '50%', // Use 50% of CPU cores
});

fullyParallel

fullyParallel · boolean · default: "false"

Run all tests in all files in parallel. By default, test files run in parallel but tests within a file run serially.

export default defineConfig({
  fullyParallel: true,
});

Retry and Failure Options

retries

retries · number · default: "0"

Number of times to retry failed tests.

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
});

maxFailures

maxFailures · number · default: "0"

Maximum number of test failures before stopping the test run. Use 0 to disable.

export default defineConfig({
  maxFailures: process.env.CI ? 10 : 0,
});

forbidOnly

forbidOnly · boolean · default: "false"

Whether to fail if any tests are marked as test.only(). Useful for CI.

export default defineConfig({
  forbidOnly: !!process.env.CI,
});

failOnFlakyTests

failOnFlakyTests · boolean · default: "false"

Whether to fail if any tests are flaky (passed after retry). Useful for CI.

export default defineConfig({
  failOnFlakyTests: !!process.env.CI,
});

Output and Reporting

outputDir

outputDir · string · default: "'test-results'"

Directory for test artifacts like screenshots, videos, and traces.

export default defineConfig({
  outputDir: './test-results',
});

reporter

reporter · ReporterDescription[] · default: "'list'"

Test reporters to use. Can be built-in reporters or custom reporter modules.

Built-in Reporters: 'list', 'dot', 'line', 'github', 'json', 'junit', 'html', 'blob'

export default defineConfig({
  reporter: [
    ['html', { outputFolder: 'playwright-report' }],
    ['json', { outputFile: 'test-results.json' }],
    ['junit', { outputFile: 'junit.xml' }],
  ],
});

reportSlowTests

reportSlowTests · { max: number; threshold: number } | null · default: "{ max: 5, threshold: 15000 }"

Report slow test files. Set to null to disable.

export default defineConfig({
  reportSlowTests: {
    max: 10,      // Report up to 10 slow test files
    threshold: 30000  // Files taking more than 30s
  },
});

quiet

quiet · boolean · default: "false"

Whether to suppress stdio output from tests.

export default defineConfig({
  quiet: true,
});

Use Options

The use section configures the browser context and test options.

Browser Options

use.browserName · 'chromium' | 'firefox' | 'webkit' · default: "'chromium'"

Browser to use for tests.

use.headless · boolean · default: "true"

Whether to run browser in headless mode.

use.channel · string

Browser channel to use (e.g., ‘chrome’, ‘msedge’).

export default defineConfig({
  use: {
    browserName: 'chromium',
    headless: true,
    channel: 'chrome',
  },
});

Context Options

use.baseURL · string

Base URL for page.goto(). Relative URLs will be resolved against this.

use.viewport · { width: number; height: number } | null · default: "{ width: 1280, height: 720 }"

Browser viewport size. Set to null to disable fixed viewport.

use.userAgent · string

Custom user agent string.

use.locale · string · default: "'en-US'"

Browser locale.

use.timezoneId · string

Timezone identifier (e.g., ‘America/New_York’).

export default defineConfig({
  use: {
    baseURL: 'http://localhost:3000',
    viewport: { width: 1920, height: 1080 },
    locale: 'en-US',
    timezoneId: 'America/New_York',
  },
});

Network Options

use.ignoreHTTPSErrors · boolean · default: "false"

Whether to ignore HTTPS errors.

use.offline · boolean · default: "false"

Simulate offline network.

use.proxy · { server: string; bypass?: string; username?: string; password?: string }

Network proxy settings.

export default defineConfig({
  use: {
    ignoreHTTPSErrors: true,
    proxy: {
      server: 'http://proxy.example.com:8080',
      bypass: 'localhost',
    },
  },
});

Recording Options

use.screenshot · 'off' | 'on' | 'only-on-failure' | 'on-first-failure' · default: "'off'"

When to capture screenshots.

use.video · 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' · default: "'off'"

When to record videos.

use.trace · 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' · default: "'off'"

When to record traces.

export default defineConfig({
  use: {
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    trace: 'on-first-retry',
  },
});

Agent Options

use.agentOptions · AgentOptions

Configuration for AI agent fixture.

interface AgentOptions {
  provider?: {
    api: 'openai' | 'anthropic' | 'google' | 'openai-compatible';
    apiKey: string;
    model: string;
    apiEndpoint?: string;
    apiTimeout?: number;
  };
  limits?: {
    maxTokens?: number;
    maxActions?: number;
    maxActionRetries?: number;
  };
  cachePathTemplate?: string;
  systemPrompt?: string;
  secrets?: Record<string, string>;
}

Example:

export default defineConfig({
  use: {
    agentOptions: {
      provider: {
        api: 'openai',
        apiKey: process.env.OPENAI_API_KEY!,
        model: 'gpt-4',
      },
      limits: {
        maxActions: 50,
      },
    },
  },
});

Project Configuration

Define multiple projects to run tests in different configurations.

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    {
      name: 'mobile-chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'mobile-safari',
      use: { ...devices['iPhone 13'] },
    },
  ],
});

Project Dependencies

export default defineConfig({
  projects: [
    {
      name: 'setup',
      testMatch: /global\.setup\.ts/,
    },
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
      dependencies: ['setup'],
    },
  ],
});

Project Teardown

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
      teardown: 'cleanup',
    },
    {
      name: 'cleanup',
      testMatch: /global\.teardown\.ts/,
    },
  ],
});

Global Hooks

globalSetup

globalSetup · string | string[]

Path to global setup file(s) that run before all tests.

export default defineConfig({
  globalSetup: './global-setup.ts',
});

global-setup.ts:

import { FullConfig } from '@playwright/test';

export default async function globalSetup(config: FullConfig) {
  // Start database, servers, etc.
  console.log('Running global setup');
}

globalTeardown

globalTeardown · string | string[]

Path to global teardown file(s) that run after all tests.

export default defineConfig({
  globalTeardown: './global-teardown.ts',
});

Web Server

Start a development server before running tests.

webServer · WebServer | WebServer[]

Configuration for starting a web server.

interface WebServer {
  command: string;
  url: string;
  timeout?: number;
  reuseExistingServer?: boolean;
  cwd?: string;
  env?: Record<string, string>;
  ignoreHTTPSErrors?: boolean;
}

Example:

export default defineConfig({
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 120000,
  },
});

Expect Configuration

Configure assertion behavior.

export default defineConfig({
  expect: {
    timeout: 5000,
    toHaveScreenshot: {
      threshold: 0.2,
      maxDiffPixels: 100,
    },
    toMatchSnapshot: {
      threshold: 0.3,
    },
  },
});

TypeScript Definitions

function defineConfig<T = {}, W = {}>(config: TestConfig<T, W>): TestConfig<T, W>;
function defineConfig(config: TestConfig): TestConfig;

interface FullConfig extends TestConfig {
  version: string;
  configFile?: string;
  rootDir: string;
  projects: FullProject[];
}

interface FullProject {
  name: string;
  testDir: string;
  outputDir: string;
  use: UseOptions;
  // ... other resolved options
}

See Also

• Test API - Test functions and methods
• Test Fixtures - Built-in fixtures
• Configuration Guide - Detailed configuration examples