Codex 教程

用 Codex 生成测试

用 Codex 生成单元测试、集成测试和回归测试的完整指南，覆盖风险点分析、测试用例矩阵、Vitest 示例、Mock 边界、CI 验证和常见误区。

预计阅读: 5 分钟
最近更新: 2026/07/03
维护方式: 人工编辑

用 Codex 生成测试，适合为已有功能补覆盖、为 Bug 补回归用例、为重构前建立安全网。可靠测试应来自真实行为、风险点和可复现输入，而不是为了覆盖率拼数量。

测试生成的关键，是让 Codex 先读项目、列出风险、确认测试框架，再写最小可维护用例。这样得到的测试才会帮助团队发现回归，而不是制造一堆脆弱断言。

项目	说明
阅读时间	约 5 分钟
更新时间	2026-07-03
适合读者	开发者、独立项目维护者、需要让 Codex 为项目补测试的人
你会获得	风险分析方法、测试用例矩阵、可复制 Goal Prompt、Vitest 示例、Mock 外部 API 的边界和 CI 验证清单

使用场景

场景	推荐测试	Codex 要先确认什么	验证标准
修 Bug 后补回归	回归测试	失败输入、修复前行为、预期输出	旧逻辑会失败，新逻辑通过
工具函数或纯逻辑	单元测试	正常路径、边界值、错误输入	断言覆盖返回值和异常
API 路由	集成测试	请求方法、状态码、响应体、鉴权	不依赖真实外部服务
UI 行为	组件测试或端到端测试	用户动作、可见结果、无障碍状态	测用户路径，不测内部变量
重构前建安全网	针对公开接口的回归测试	当前行为、调用方、兼容边界	重构前后测试结果一致
外部 API 封装	单元测试加 smoke test	Mock 范围、环境变量、错误处理	默认 mock，真实请求单独运行

测试生成流程图

可复制 Goal Prompt

Goal: 为 [功能/模块/Bug] 补充可维护测试。

Context:
- 被测代码路径：[填写路径]
- 相关需求或 Bug：[填写链接或描述]
- 现有测试命令：[填写 npm test / npm run test / pnpm test 等]

请先读取：
- 被测代码和调用方
- 现有测试目录、测试框架和命名风格
- package.json / pyproject.toml / go.mod / README 中的运行说明
- AGENTS.md 或项目内约束文件

要求：
- 先列出风险点和测试用例矩阵，再写测试。
- 优先覆盖正常路径、边界条件、错误路径和回归场景。
- 不为了测试而大规模重构生产代码；确实需要小改动时先说明原因。
- 默认 mock 外部网络、文件系统、时间、随机数和第三方 API。
- 不写真实 API Key，不打印敏感日志。
- 运行相关测试命令，并报告通过、失败或无法运行的原因。

Done when:
- 新增测试能稳定运行。
- Bug 场景有回归用例。
- diff 中没有无关重构。
- 给出后续可进入 CI 的命令。

Codex 官方手册建议把任务写清目标、上下文、约束和完成条件。生成测试时，这些信息会直接影响质量：没有风险矩阵，Codex 往往只补正常路径；没有验证命令，测试就很难进入真实交付流程。

执行步骤

明确被测行为，而不是只说“提高覆盖率”。
让 Codex 读取现有测试和脚本，确认框架、断言库、命名习惯。
要求它列出风险点、输入样例、预期输出和需要 mock 的依赖。
先补最小测试，用公开接口验证行为，不直接锁死内部实现。
运行相关测试命令，记录失败日志，不用快照或跳过语句掩盖问题。
对 Bug 修复，确认测试在旧逻辑上会失败，在修复后通过。
把稳定测试接入 CI，真实 API smoke test 单独开关控制。

Codex 应该先读什么

文件或信息	目的	要求 Codex 输出什么
被测源码	理解公开接口、分支和副作用	可测行为列表
现有测试文件	沿用框架、命名和断言风格	推荐放置路径
`package.json` / `pyproject.toml` / `go.mod`	确认测试命令和依赖	实际可运行命令
README 或开发文档	复核启动、环境变量和约束	测试前置条件
AGENTS.md	遵守项目内长期规则	需要遵守的测试规范
失败日志或 Bug 描述	建立回归用例	复现输入和预期结果

测试用例矩阵

行为	用例	断言	是否 mock	验证命令
正常折扣计算	会员价格 100	返回 90	否	`npm test -- calc-total`
错误输入	价格为负数	抛出明确错误	否	`npm test -- calc-total`
API 封装	模型返回摘要文本	保留来源页码	是，mock 模型客户端	`npm test -- summarize`
网络失败	上游超时	返回可处理错误或重试	是，mock 请求层	`npm test -- retry`
重构保护	公开函数输入不变	重构前后结果一致	视依赖而定	`npm test -- public-api`
CI smoke test	环境变量齐全	最小请求可返回状态	真实请求单独运行	`npm run test:smoke --if-present`

这张表可以直接交给 Codex。重点不是表格本身，而是让每个测试都有行为、输入、断言和验证命令，避免“看起来有覆盖率，实际不防回归”。

示例：Vitest 单元测试

Vitest 官方文档展示了从 vitest 导入 test、expect、vi 等 API 的用法，也支持 .test.ts 这类 TypeScript 测试文件。下面的例子只演示断言形状；真实项目中，calcTotal 应从业务文件导入。

import { describe, expect, test } from 'vitest';

type DiscountInput = {
  price: number;
  coupon?: 'none' | 'member';
};

function calcTotal(input: DiscountInput) {
  if (input.price < 0) {
    throw new Error('price must be positive');
  }

  if (input.coupon === 'member') {
    return input.price * 0.9;
  }

  return input.price;
}

