fix

修复失败或不稳定的测试

使用系统化的分类法诊断并修复间歇性失败或间歇性通过的 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

如果测试通过，则很可能是不稳定测试。运行 burn-in：

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

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

3. 对失败进行分类

从此 Skill 目录加载 flaky-taxonomy.md。

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

类别	症状	诊断
Timing/Async	到处都间歇性失败	--repeat-each=20 可在本地复现
Test Isolation	在套件中失败，单独运行则通过	--workers=1 --grep "test name" 通过
Environment	在 CI 中失败，本地通过	对比 CI 与本地的截图/trace
Infrastructure	随机出现，无规律	错误涉及浏览器内部

4. 应用针对性修复

Timing/Async：

• 用 web-first 断言替换 waitForTimeout()
• 为缺失的 Playwright 调用添加 await
• 在断言前等待特定的网络响应
• 在与元素交互前使用 toBeVisible()

Test Isolation：

• 移除测试之间共享的可变状态
• 通过 API 或 fixture 为每个测试创建测试数据
• 为测试数据使用唯一标识符（时间戳、随机字符串）
• 检查数据库状态泄漏

Environment：

• 让本地与 CI 的视口尺寸保持一致
• 考虑截图中字体渲染的差异
• 在本地使用 docker 以匹配 CI 环境
• 检查依赖时区的断言

Infrastructure：

• 为较慢的 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 通过）
• 预防建议