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: 1280, height: 720 }
locale	string	浏览器语言，如 'zh-CN'、'en-US'
timezone	string	时区，如 'Asia/Shanghai'
colorScheme	string	颜色方案：'light'｜'dark'｜'no-preference'
geolocation		模拟地理位置
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;

AI 思考中...

Playwright 认证（Authentication）

Playwright 多项目配置（Projects）