治理 CI 里的 flaky test：从每月 40 次假失败到连续 6 周零误报的工程实践

现象与背景：假失败正在吃掉团队的信任

先给一组真实数字。我在一家做 B 端 SaaS 的团队做测试开发，负责一条跑 1200+ 个用例的 CI 流水线（Java 17 + JUnit 5 + Spring Boot 3.1，CI 用 GitLab Runner，2 台 4C8G 的 runner 并行）。

过去 3 个月，这条流水线每月出现 35~45 次"红了但重跑就绿"的假失败。一次假失败的成本是：

• 开发同学重新点 Run pipeline，平均等待 6 分钟（这条线全量跑 5 分 40 秒）；
• 期间他手上的 commit 无法合并，阻塞平均 8 分钟；
• 更隐蔽的代价是信任损耗——连续 3 次假失败之后，团队里开始出现"红了先点重跑"的肌肉记忆，真正的回归 bug 也被顺手重跑了。

我统计过：3 月份 41 次假失败里，有 2 次真 bug 被"重跑变绿"掩盖了，直到灰度环境才暴露。这是最贵的代价。

根因分析：flaky 不是"玄学"，是四类可归因的机制

把 41 次假失败逐条拉日志归类后，分布很集中：

| 类别 | 占比 | 典型表现 | |---|---|---| | 并发/时序 | 44% | 异步任务未完成断言就执行、@DirtiesContext 缺失导致用例间状态污染 | | 外部依赖 | 27% | 调第三方 mock server 偶发 503、时间戳用 LocalDateTime.now() 断言 | | 资源竞争 | 20% | 端口占用、临时文件残留、内存不足 OOM | | 数据假设 | 9% | 用例假设"我插入的第一条就是 id=1" |

机制上最关键的一点：CI runner 是多 job 并行的。两个 job 抢同一个 mock server 端口（我项目里是 9090），谁先抢到谁活，另一个就 Connection refused。这种失败在本地单机永远复现不了，只在 CI 高负载时出现——这就是为什么 flaky 几乎只发生在 CI。

具体做法：四步治理，可复现

第一步：量化基线，别凭感觉。 在 CI 日志里加一段统计（GitLab CI 的 after_script）：

# 统计本次 pipeline 各 stage 的失败次数与重试成功率
python3 ci_flaky_report.py \
  --project-id $CI_PROJECT_ID \
  --since "1 month ago" \
  --output flaky_report.json

报告输出每个用例的 failCount / totalRuns / firstPassRate，firstPassRate < 100% 的进 flaky 清单。

第二步：隔离，而不是重跑。

• 端口冲突：给每个 job 分配独立端口段，MOCK_PORT=$((9000 + CI_JOB_ID))，从源头消除竞争；
• 状态污染：给所有共享 ApplicationContext 的用例显式标注，并把会改全局状态的用例单独放一个 @DirtiesContext 的类；
• 时间依赖：把 LocalDateTime.now() 替换成注入的 Clock，测试里固定 Clock.fixed()。

第三步：重试只用于隔离，不用于放行。 GitLab 里给整个 job 加 retry: 2，但规则是：只有被标记为 flaky 的用例允许吃重试红利。用 JUnit 的 @RepeatedTest 配合一个 FlakyMarker 标签做白名单，非白名单用例失败即真失败，直接红。这一步逼着团队把每个 flaky 用例都登记在册、限期修复。

第四步：设 KPI，进迭代。 把"flaky 用例数"作为测试基建的指标写进迭代目标。我们定的是：每月新增 flaky ≤ 2，存量每月清零 20%。配合第一步的报告，每个 flaky 用例都有 owner 和到期日。

踩过的坑与反直觉之处

1. 重试次数调大不是解法，是遮羞布。 我们把 retry 从 1 调到 3 的那个月，假失败"消失"了，但真 bug 的漏报率从 2/41 涨到 5/38——重试掩盖的正是它本该暴露的东西。
2. 本地能复现的 flaky 反而更危险。 因为本地复现容易，大家倾向"多跑几次就过了"然后忽略；而 CI-only 的 flaky 因为难复现，反而被认真排查。
3. @DirtiesContext 是最被低估的坑。 它会让 Spring 重新加载上下文，单个用例耗时从 200ms 涨到 3 秒。团队一度觉得"太慢"而到处删，结果状态污染又回来了。正确做法是精准标注 + 合并同类上下文，而不是全删或全加。
4. 别追求 100% 一次通过。 我们目标是 firstPassRate ≥ 99.5%，允许极少量 flaky 存在并用白名单隔离，而不是让任何人为了消灭最后一个 flaky 去删掉一个有价值的用例。

结论与可复用清单

治理 flaky 的本质不是"让它不失败"，而是让每一次失败都可归因、可追责、可修复。可复用清单：

• [ ] 建立 flaky 量化基线：统计 firstPassRate，<100% 进清单并指派 owner；
• [ ] 消除资源竞争：CI job 间用 CI_JOB_ID 派生独立端口/临时目录；
• [ ] 消除时序依赖：注入 Clock、异步任务改显式等待（awaitility 而非 Thread.sleep）；
• [ ] 状态污染：精准使用 @DirtiesContext，合并同类上下文；
• [ ] 重试做隔离而非放行：flaky 白名单 + retry: 2，非白名单失败即红；
• [ ] 设 KPI：每月新增 ≤ 2、存量清零 20%，写进迭代；
• [ ] 用真实漏报数复盘，警惕"重试掩盖真 bug"。

三个月后，这条流水线连续 6 周零误报，firstPassRate 稳定在 99.7%。团队"红了先重跑"的肌肉记忆也慢慢回来了——这次是回不来了。