describe('calcTotal', () => {
  test('applies member discount', () => {
    expect(calcTotal({ price: 100, coupon: 'member' })).toBe(90);
  });

  test('keeps normal price without coupon', () => {
    expect(calcTotal({ price: 100, coupon: 'none' })).toBe(100);
  });

  test('rejects negative price', () => {
    expect(() => calcTotal({ price: -1 })).toThrow('price must be positive');
  });
});

让 Codex 写这类测试时，可以要求它解释每个用例覆盖的风险。异常断言要把函数调用包在回调里，否则异常会在断言前抛出。

Mock 外部 API 的边界

AI 应用的测试常常会碰到模型调用、Embedding、图片生成、文件读取、网络请求和时间戳。默认策略是：业务逻辑测试 mock 外部依赖；真实 API 只用于少量 smoke test。

import { expect, test, vi } from 'vitest';
import { summarizePdf } from './summarize-pdf';
import { callModel } from './model-client';

vi.mock('./model-client', () => ({
  callModel: vi.fn(),
}));

test('keeps source page number in summary', async () => {
  vi.mocked(callModel).mockResolvedValue({
    text: '第 3 页：收入增长。',
  });

  await expect(summarizePdf('report.pdf')).resolves.toContain('第 3 页');
  expect(callModel).toHaveBeenCalledTimes(1);
});

Mock 的边界应贴近外部世界：模型客户端、HTTP 层、文件系统、时间和随机数都适合 mock；纯业务函数不需要 mock。不要 mock 掉被测对象本身，否则测试只会证明 mock 会返回你写进去的结果。

API smoke test 的安全写法

如果测试涉及 OpenAI-compatible API，优先 mock SDK 响应。确实需要 smoke test 时，把真实请求放在单独命令里，并通过环境变量读取配置。

OPENAI_BASE_URL=https://api.ofapp.cn/v1
OPENAI_API_KEY=sk-xxxx
npm run test:smoke --if-present

在 OfApp.cn 场景中，OpenAI / Codex 生态的 Base URL 可以使用 https://api.ofapp.cn/v1。Key、模型、额度、价格和具体能力会随账户与控制台状态变化，请以 OfApp.cn 控制台或官方文档为准。

常见错误排查

错误	表现	修复
Codex 编造测试框架	命令不存在或依赖缺失	先读取项目配置，不凭空引入框架
用例只测正常路径	回归仍会漏	增加错误路径、边界值和历史 Bug 输入
依赖真实 API	CI 偶发失败或成本不可控	mock 外部调用，smoke test 单独运行
断言内部实现	重构后大量误报	改为验证公开接口和用户可见行为
快照过大	diff 难审、误报多	只快照稳定结构，关键字段用明确断言
通过跳过测试修失败	CI 变绿但问题仍在	删除无意义跳过，定位失败根因

注意事项

风险	处理方式
覆盖率好看但无用	优先覆盖高风险行为、边界和历史 Bug。
引入新框架过重	先使用项目已有测试工具，引入依赖前说明收益和成本。
测试污染环境	清理临时文件、数据库、缓存和全局状态。
异步测试不稳定	控制时间、重试、网络和随机数，避免真实等待。
日志泄露密钥	对 Authorization、Cookie、API Key、用户数据做脱敏。
生产代码被顺手重构	把可测试性小改动和业务重构分开说明。

资料来源

Vitest 官方文档：测试文件、expect 断言和 vi.mock 等用法。
OpenAI Codex 官方手册：Codex 任务说明、项目指令和验证流程建议。
OfApp.cn API 文档：Base URL、API Key、Codex / OpenAI 生态接入入口和示例。
OfApp.cn 天才游乐场：聊天、图片和参数调试入口。

常见问题

Codex 生成的测试越多越好吗？

不是。测试应覆盖真实风险和行为。大量脆弱测试会增加维护成本，也会让团队对失败信号失去信任。

没有测试框架怎么办？

先让 Codex 识别项目语言、包管理器和已有脚本，再提出最小测试方案。引入新依赖前，要确认团队接受维护成本。

可以让 Codex 修改生产代码以便测试吗？

可以做小范围可测试性调整，例如拆出纯函数、注入依赖或暴露稳定接口。但 Codex 应先说明理由，并避免借测试之名重写核心逻辑。

UI 测试和单元测试怎么选？

纯逻辑优先单元测试，跨组件行为用组件测试，关键用户路径再用端到端测试。不要用端到端测试覆盖所有细节，否则运行慢、失败也难定位。

测试需要真实 API Key 怎么办？

默认不需要。业务逻辑测试应 mock API 响应。确实要验证真实链路时，用环境变量或 CI Secret 注入 Key，并把 smoke test 和常规测试分开。

生成测试后一定要进 CI 吗？

稳定、快速、无真实密钥依赖的测试应进入 CI。慢测试、真实 API smoke test 和需要人工数据的测试，可以放在单独命令或受控环境里运行。

用 Codex 修 Bug：为修复补回归测试。
用 Codex 重构项目：重构前先建立测试安全网。
用 Codex 配置 GitHub 工作流：让测试进入 CI。
用 Codex 排查报错：定位构建、测试和运行时失败。
Codex 本地项目使用指南：让 Codex 读取项目结构、脚本和约束。
Codex Goal 提示词模板：把测试任务写成可验证目标。
AI 辅助开发：把测试、修 Bug、重构和提交串成开发流程。
错误重试示例：测试 API 重试和退避逻辑。

带走什么

用 Codex 生成测试的价值在于快速建立风险覆盖。关键是先定义行为和风险点，再让测试证明功能正确、Bug 不回归、外部依赖被隔离。好的测试不会炫技，它会在未来某次改动里安静地拦住错误。