Codex测试偶发失败排查与修复流程

自动化测试有时候跑着跑着就过了，有时候又莫名其妙地挂了，这种问题在业内有个专门的称呼——Flaky Test。相比那些稳稳报错的测试，这类偶发失败更难排查，因为它可能跟异步逻辑、时间戳、随机数据、测试顺序，甚至是外部服务的状态有关。今天这篇，就来聊聊怎么用 Codex 收集证据、定位不稳定因素，再通过重复跑和 Git Diff 来验证修复是否真的有效。

在项目开发中，最让人头疼的测试不是那种“每次都失败”的，而是下面这种：

第一次运行：通过
第二次运行：失败
第三次运行：通过

这种偶发失败会严重拖累 CI/CD 的稳定性，而且很容易让团队误以为是构建平台出了问题。

有些开发者遇到这种情况，会直接丢给 Codex 一句：

把这个测试改到可以通过。

实话实说，这种要求挺危险的。Codex 很可能会通过增加重试次数、延长等待时间，或者降低断言标准来让失败暂时消失，但根因根本没解决。

一、先确认是不是 Flaky Test

怎么判断呢？不妨先试试把同一个测试重复跑几遍：

npm run test -- user-profile.test.ts

或者用循环连续执行：

for i in {1..20}; do
  npm run test -- user-profile.test.ts || break
done

跑的时候，注意记录以下几点：

• 失败出现的频率有多高；
• 是不是只在 CI 环境下才失败；
• 单独跑的时候能不能通过；
• 跟其他测试一起跑的时候会不会失败；
• 每次失败的日志是不是完全一样；
• 跟执行顺序有没有关系。

把收集到的信息交给 Codex，可以这样问：

当前测试连续运行 20 次，其中失败 4 次。

单独运行通常通过，
与完整测试集一起运行时更容易失败。

请先分析，不要修改测试。

输出：

1. 最可能的不稳定因素；
2. 如何验证每个原因；
3. 需要检查哪些文件；
4. 最小修复方案；
5. 如何证明问题已经解决。

二、重点排查这五类原因

1. 异步操作没有等待完成

最常见的情况是：页面还在拼命加载数据，测试这边就已经开始等着检查结果了。比如：

render(UserProfile);

expect(screen.getByText("张三")).toBeInTheDocument();

更稳妥的做法是等待元素出现：

expect(
  await screen.findByText("张三")
).toBeInTheDocument();

但要注意，不能简单地把所有等待时间都拉长。真正需要确认的是，测试是否在等待明确的业务结果。

2. 测试之间共享状态

某个测试修改了全局变量、缓存或 Mock，完事儿却没有清理，结果影响了后面的测试。

重点检查这几个地方：

• localStorage；
• 全局状态管理；
• 数据库测试数据；
• Mock 请求；
• 单例对象；
• 环境变量；
• Fake Timer。

建议在每个测试结束之后，把状态恢复原样：

afterEach(() => {
  localStorage.clear();
  vi.clearAllMocks();
  vi.useRealTimers();
});

3. 依赖真实时间

如果测试跟当前日期、时区或者倒计时有关，那在不同时间、不同环境中跑，结果很可能不一样。

举个例子：

const today = new Date();

可以在测试里把时间固定下来：

vi.useFakeTimers();
vi.setSystemTime(new Date("2026-07-23T10:00:00Z"));

这么一来，本地和 CI 环境执行时，结果就是一致的。

4. 使用了随机数据

测试里直接上随机数、随机用户名、随机订单状态，结果根本没法复现。

不建议这么写：

const quantity = Math.floor(Math.random() * 10);

更推荐用固定输入，或者至少把随机种子记录下来：

const quantity = 3;

记住，测试的目标是验证确定行为，而不是每次制造不同的条件。

5. 依赖外部服务

如果测试直接请求真实的 API、数据库或者第三方服务，网络延迟和服务状态都会影响结果。

更稳定的做法是：

• 单元测试使用 Mock；
• 集成测试使用独立的测试环境；
• 外部服务设置明确的超时时间；
• 测试数据要能重复创建和清理；
• 把外部依赖的测试跟普通单元测试分开。

