fix

fix skill 概览

fix skill 能做什么

fix skill 是一套面向 Playwright 测试失败或不稳定失败的专用调试流程。它帮助 AI agent 从“这个测试坏了”推进到更可能的根因：先复现失败、收集 trace 证据，再用 flaky-test taxonomy 对问题分类，而不是只凭 assertion error 猜测原因。

最适合 Playwright 测试调试的场景

如果你维护端到端测试，并且经常遇到 “test failing”、“flaky test”、“passes locally but fails in CI” 或 “intermittent failure” 这类问题，就适合安装这个 skill。对于在 CI 中运行 Playwright 的团队尤其有用，因为失败可能来自时序问题、测试隔离不足、环境差异或基础设施压力。

为什么它比通用 prompt 更有用

通用调试 prompt 往往会直接跳到改代码。fix skill 会强制采用更可靠的顺序：先复现；如果失败消失，就做 burn-in；然后抓取 trace；最后把症状映射到具体类别。它配套的 flaky-taxonomy.md 提供了明确的诊断分支和修复模式，包括缺少 await、共享状态、只在 CI 出现的 viewport/font/timezone 差异、浏览器崩溃，以及与 worker 相关的不稳定问题。

安装前需要了解的限制

这不是一个通用 bug 修复器。它的范围限定在 Playwright 测试，并且默认 agent 能查看你的测试文件、运行 Playwright 命令，以及读取 trace、截图、日志或 CI 失败文本等输出。它没有辅助脚本，因此价值主要来自调试流程和 taxonomy，而不是自动化工具。

如何使用 fix skill

fix 安装方式与优先查看的文件

在兼容的 skills 环境中使用以下命令安装：

npx skills add alirezarezvani/claude-skills --skill fix

安装后，先阅读 SKILL.md 了解执行流程，再打开 flaky-taxonomy.md 查看决策树和常见修复方式。仓库路径是 engineering-team/playwright-pro/skills/fix，有用的源文件刻意保持很小：没有隐藏脚本、规则或需要配置的 metadata 文件。

fix skill 需要哪些输入

为了获得更好的结果，至少提供以下输入中的一项：

• 测试文件路径，例如 e2e/login.spec.ts
• 精确的测试名称或 --grep 字符串
• 失败消息、stack trace 或 assertion error
• 失败发生在本地、CI，还是两者都会发生
• 是否单独运行能通过，但在完整 suite 中会失败
• 如果有，提供 trace、截图、视频或 CI artifact 路径
• 相关 Playwright 配置，尤其是 workers、retries、projects、viewport、timezone 和 base URL

较弱的 prompt：“Fix my flaky checkout test.”

更好的 prompt：“Use the fix skill for Debugging e2e/checkout.spec.ts, test should submit paid order. It passes locally alone, fails in CI about 30% of runs, and the failure is Timeout 5000ms exceeded waiting for getByRole('button', { name: 'Pay' }). CI uses 4 workers and retries=2. Suggest the reproduction commands, likely category, and minimal code/config changes.”

实用的 fix 调试流程

从精确的失败文件开始：

npx playwright test <file> --reporter=list

如果它通过了，把它视为可能的 flaky 问题，并运行 burn-in：

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

如果问题只在并发下出现，使用并行参数运行：

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

然后收集 trace 证据：

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

在改代码之前，先让 agent 对失败分类。预期类别包括 timing/async、test isolation、environment 或 infrastructure。这样可以避免常见的错误修复方式，例如随意添加 waitForTimeout、提高全局 timeout，或用 retries 掩盖真实的 race。

让结果更好的 prompt 模板

使用能把证据和请求分开的 prompt：

“Use the fix skill. Diagnose before changing code. Test: <file> / <test name>. Reproduction result: <passes/fails command>. CI/local behavior: <details>. Trace or screenshot: <path or summary>. Current suspicion: <optional>. Please categorize using flaky-taxonomy.md, explain the evidence, propose the smallest safe fix, and list the command to verify it.”

这种结构能帮助 skill 产出可验证的调试计划，而不是凭猜测给出 patch。

fix skill 常见问题

fix 只适用于 flaky tests 吗？

不是。fix skill 既能处理稳定复现失败的 Playwright 测试，也能处理间歇性失败。对于确定性失败，它仍然会从复现和 trace 抓取开始。对于间歇性失败，它会增加 burn-in 和 parallel-worker 检查，用来暴露 timing、isolation 或 infrastructure 模式。

什么时候不该使用这个 skill？

不要把它作为单元测试、后端集成测试、没有 Playwright 覆盖的生产 bug，或大范围应用架构调试的主要工具。它也许能提供一些通用思路，但它的命令、taxonomy 和示例都是为 Playwright 端到端测试编写的。

它和 Playwright trace viewer 有什么区别？

Trace viewer 展示发生了什么；fix skill 帮你判断这些现象意味着什么。例如，一个元素缺失可能表示 async race、前一个测试泄漏的状态、CI viewport 差异，或网络依赖问题。taxonomy 会把 artifacts 转化为诊断路径和建议的修复类型。

fix 适合新手吗？

适合，前提是用户能运行 Playwright 命令并提供错误信息。新手会受益于明确的命令顺序和分类表。不过，这个 skill 不能替代基础项目配置知识：Playwright 必须已经安装，测试 suite 必须可以运行，并且 artifacts 必须能够访问。

如何改进 fix skill 的使用效果

为 fix 提供更强的失败证据

最重要的改进是提高输入质量。提供已经尝试过的精确命令及其结果。“Fails in CI” 不如 “fails in CI with 4 workers, passes locally with one worker, fails locally with --fully-parallel --workers=4 --repeat-each=5” 有用。后面这个细节能把方向指向 isolation 或 parallelism，而不是泛泛的 timing 问题。

避免常见的调试失败模式

不要在诊断前就要求 patch。常见的坏结果包括添加固定 sleep、提高全局 timeout、增加 retries，或在未确认原因的情况下重写 selectors。改代码前，要求 skill 明确说明类别、证据、最小修复方案和验证命令。

首次修复后继续迭代

应用建议的改动后，重新运行最小但有意义的验证命令。如果修复针对 timing，使用 burn-in。如果修复针对 isolation，对比单个测试与完整 suite 的表现。如果修复针对 CI environment，用更接近 CI 的设置复现，例如 Docker、workers、timezone、viewport 或 mocked network services。

为你的项目扩展 fix 指南

团队可以在 skill workflow 附近添加项目特定说明，以改善本地效果：常见 CI 设置、已知 flaky services、必需的 test data resets、标准 fixtures、mock 策略，以及首选 locator 约定。fix skill 在 taxonomy 与你仓库中的真实失败模式结合时效果最好。