Playwright 配置详解

本章详细介绍 playwright.config.ts 中的各项配置，让你能够根据项目需求灵活调整测试行为。

配置文件概览

playwright.config.ts 是 Playwright 的中央配置文件，所有测试运行参数都在此定义。

实例

// 文件路径：playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
// ===== 基础配置 =====
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
timeout: 30000,

// ===== 全局共享配置 =====
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},

// ===== 多浏览器项目 =====
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
],

// ===== Web 服务器 =====
webServer: {
command: 'npm run start',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
});

基础配置项

配置项	类型	默认值	说明
`testDir`	string	tests	测试文件所在目录
`fullyParallel`	boolean	false	是否完全并行运行所有测试（包括同一文件内的测试）
`workers`	number	CPU 核心数/2	并行执行的 worker 数量
`retries`	number	0	失败测试的重试次数
`timeout`	number	30000	每个测试的总超时（毫秒）
`reporter`	string/array	list	测试报告器类型
`forbidOnly`	boolean	false	CI 上检测到 test.only() 则失败
`testMatch`	string/RegExp	*.spec.(ts\\|js)	测试文件的匹配模式
`testIgnore`	string/RegExp	-	忽略的测试文件模式

配置示例

实例

export default defineConfig({
// 在 e2e 目录中找测试
testDir: './e2e',

// 所有测试完全并行
fullyParallel: true,

// 自动分配 worker 数量
workers: undefined,

// 失败不重试（本地）/ 重试 2 次（CI）
retries: process.env.CI ? 2 : 0,

// 同时使用命令行和 HTML 报告
reporter: [
['list'],
['html', { open: 'never' }],
],
});

use 公共配置

use 中的配置会应用到所有测试和项目：

配置项	类型	说明
`baseURL`	string	基础 URL，测试中可用相对路径（如 `await page.goto('/login')`）
`viewport`	{width, height}	浏览器视口大小，默认 `{ width: 1280, height: 720 }`
`locale`	string	浏览器语言，如 `'zh-CN'`、`'en-US'`
`timezone`	string	时区，如 `'Asia/Shanghai'`
`colorScheme`	string	颜色方案：`'light'`｜`'dark'`｜`'no-preference'`
`geolocation`	{latitude, longitude}	模拟地理位置
`permissions`	string[]	授予的浏览器权限（如 `['geolocation']`）
`userAgent`	string	自定义 User-Agent 字符串
`trace`	string	Trace 收集策略：`'on'`｜`'off'`｜`'on-first-retry'`
`screenshot`	string	截图策略：`'on'`｜`'off'`｜`'only-on-failure'`
`video`	string	视频录制策略：`'on'`｜`'off'`｜`'retain-on-failure'`
`storageState`	string	认证状态文件路径
`testIdAttribute`	string	自定义 testId 属性名，默认 `'data-testid'`
`actionTimeout`	number	每个操作（click、fill）的超时时间
`navigationTimeout`	number	每次导航的超时时间

webServer 配置

webServer 配置让 Playwright 在运行测试前自动启动你的开发服务器：

实例

export default defineConfig({
webServer: {
// 启动命令
command: 'npm run dev',

// 等待此 URL 可访问后再运行测试
url: 'http://localhost:5173',

// 超时等待时间（毫秒）
timeout: 120000,

// 是否复用已运行的服务器（本地可复用，CI 上重新启动）
reuseExistingServer: !process.env.CI,
},
});

globalSetup / globalTeardown 全局钩子

在所有测试运行之前/之后执行一次，适合数据库初始化等操作。

实例

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

实例

// 文件路径：global-setup.ts
import { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
// 在所有测试运行之前执行
console.log('开始全局设置...');
// 例如：初始化测试数据库、创建测试用户等
}

export default globalSetup;

返回顶部

菜鸟教程