三、别用重试来掩盖根因

有些 CI 平台支持失败后自动重试，这可以作为临时保护，但不能代替真正的修复。

一个测试重试三次后通过了，这只能说明它依然不稳定。

需要警惕的几种“修改”包括：

增加等待时间；
降低断言标准；
跳过失败测试；
设置多次重试；
捕获异常后不处理。

可以让 Codex 帮忙审查一下：

请检查当前修复是否只是隐藏 Flaky Test。

重点确认：

1. 是否增加了无依据的延迟；
2. 是否降低了断言；
3. 是否加入重试但没有修复根因；
4. 是否遗漏状态清理；
5. 是否仍依赖真实时间或外部服务。

四、修复时坚持最小范围

假设问题出在用户状态没有清理，那这次修改只需要涉及：

用户状态测试；
测试初始化文件；
相关 Mock。

不应该顺手把整个用户模块重构一遍。

可以明确告诉 Codex 允许修改的范围：

允许修改：

- tests/user
- tests/setup.ts
- 用户状态相关 Mock

禁止修改：

- 生产业务逻辑；
- 路由配置；
- 权限规则；
- package.json；
- 无关测试文件。

如果确认是生产代码本身存在竞态条件，那再单独建立一个业务修复任务。

五、修复之后怎么证明它稳定了？

一次测试通过，说明不了什么。Flaky Test 就像幽灵，你得证明它真的被赶走了。

建议完成三层验证。

第一层：重复运行当前测试

连续执行 20 到 50 次，确认不再出现偶发失败。

第二层：跟完整测试集一起跑

npm run test

检查是否存在测试顺序依赖。

第三层：在 CI 环境里验证

确认在 Linux、不同 Node.js 版本，或者并行执行时，结果依然稳定。

同时跑一下：

npm run type-check
npm run lint
npm run build

最后检查一下：

git status
git diff --stat
git diff

确认没有通过删除测试、放宽断言，或者修改无关文件来获得“稳定”。

六、让 Codex 输出测试修复报告

任务完成后，可以要求 Codex 输出一份完整的修复报告：

请输出 Flaky Test 修复报告：

1. 问题现象；
2. 失败频率；
3. 根本原因；
4. 修改文件；
5. 修复方式；
6. 重复运行结果；
7. 完整测试结果；
8. 仍然存在的风险。

举个例子：

## 根本原因

测试使用 Fake Timer 后没有恢复真实时间，
导致后续用户状态测试的超时逻辑异常。

## 修复内容

- 在 afterEach 中恢复真实时间；
- 清理用户状态和 Mock；
- 补充测试顺序验证。

## 验证结果

- 当前测试连续运行 50 次：全部通过
- 完整测试集：通过
- 类型检查：通过
- 项目构建：通过

七、什么时候考虑升级到 Pro？

偶尔分析一个失败的测试，现有的方案通常够用。

但如果每天都需要 Codex 来做这些事情：

• 阅读大量 CI 日志；
• 重复运行测试；
• 分析异步和竞态问题；
• 修改多个测试与业务文件；
• 连续处理多轮失败结果；
• 同时维护多个仓库。

那任务就会形成一条很长的调试链路。

这种情况下，应该先通过限定测试范围、固定时间、清理共享状态和拆分任务来减少无效消耗。如果工作流已经优化，但测试分析、修改和重复验证仍然经常因为使用限制而中断，那就可以重新评估一下是否升级到 Pro 方案。

对于长期把 Codex 用在测试、调试和项目交付上的开发者来说，Pro 更适合持续推进多轮工程任务，可以减少在问题还没验证完成时，反复恢复上下文的成本。

总结

Flaky Test 的难点不在于让它“这一次通过”，而在于证明它以后能稳定通过。

更可靠的处理流程是：

记录失败频率 → 定位不确定因素 → 最小范围修复 → 重复运行验证 → 完整测试与 CI 检查。

Codex 能帮我们分析异步逻辑、共享状态、时间和外部依赖，但它不能通过重试或者降低测试标准来掩盖问题。

只有测试结果可重复、失败原因可解释、修改范围可审查，才算真正完成修复。