测试不稳定时用运行时自愈与隔离管理恢复可信测试套件

当测试在 CI 中偶发失败、定位器失效或数据过期时，对单个测试做可观测、可评审的运行时自愈与隔离。

适用场景

解决思路

1. 先检查 `.agents/qa-project-context.md`，跳过其中已回答的已知易碎区域、选择器策略与 CI 环境问题。
2. 评估当前 flaky 率：查看近 30 天 CI 失败统计，低于 2% 健康，2-5% 需关注，高于 5% 正在侵蚀团队信任。
3. 确定痛点集中处（定位器、时序、测试数据、环境），未知时先做埋点与分类。
4. 明确当前选择器策略（data-testid、混合 CSS/role、无策略），作为稳定性评分基线。
5. 明确当前 flaky 处理方式（重试祈祷、跳过遗忘、结构化流程），决定需增加多少流程。
6. 明确 CI 运行环境（固定机器还是不同 runner、资源是否稳定），用于区分环境问题与测试问题。
7. 明确测试数据策略（共享数据库、每测试 fixture、工厂播种、外部服务），决定是否适用数据自愈。
8. 遵循预防优先：写健壮测试成本 1x，调查 flaky 成本 10x，失去团队信任成本 100x。
9. 保证自愈可观测可评审：每次自动修复产出证据（什么坏了、试了什么、什么生效、置信度），禁止静默修复。
10. 先分类再修复：时序问题与数据依赖问题的修复方式完全不同，错误诊断会浪费精力并恶化问题。
11. 把 flaky 测试当作 bug：要么是测试 bug（修测试）、应用 bug（修应用）、环境问题（修环境）。
12. 把可靠性当指标跟踪：测量 flaky 率、平均修复时间、隔离时长、选择器稳定性。
13. 按自愈光谱渐进：先做健壮定位器（Level 1），再加回退策略（Level 2），再做环境感知自愈（Level 3），最后做置信度评分自动修复（Level 4），未掌握 Level 1 前不要跳到 Level 4。
14. 使用多属性选择器：用 `multiAttributeLocator(page, { testId, role, name, nearText })` 组合多个信号，内部从最具体到最宽松尝试组合（testId+role+name → testId → role+name → text → nearText+role），返回首个可见匹配，而非简单回退链。
15. 定位器失败时用 DOM 相似度/邻居上下文匹配作为修复候选：父容器+标签+类型、前置 label、邻近文本上下文，并按置信度评分，而非运行时回退。
16. 对每个选择器按 0-5 分评分以排定重构优先级：5=`getByTestId`，4=`getByRole`，3=`getByLabel`，2=`getByText`，1=CSS 类组合，0=XPath 结构路径。
17. 目标套件平均分 >= 3.5，每月审计，优先修复 0 分和 1 分选择器，并把每个定位器分数输出到 `selector-stability.md` 或 CI 步骤以验证平均值。
18. 按类别分类 flaky：Timing、Data dependency、Environment、Order dependency、Time sensitivity、Visual rendering、External service，每类对应不同修复方向。
19. 用分类决策树：先问单独运行是否通过（是→顺序/数据依赖），再问 CI 是否比本地更常失败（是→时序/环境），再问是否特定时间失败（是→时间敏感），再问是否涉及截图（是→视觉渲染），再问是否调用外部 HTTP（是→外部服务），否则默认时序问题。
20. 环境感知自愈：动作失败时先打 `/api/health`，后端不健康（5xx/超时）则指数退避重试并诊断为 `backend_down`，后端健康（2xx）则是真实 UI/测试失败，不重试。
21. 返回结构化诊断 `{ success, diagnosis: 'backend_down' | 'ui_failure' | 'backend_slow_recovered' }`，用于喂给 flaky 分类。
22. 检测资源争用：加载 `about:blank` 若 > 2s（基线 < 500ms）说明 runner 过载；打 `/api/health` 若 > 5s（基线 < 1s）说明后端承压；任一失败则归类为环境问题并标注，不计入 flaky 率。
23. 数据自愈：识别常见数据失败模式——401 过期 token（在 fixture 中重新生成）、404 记录被删（测试前重新播种）、409 唯一性冲突（每次运行生成唯一标识）、缓存过期（setup 中清缓存）、429 配额超限（重置配额或用专用测试账号）。
24. 构建自愈 fixture：验证→修复→使用→清理，用 `testInfo.testId` 生成每测试唯一标识，修复时写入 `testInfo.annotations` 以便观测，在 fixture 的 post-use 块中清理（而非 `afterEach`）以保证失败时也清理。
25. 可观测修复流程：失败检测 → 生成候选修复 → 计算置信度（0.0-1.0）→ 产出证据 diff → 应用审批策略 → 意图保真检查 → 若意图保真下降则回滚。
26. 按六维加权计算置信度：匹配特异性 0.30（testId=1.0、role=0.9、text=0.7、context=0.5、CSS=0.3）、元素可见 0.15、同父容器 0.15、同元素类型 0.15、文本相似度 0.15（Levenshtein 比率）、属性重叠 0.10（Jaccard）。
27. 按半开区间应用阈值：>= 0.9 自动应用并记录批量评审；0.7-0.89 在隔离中应用并标记单独评审；0.5-0.69 不应用，开 PR 附证据评审；< 0.5 丢弃，需人工调查。
28. 每次修复产出证据记录：测试文件、测试名、失败类型、原定位器、候选替换（含置信度、证据字符串、意图保留标志）、选中候选、时间戳、审批路径、回滚触发条件，以及修复运行的 `screencast.webm` 录像（Playwright 1.59+ `page.screencast` 配 `showActions`）。
29. 做意图保真检查：元素类型变化（button→a）、ARIA role 变化（button→link）、表单 action 变化（指向不同端点）均视为意图未保留并回滚；同 tag、role、form action 则保留修复。
30. 决定自建还是采购：不想自养置信度评分修复器时交给厂商；需要本地/气隙部署、显式 AI prompt 审计轨迹或跟踪器无法表达的隔离逻辑时自建。
31. Selenium/Selenide/Robot Framework 套件用 Healenium 作为专用自愈层；Playwright 的 agent 驱动自愈用 Playwright MCP；托管平台可选 Trunk Flaky Tests、CloudBees Smart Tests（原 Launchable）、Datadog Test Optimization（原 Test Visibility）。
32. 隔离管理：给 flaky 测试打 `@quarantine` 标签并附 annotation（含日期与 ticket 链接），在 `playwright.config.ts` 中分 `stable`（grep 排除 @quarantine）与 `quarantine`（grep @quarantine，retries: 3）两个 project。
33. CI 中把 `--project=stable` 作为阻塞步骤，`--project=quarantine` 配 `continue-on-error: true`，确保隔离项目永不阻塞流水线。
34. 执行隔离生命周期：DETECT → TAG（附 ticket 与日期）→ ISOLATE → DIAGNOSE → FIX → VERIFY（`--repeat-each=50` 零失败）→ RELEASE（移除标签并记录修复）。
35. 遵守隔离卫生规则：最长隔离 14 天，到期修复或删除；每条隔离都有 ticket 链接；每周评审；隔离规模超过 5% 说明系统性问题需改流程。
36. 避免反模式：静默替换选择器、把重试当修复、永久禁用 flaky 测试、把所有 flaky 一视同仁、用 `waitForTimeout` 当稳定修复、无观测的自愈、在写稳定测试前过度工程化自愈、无隔离过期。
37. 用条件等待替代 `waitForTimeout`：`await expect(page.getByRole('table')).toBeVisible()` 或 `await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)`。
38. 处理失败模式：健康检查自身抖动导致误判 `backend_down` 时单独跟踪其 p99；修复录像导致产物膨胀时只在修复路径录制；自动修复准确率低于 80% 时提高自动应用下限且不跳过意图检查；隔离项目阻塞流水线时补 `continue-on-error`。
39. 验证：用 `npx playwright test <spec> --repeat-each=20 --workers=4 --trace=on` 复现 flake（必须至少失败一次）；修复后用 `--repeat-each=50 --workers=4` 要求 50/50 通过（含 CI 条件）；确认 `--project=stable` 排除 @quarantine 且 `--project=quarantine` 只跑它们；确认选择器审计输出每个定位器分数与套件平均值。
40. 完成标准：每个 flaky 测试都被识别并按根因分类；每个 flaky 测试被隔离或修复，无静默重试；`selector-stability.md` 或 CI 报告列出每个定位器分数且套件平均 >= 3.5；flaky 率指标发布到 CI 仪表盘；每条隔离都有 ticket 引用且到期日 <= 14 天。

适用边界 · 注意事项

• 计划性 UI 重构后需要批量离线重写大量选择器时——应使用 selector-drift-recovery，本技能只在运行时修复单个测试。
• 需要把 CI 失败分类/聚类成 bug 报告时——应使用 ai-bug-triage。
• 尚未采用基本健壮定位器与正确等待模式前，不要先构建复杂的自愈框架。