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 能帮助我们分析异步逻辑、共享状态、时间和外部依赖，但它不能通过重试或降低测试标准来掩盖问题。

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