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

string

default:"."

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

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

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

string | RegExp | Array<string | RegExp>

default:"[]"

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

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

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

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

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

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

number

default:"0"

Number of times to retry failed tests.

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

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

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

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

string

default:"'test-results'"

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

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

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

{ 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

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

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

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
}

Overview

Test API

Core Classes

Input & Interaction

Network

Testing Utilities

Reporters

Misc

​Test Configuration

​Importing

​Basic Configuration

​Example Configuration

​Configuration Interface

​TestConfig

​Test Execution Options

​testDir

​testMatch

​testIgnore

​timeout

​globalTimeout

​Parallelization Options

​workers

​fullyParallel

​Retry and Failure Options

​retries

​maxFailures

​forbidOnly

​failOnFlakyTests

​Output and Reporting

​outputDir

​reporter

​reportSlowTests

​quiet

​Use Options

​Browser Options

​Context Options

​Network Options

​Recording Options

​Agent Options

​Project Configuration

​Project Dependencies

​Project Teardown

​Global Hooks

​globalSetup

​globalTeardown

​Web Server

​Expect Configuration

​TypeScript Definitions

​See Also

Build docs developers (and LLMs) love

Test Configuration

Importing

Basic Configuration

Example Configuration

Configuration Interface

TestConfig

Test Execution Options

testDir

testMatch

testIgnore

timeout

globalTimeout

Parallelization Options

workers

fullyParallel

Retry and Failure Options

retries

maxFailures

forbidOnly

failOnFlakyTests

Output and Reporting

outputDir

reporter

reportSlowTests

quiet

Use Options

Browser Options

Context Options

Network Options

Recording Options

Agent Options

Project Configuration

Project Dependencies

Project Teardown

Global Hooks

globalSetup

globalTeardown

Web Server

Expect Configuration

TypeScript Definitions

See Also