第 11 天：Playwright 配置文件

今日目标

• 理解 playwright.config.ts。
• 掌握 baseURL、projects、timeout、retries、reporter、use。

学习时间安排（60–120 分钟）

核心概念与词汇

学习材料

• 必读：[Test configuration](https://playwright.dev/docs/test-configuration)
• 必读：[Basic options](https://playwright.dev/docs/test-configuration#basic-options) 部分
• 选读：[Emulation](https://playwright.dev/docs/emulation)（了解 devices 的能力）

重点理解

常见配置：

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

export default defineConfig({
  testDir: './tests',
  timeout: 30 * 1000,
  expect: {
    timeout: 5000,
  },
  retries: process.env.CI ? 2 : 0,
  reporter: [['html'], ['list']],
  use: {
    baseURL: 'https://playwright.dev',
    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'] } },
  ],
});

重点理解：

• testDir：测试目录。
• timeout：单条测试超时。
• expect.timeout：断言超时。
• retries：失败重试。
• reporter：报告。
• use：所有测试共享配置。
• projects：浏览器/设备/环境矩阵。

实操步骤

修改配置：

1. 设置 baseURL。
2. 开启失败截图。
3. 开启失败视频。
4. 设置 trace 为 on-first-retry。
5. 只保留 chromium 项目运行一次。

示例代码

配合 baseURL 后，测试里的导航用相对路径：

// 之前
await page.goto('https://playwright.dev/');
// 之后（baseURL: 'https://playwright.dev'）
await page.goto('/');

常见坑

• timeout 和 expect.timeout 混为一谈，改错一个导致全项目行为变化。
• 本地 retries 也开 2 次，flaky 被隐藏，问题拖到 CI 才爆发。
• 忘记 use 的作用域：projects 里也可以覆盖 use，配置有层级。
• 截图/视频/trace 全量开启，磁盘被测试产物塞满。
• baseURL 配了但测试里仍写绝对 URL，换环境时改不过来。

今日产出

• 一份可解释的 playwright.config.ts。
• 记录每个关键字段的作用。

今日问题

1. baseURL 有什么好处？
2. timeout 和 expect.timeout 有什么区别？
3. 为什么 CI 上通常要配置 retries？
4. Trace、screenshot、video 分别适合排查什么？
5. projects 可以用来解决哪些测试矩阵问题？

复盘要点

• 配置文件是团队测试行为的“宪法”：谁改配置，影响的是所有人的测试。
• 记住三层结构：全局 → use → projects 覆盖，排错时从最内层看起。
• 产物策略（trace/screenshot/video）从今天起就按 CI 标准配好，别等失败时才发现没有证据。

AI 时代扩展：AI 辅助 Playwright 测试

新增概念

适用场景

让 AI 解释你的配置文件每个字段，或者根据“我要跑多环境 + CI 保留失败证据”的需求生成一份配置草稿，再逐项核对官方文档。

可复用表达 / 提示词

请解释这个 playwright.config.ts 的每个字段，并指出哪些配置在 CI 上会有问题。
我需要 3 个环境的测试矩阵（dev/staging/prod），CI 失败时保留 trace 和截图，请给出配置草稿并说明理由。

追问加练

• AI 生成的配置里有你不认识的字段，你会怎么处理？
• 多环境矩阵用 projects 还是用环境变量？各自的取舍是什么？
• 哪些配置错误 AI 很难发现？

今日作业

• 给配置文件写注释，每行说明影响什么行为。
• 用 baseURL 改写自己测试里的所有绝对 URL。
• 让 AI 审查你的配置，逐条核对它的意见是否与官方文档一致。

自检清单

• 我能解释 7 个以上配置项的作用。
• 我的 baseURL 已生效，测试用相对路径。
• 失败时能自动保留截图和 trace。
• 我知道 retries 为什么只在 CI 开启。
• 明天学习 hooks 时，我能说出 beforeEach 和配置的边界。