6. 配置文件 playwright.config 详解

配置文件是什么

第 2 章脚手架已经生成了 playwright.config.ts。它是整个项目的「总开关」。

所有运行选项都写在这里。注意一个关键规则：运行器选项写顶层，不要塞进 use。比如 testDir、timeout、projects 是顶层；而 baseURL、headless 这类「每次操作怎么执行」的，才放 use 里。

一个能照抄的起步配置

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

export default defineConfig({
  // 用例放在哪个目录
  testDir: 'tests',

  // 所有用例并行跑
  fullyParallel: true,

  // CI 上若误留 test.only 直接报错退出
  forbidOnly: !!process.env.CI,

  // 只在 CI 上重试
  retries: process.env.CI ? 2 : 0,

  // CI 上单进程跑，本地默认
  workers: process.env.CI ? 1 : undefined,

  // 用 HTML 报告
  reporter: 'html',

  use: {
    // 给 page.goto('/') 用的基础地址
    baseURL: 'http://localhost:3000',
    // 首次重试时留痕
    trace: 'on-first-retry',
  },

  // 配置要跑的浏览器
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],

  // 跑测试前自动启动本地服务
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

顶层字段逐个看

testDir：用例放哪

Playwright 去这个目录找测试文件。默认匹配 **/*.@(spec|test).?(c|m)[jt]s?(x) —— 说人话就是文件名以 .spec.ts、.test.ts 结尾（.js、.mjs、.tsx 等变体同样算）。

想限定只跑某类文件，用 testMatch；想排除某些文件，用 testIgnore：

export default defineConfig({
  testIgnore: '*test-assets',
  testMatch: '*todo-tests/*.spec.ts',
});

timeout：单条用例多久算挂

默认 30 秒。时间包含测试函数本身、beforeEach 钩子里耗的时长。

export default defineConfig({
  timeout: 30000, // 30 秒
});

use：每次操作怎么执行

use 里放的是「操作级」配置。最常用的是 baseURL：

use: {
  baseURL: 'http://localhost:3000',
}

配了之后，page.goto('/login') 就等价于访问 http://localhost:3000/login，少写重复前缀。

projects：跑哪些浏览器

projects 让你把同一份用例，跑在多个浏览器或设备上。

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'] } },
],

devices 是 Playwright 内置的设备字典，直接展开就能模拟手机视口。

webServer：跑前自动起服务

这是新手最容易踩的坑。测试要点 localhost:3000，但你得先把它起起来。

webServer 帮你做这件事：

webServer: {
  command: 'npm run start',
  url: 'http://localhost:3000',
  reuseExistingServer: !process.env.CI,
}

• command：启动命令。
• url：Playwright 会等这个地址可访问，才开跑。
• reuseExistingServer：本地若已起了服务就复用；CI 上必须重新起，所以置为 false。

进阶：全局 setup 与产物目录

export default defineConfig({
  // 截图、视频、trace 等产物放哪
  outputDir: 'test-results',
  // 全部用例跑前执行一次
  globalSetup: require.resolve('./global-setup'),
  // 全部用例跑后执行一次
  globalTeardown: require.resolve('./global-teardown'),
});

globalSetup 常用来做登录、写 storageState，让后续用例直接带着登录态跑。

如果你的项目是 ESM（package.json 里写了 "type": "module"），require.resolve 用不了，直接写相对路径就行：globalSetup: './global-setup.ts'。

expect 也能单独调超时

断言有独立的超时，默认 5 秒，在配置里单独设：

expect: {
  timeout: 5000,
  toHaveScreenshot: { maxDiffPixels: 10 },
}

小结

配置文件管全局。记住这几条就够起步：testDir 指定用例目录，timeout 设单条上限，use 里放 baseURL，projects 列要跑的浏览器，webServer 负责跑前起服务。

下一章，我们看一个能帮你「写代码」的工具：测试生成器 codegen。