debug-fix-failed-flaky-autotests

调试并修复失败的自动化测试

诊断失败的自动化测试并进行有针对性的修复。 按顺序完成以下四个步骤。 详细修复方法和代码示例：references/DEBUGGING_QUICK_REFERENCE.md。

第 1 步：分析失败原因

• 确定测试框架。框架决定调试工具：
  • Playwright：CLI 调试、跟踪查看器、MCP 快照。
  • CodeceptJS：--steps 模式、CDP 检查。
  • Cypress：devTools、失败时截取屏幕截图。
  • WebdriverIO：Selenium 日志。
• 对错误分类：
  • 定位器（元素缺失或无法访问）。
  • 时序（超时或竞态）。
  • 断言（预期值 ≠ 实际值）。
  • 流程（导航、前置条件）。
  • 基础设施（CI、浏览器、网络）。
• 最后给出假设：根本原因 + 修复类别。

第 2 步：检查并诊断

• 检查 DOM：
  • Playwright：page.locator('selector').evaluate(el => el.outerHTML)。
  • CodeceptJS：I.executeScript(() => document.querySelector('.selector').outerHTML)。
  • MCP 快照：捕获复杂元素的实时 DOM 状态。
• 查看控制台和网络日志：
  • 控制台：page.on('console', msg => console.log(msg.text()))。
  • 失败的请求：page.on('requestfailed', r => console.log(r.failure().errorText))。
• 分析跟踪记录（Playwright）：npx playwright show-trace trace.zip。
  • 检查点击、导航和网络请求的时序与顺序。

第 3 步：应用修复

按优先顺序修复：定位器 → 时序 → 断言 → 流程。

• 定位器：使用稳定的选择器（data-testid → aria-label → role → id → text → CSS/XPath）。
  • 重新获取失效的元素，将隐藏元素滚动到视图中；有多个匹配项时使用 .first()。
• 时序：使用框架原生的等待方式（waitFor、waitForNavigation、waitForLoadState('networkidle')）。
  • 不要使用 sleep(5000) 或 wait(2) 这类硬编码休眠。
• 断言：使用包含匹配或正则表达式，以提高匹配灵活性。
  • 根据测试规范验证预期值，而不是依赖假设。
• 流程：确保满足前置条件（登录、导航顺序、测试数据）。
  • 将测试状态与之前的运行隔离。

各类别的修复前后示例：references/DEBUGGING_QUICK_REFERENCE.md。

第 4 步：验证并提高稳定性

重新运行测试：

npx playwright test path/to/test.spec.ts
npx codeceptjs run path/to/test.js

满足以下条件时，测试即为稳定：

• 连续通过 2 次。
• 使用具有韧性的定位器。
• 正确等待动态内容。

**总共最多尝试修复 3 次。**若 3 次尝试后仍失败：停止操作，记录已尝试的方法，并向用户寻求指导。

记录修复内容：根本原因、应用的修复、验证结果。

MCP 调试工具（可选）

当常规修复无效、界面复杂（下拉菜单、模态框、动态内容）或需要检查实时 DOM 时，使用 MCP：

• Playwright MCP：实时快照、元素计数，以及每次操作后的 DOM 检查。
• CodeceptJS MCP：基于 CDP 的检查，以及用于实时调试的 --steps 模式。

与用户交互

有疑问时询问：

❓ Which element should I target for this action?

Options:
1. Submit button (data-testid="submit")
2. Save button (aria-label="Save")
3. Other (specify)

报告进展：

🔍 Analyzing failure...
  - Error: Element not found
  - Context: Login test, line 42

🔧 Applying fix...
  - Issue: Selector too broad
  - Fix: Using getByRole('button', { name: 'Login' })

✅ Test passed! (Run 1/2)