修复

修复失败或不稳定的测试

使用系统化的分类方法，诊断并修复失败或间歇性通过的 Playwright 测试。

输入

$ARGUMENTS 包含：

• 测试文件路径：e2e/login.spec.ts

• 测试名称："should redirect after login"

• 描述："the checkout test fails in CI but passes locally"

步骤

1. 复现失败

运行测试以捕获错误：

npx playwright test <file> --reporter=list

如果测试通过，则可能是不稳定的（flaky）。运行压力测试：

npx playwright test <file> --repeat-each=10 --reporter=list

如果仍然通过，尝试使用并行 worker 运行：

npx playwright test --fully-parallel --workers=4 --repeat-each=5

2. 捕获追踪 (Trace)

开启完整追踪运行：

npx playwright test <file> --trace=on --retries=0

阅读追踪输出。如果可用，使用 /debug 分析追踪文件。

3. 对失败进行分类

加载本技能目录下的 flaky-taxonomy.md。

每个失败的测试都属于以下四类之一：

| 类别 | 症状 | 诊断 |
|---|---|---|
| 时序/异步 (Timing/Async) | 在任何环境下都间歇性失败 | --repeat-each=20 可在本地复现 |
| 测试隔离 (Test Isolation) | 在测试套件中失败，单独运行通过 | --workers=1 --grep "test name" 可通过 |
| 环境 (Environment) | CI 环境失败，本地通过 | 对比 CI 与本地的截图/追踪 |
| 基础设施 (Infrastructure) | 随机失败，无规律 | 错误信息涉及浏览器内部机制 |

4. 应用针对性修复

时序/异步：

• 将 waitForTimeout() 替换为 Web-first 断言

• 为缺失的 Playwright 调用添加 await

• 在断言前等待特定的网络响应

• 在与元素交互前使用 toBeVisible()

测试隔离：

• 移除测试之间共享的可变状态

• 通过 API 或 fixtures 为每个测试创建独立测试数据

• 为测试数据使用唯一标识符（时间戳、随机字符串）

• 检查数据库状态泄露

环境：

• 统一本地与 CI 的视口 (viewport) 大小

• 在截图中考虑字体渲染差异

• 在本地使用 docker 以匹配 CI 环境

• 检查是否存在依赖时区的断言

基础设施：

• 为运行缓慢的 CI 增加超时时间

• 在 CI 配置中添加重试 (retries: 2)

• 检查浏览器是否 OOM（减少并行 worker 数量）

• 确保安装了所有浏览器依赖

5. 验证修复

运行测试 10 次以确认稳定性：

npx playwright test <file> --repeat-each=10 --reporter=list

必须 10 次全部通过。如果任何一次失败，请返回步骤 3。

6. 防止再次发生

建议：

• 如果尚未配置，在 CI 中添加 retries: 2

• 在配置中启用 trace: 'on-first-retry'

• 将修复模式添加到项目的测试规范文档中

输出

• 根本原因类别及具体问题

• 已应用的修复方案（附带 diff）

• 验证结果（10/10 通过）

• 预防建议