编程 Agent 的 Flaky Test 治理：复现、归因与隔离恢复

同一提交有时绿、有时红，并不意味着“再跑一次就好”。它可能暴露共享状态、竞争条件、时区依赖、未等待异步任务、资源不足或外部服务波动。编程 Agent 若被奖励为尽快恢复绿色，最容易增加重试、延长等待或直接跳过测试，把真实缺陷藏进主干。

治理的第一条规则是区分“产品回归”和“测试不稳定”。第一次失败仍按真实失败处理，保留完整证据；只有同一提交、同一输入在受控重复中出现通过与失败，才可标记为 flaky 候选。普通调试方法可参考AI 辅助调试，但隔离权限和退出条件必须由平台控制，不能交给 Agent 自行决定。

首次失败就采集可重放上下文

CI 为每次测试运行分配 runId，记录 commit SHA、容器镜像 digest、Node 与测试框架版本、CPU/内存限制、并发度、时区、locale、随机种子、分片、测试顺序和外部依赖版本。敏感环境变量只保留键名与密钥版本，不输出值。日志、截图、trace、网络错误和资源曲线作为有保留期限的工件。

以 Node 22.18.0、pnpm 10.14.0 和精确锁文件为例，复现作业从原提交启动隔离容器：

pnpm install --frozen-lockfile
node --version
pnpm --version
sha256sum pnpm-lock.yaml
pnpm exec playwright test tests/checkout.spec.ts \
  --project=chromium --workers=1 --repeat-each=30 --retries=0

--retries=0 很重要：复现阶段需要看原始失败频率。先用原并发和顺序复跑，再分别固定单 worker、随机顺序、受限 CPU、慢网络和不同时区，以定位触发条件。服务端测试则冻结数据库快照、消息队列起点和伪时钟。跨服务因果链可用分布式追踪关联，但正文与凭据应脱敏。

失败指纹不能只有测试名。它由首个业务栈帧、异常类型、规范化错误信息、关键断言和阶段组成；去掉时间戳、临时端口等噪声。相同测试出现两个指纹时按两个问题处理，避免把新产品回归并入旧 flaky 工单。

用证据决定是否隔离

候选测试至少在同一 SHA、输入和环境上执行 20 次，并观察到一次通过和一次相同指纹失败。最近 50 次主干运行中出现 3 次相同指纹的非连续失败只能把它送入候选队列；隔离前仍要选定一个失败 SHA，在冻结环境中重放出通过与失败。涉及鉴权、计费、数据删除和迁移的测试即使满足条件，也不能仅靠隔离放行，必须提供覆盖同一风险的稳定替代门。

隔离记录包含 owner、原因假设、首次与最近失败、失败指纹、复现命令、关联工单、替代覆盖和到期时间，最长 7 天。测试仍在单独队列每个提交运行，只是不重复阻断同一已知指纹；若出现新指纹，立即按新回归阻断。仓库中的 skip、only 和重试配置变更由策略检查拦截，未经隔离记录不能合并。

Playwright 将首次通过、重试后通过和持续失败区分开，这些状态应完整上报。重试后通过计为 flaky 事件，而不是绿色成功；自动重试最多一次用于收集分类证据，不得掩盖发布门。整体补丁证据仍遵循编程 Agent 的改动验证门。

修根因，而不是调大等待时间

常见根因有四组。共享状态问题通过每例独立数据、唯一命名空间和清理校验修复；竞态问题用事件或条件等待替代固定 sleep；时间随机问题注入时钟与种子；外部依赖问题用契约稳定的本地替身，并保留单独的真实集成门。资源饥饿则应校准并发和容器配额，不要无限扩大测试超时。

Agent 提交修复时必须带最小失败样本和修复前后对比。例如原 SHA 在触发配置下 7/100 失败，补丁连续 500/500 通过，且在默认配置跑完整领域套件。只把 waitForTimeout(500) 改成 5000 不算修复，因为它没有建立被等待的业务条件。

若无法本地复现，保留线上工件并用固定环境扩大采样，最多两轮自动假设验证。Agent 不得一次改动多个独立同步点来碰运气；每轮记录假设、单一干预和结果。预算耗尽后转人工，测试维持隔离或阻断，不生成未经证据的“可能已修复”结论。

恢复门要比隔离门更严格

解除隔离前，修复提交在历史触发条件下连续 500 次无同指纹失败，默认配置连续 200 次通过，相关领域套件通过，且至少观察 3 次主干运行。计数、种子和工件必须绑定修复 SHA。到期仍未满足就升级负责人和发布风险，不能自动续期。

恢复时还要撤销为诊断临时加入的串行执行、额外日志和资源放宽，再按生产 CI 的并发、分片与测试顺序重跑。否则团队证明的只是诊断环境稳定，原来的触发条件可能仍然存在。

团队追踪 flaky 测试数量、失败率、平均隔离时长、过期项、重试消耗分钟数和新指纹数，并按根因复盘。还可用Agent 回放评测保存触发事件顺序。目标不是让 CI 看起来一直绿色，而是把每次不确定失败变成可复现证据，暂时隔离时仍守住行为，并确保隔离最终退出。