Playwright Configuration Explained
This chapter provides a detailed introduction toplaywright.config.tsthe various configurations in it, allowing you to flexibly adjust test behavior based on project requirements.
Configuration File Overview
playwright.config.tsis Playwright's central configuration file, where all test runtime parameters are defined.
Example
// File path: playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
// ===== Basic Configuration =====
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
timeout: 30000,
// ===== Global Shared Configuration =====
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
// ===== Multi-browser Projects =====
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
],
// ===== Web Server =====
webServer: {
command: 'npm run start',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
});
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
// ===== Basic Configuration =====
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
timeout: 30000,
// ===== Global Shared Configuration =====
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
// ===== Multi-browser Projects =====
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
],
// ===== Web Server =====
webServer: {
command: 'npm run start',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
});
Basic Configuration Options
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
testDir | string | tests | Directory where test files are located |
fullyParallel | boolean | false | Whether to run all tests fully in parallel (including tests within the same file) |
workers | number | CPU cores / 2 | Number of workers executing in parallel |
retries | number | 0 | Number of retries for failed tests |
timeout | number | 30000 | Total timeout per test (milliseconds) |
reporter | string/array | list | Test reporter type |
forbidOnly | boolean | false | Fail if test.only() is detected on CI |
testMatch | string/RegExp | *.spec.(ts\|js) | Test file matching pattern |
testIgnore | string/RegExp | - | Ignored test file patterns |
Configuration Example
Example
export default defineConfig({
// Find tests in the e2e directory
testDir: './e2e',
// All tests fully parallel
fullyParallel: true,
// Automatically allocate worker count
workers: undefined,
// No retry on failure (local) / retry 2 times (CI)
retries: process.env.CI ? 2 : 0,
// Use both command line and HTML reports
reporter: [
['list'],
['html', { open: 'never' }],
],
});
// Find tests in the e2e directory
testDir: './e2e',
// All tests fully parallel
fullyParallel: true,
// Automatically allocate worker count
workers: undefined,
// No retry on failure (local) / retry 2 times (CI)
retries: process.env.CI ? 2 : 0,
// Use both command line and HTML reports
reporter: [
['list'],
['html', { open: 'never' }],
],
});
use Common Configuration
useThe configuration in it applies to all tests and projects:
| Configuration Item | Type | Description |
|---|---|---|
baseURL | string | Base URL, relative paths can be used in tests (e.g.await page.goto('/login')） |
viewport | {width, height} | Browser viewport size, default{ width: 1280, height: 720 } |
locale | string | Browser language, e.g.'zh-CN'、'en-US' |
timezone | string | Timezone, e.g.'Asia/Shanghai' |
colorScheme | string | Color scheme:'light'｜'dark'｜'no-preference' |
geolocation | {latitude, longitude} | Simulated geolocation |
permissions | string[] | Granted browser permissions (e.g.['geolocation']） |
userAgent | string | Custom User-Agent string |
trace | string | Trace collection strategy:'on'｜'off'｜'on-first-retry' |
screenshot | string | Screenshot strategy:'on'｜'off'｜'only-on-failure' |
video | string | Video recording strategy:'on'｜'off'｜'retain-on-failure' |
storageState | string | Authentication state file path |
testIdAttribute | string | Custom testId attribute name, default'data-testid' |
actionTimeout | number | Timeout for each operation (click, fill) |
navigationTimeout | number | Timeout for each navigation |
webServer Configuration
webServerThe configuration allows Playwright to automatically start your development server before running tests:
Example
export default defineConfig({
webServer: {
// Startup command
command: 'npm run dev',
// Wait until this URL is accessible before running tests
url: 'http://localhost:5173',
// Timeout wait duration (milliseconds)
timeout: 120000,
// Whether to reuse an already running server (can reuse locally, restart on CI)
reuseExistingServer: !process.env.CI,
},
});
webServer: {
// Startup command
command: 'npm run dev',
// Wait until this URL is accessible before running tests
url: 'http://localhost:5173',
// Timeout wait duration (milliseconds)
timeout: 120000,
// Whether to reuse an already running server (can reuse locally, restart on CI)
reuseExistingServer: !process.env.CI,
},
});
globalSetup / globalTeardown Global Hooks
Executed once before/after all tests run, suitable for operations such as database initialization.
Example
export default defineConfig({
globalSetup: './global-setup.ts',
globalTeardown: './global-teardown.ts',
});
globalSetup: './global-setup.ts',
globalTeardown: './global-teardown.ts',
});
Example
// File path: global-setup.ts
import { FullConfig } from '@playwright/test';
async function globalSetup(config: FullConfig) {
// Executed before all tests run
console.log('Starting global setup...');
// For example: initialize test database, create test users, etc.
}
export default globalSetup;
import { FullConfig } from '@playwright/test';
async function globalSetup(config: FullConfig) {
// Executed before all tests run
console.log('Starting global setup...');
// For example: initialize test database, create test users, etc.
}
export default globalSetup;