Codex 100个真实案例 - 用AI自动生成API测试用例（接口测试全覆盖）

1. 接口测试用例为什么总是写不完如果你维护过一个中等规模的 REST 服务大概都经历过这种循环接口加了一个字段测试同学手工补几条用例过两周字段约束改了老用例还在跑但已经测不到新边界再后来接口数量涨到几十个测试文件比业务代码还长谁都不敢删也没人愿意补。问题不在于“不会写 pytest”而在于用例的输入空间是组合爆炸的。一个创建用户的接口name 有长度约束、email 有格式约束、age 有范围约束、role 是枚举光正常值、边界值、异常值三档乘起来就是几十条。手写意味着你要把 OpenAPI 文档里的minimum、maxLength、enum一条条翻译成断言这个过程机械、重复、极易漏。Codex 在这里的价值不是“帮你写代码”而是把规范文档当成唯一事实来源批量翻译成可执行断言。你给它一份 OpenAPI 3.0 的 YAML它按接口逐个生成 pytest 文件正常流程、必填缺失、边界值、类型错误、注入字符、响应 Schema 校验全部覆盖。我试过在一个 7 接口的用户管理服务上跑完整流程从规范到 48 条可执行用例中间只改了两次提示词。这篇按“能直接抄去用”的标准写先给可复制的 Codex 提示词模板再给 pytest requests 的用例骨架然后是 config.toml 配置片段最后是运行验证和覆盖率检查动作。适合后端开发、测试开发以及正在把接口测试接入 CI 的团队。全程不需要你手写断言逻辑但需要你理解每一步在干什么否则报错时无从下手。2. 前置准备TaoToken 接入与 Codex 环境Codex 这类编码代理要稳定跑长任务模型调用的稳定性比单次生成质量更关键。我这边统一走 TaoToken 的 API 网关好处是模型切换、密钥管理、用量统计在一个控制台里不用在多个平台之间倒腾配置。先拿 Key。打开控制台创建 API Key建议按项目建独立 Key方便后面排查是哪个任务在消耗额度控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite拿到 Key 之后本地环境需要 Python 3.10 和 Codex CLI。依赖装这几个就够python3 --version # 确认 3.10 以上 pip install pytest requests faker pyyaml pytest-html jsonschema pytest-json-report locustpytest-json-report容易被漏掉但后面统计通过率、生成摘要全靠它建议一开始就装上。Codex 的模型配置写在config.toml里把网关地址和 Key 填进去# ~/.codex/config.toml model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat然后设置环境变量别把 Key 硬编码进文件export TAOTOKEN_API_KEYsk-你的密钥 codex --version # 能打印版本就说明配置生效注意base_url只写到/api不要自己拼/v1之类的路径网关会按模型路由。如果 Codex 启动时报 401先检查环境变量是否在当前 shell 生效echo $TAOTOKEN_API_KEY看一眼。如果你更习惯在网页里先验证模型连通性可以先用模型对话跑一句简单请求确认 Key 没问题再进本地流程模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite3. 可复制配置从 OpenAPI 到 pytest 用例3.1 第一步让 Codex 生成 OpenAPI 规范测试用例的质量上限由规范文档决定。如果你们项目已经有 Swagger直接导出 YAML 跳过这步如果没有先让 Codex 造一份结构完整的规范作为后续所有生成的输入。提示词模板可直接复制创建一个用户管理系统的 OpenAPI 3.0 规范文件YAML 格式包含以下接口 1. POST /api/users - 创建用户姓名、邮箱、年龄、角色 2. GET /api/users - 获取用户列表分页、搜索、排序 3. GET /api/users/{id} - 获取单个用户 4. PUT /api/users/{id} - 更新用户信息 5. DELETE /api/users/{id} - 删除用户 6. POST /api/users/login - 用户登录 7. GET /api/users/{id}/orders - 获取用户订单 每个接口要有完整的请求参数、响应 Schema、错误码定义。 字段约束要写清楚minLength、maxLength、minimum、maximum、enum、format。 输出到 openapi.yaml。生成后重点检查三处required数组是否完整、数值字段有没有minimum/maximum、字符串字段有没有minLength/maxLength。这三类约束直接决定后面边界值用例能不能生成出来。缺了约束Codex 只能生成正常流程覆盖率上不去。3.2 第二步OpenAPI 解析器解析器的职责是把 YAML 里的$ref展开把 path/query/header 参数、请求体 Schema、响应状态码抽成结构化列表。提示词创建 api_parser.py解析 OpenAPI 3.0 的 YAML 文件提取 1. 所有接口的 URL、方法、参数 2. 请求体 Schema包括必填字段、类型、约束 3. 响应的预期状态码 4. 参数的边界值min/max/enum/minLength/maxLength 输出结构化的接口信息列表供测试生成器使用。中文注释。核心逻辑是递归解析$ref因为 OpenAPI 里 Schema 经常嵌套引用。解析完调用parse_all_endpoints()你会看到类似这样的概览API 概览: 用户管理系统 API 版本: 1.0.0 基础URL: http://localhost:8000 接口数量: 7 ------------------------------------------------------------ POST /api/users 创建用户 (0参, 有请求体) GET /api/users 获取用户列表 (5参, 无请求体) GET /api/users/{id} 获取单个用户 (1参, 无请求体) PUT /api/users/{id} 更新用户 (1参, 有请求体) DELETE /api/users/{id} 删除用户 (1参, 无请求体) POST /api/users/login 用户登录 (0参, 有请求体) GET /api/users/{id}/orders 获取用户订单 (2参, 无请求体)这一步跑通说明规范文档没有语法错误$ref都能解析。如果某个接口的参数量是 0 但你明明写了参数八成是参数写在了requestBody里而不是parameters检查一下规范结构。3.3 第三步Mock 数据引擎Mock 引擎按 Schema 类型生成三类数据正常值符合所有约束、边界值最小值、最大值、刚好越界、异常值类型错误、空值、注入字符。提示词创建 mock_engine.py根据 Schema 类型自动生成 1. 正常数据符合所有约束 2. 边界值数据最小值、最大值、空值、刚好越界 3. 异常数据类型错误、超出范围、格式错误、SQL注入、XSS 使用 Faker 生成逼真数据支持 email/date-time 等格式。中文注释。这里有个容易踩的坑边界值要生成“刚好越界”的那一条比如minimum: 1要同时生成1合法和0非法maxLength: 50要生成 50 字符和 51 字符。只生成合法边界测不出校验逻辑只生成非法值正常路径又没覆盖。两类都要有断言方向相反。3.4 第四步pytest 用例生成器这是核心步骤。生成器读解析结果为每个接口产出一个test_*.py文件内部按测试类型分方法。提示词创建 test_generator.py读取 OpenAPI 解析结果 为每个接口自动生成 pytest 测试文件包含 1. 正常流程测试happy path 2. 必填字段缺失测试 3. 边界值测试 4. 异常数据测试 5. 响应 Schema 验证 使用 pytest fixture 管理测试状态支持测试用例参数化。 输出到 tests/ 目录同时生成 conftest.py 和 pytest.ini。生成的conftest.py里放共享 fixture包括session复用连接池、base_url、auth_token以及一个created_userfixture 负责创建测试数据并在用例结束后清理。这个清理动作很重要否则跑几轮之后数据库里全是测试垃圾数据列表接口的分页断言会开始飘。生成的用例骨架长这样以创建用户为例class TestcreateUser: 测试: 创建用户 def test_正常请求_应返回成功(self, session, base_url): 正常流程测试Happy Path data {name: 测试用户, email: testexample.com, password: test123456, age: 25, role: user} resp session.post(f{base_url}/api/users, jsondata) assert resp.status_code 201, f期望 201实际 {resp.status_code}: {resp.text} pytest.mark.parametrize(missing_field, [name, email, password]) def test_缺少必填字段_应返回400(self, session, base_url, missing_field): 缺少必填字段应返回 400 错误 data {name: 测试用户, email: testexample.com, password: test123456} data.pop(missing_field, None) resp session.post(f{base_url}/api/users, jsondata) assert resp.status_code 400 pytest.mark.parametrize(case_name,test_data,expect_valid, [ (name_最短长度_2, {name: ab, email: ab.com, password: test123456}, True), (name_短于最小长度_1, {name: a, email: ab.com, password: test123456}, False), (age_最小值_1, {name: 测试, email: ab.com, password: test123456, age: 1}, True), (age_低于最小值_0, {name: 测试, email: ab.com, password: test123456, age: 0}, False), ]) def test_边界值(self, session, base_url, case_name, test_data, expect_valid): 边界值测试: {case_name} resp session.post(f{base_url}/api/users, jsontest_data) if expect_valid: assert resp.status_code 400, f{case_name}: 期望成功但返回 {resp.status_code} else: assert resp.status_code 400, f{case_name}: 期望失败但返回 {resp.status_code}参数化是这里的关键设计。pytest.mark.parametrize让一组边界值共享同一个测试方法失败时 pytest 会精确报出是哪条数据挂了而不是笼统地说“边界值测试失败”。排查效率差好几倍。3.5 第五步pytest.ini 配置生成器会顺手产出pytest.ini把测试发现规则和标记固定下来[pytest] testpaths tests python_files test_*.py python_classes Test* python_functions test_* addopts -v --tbshort --strict-markers markers slow: 标记慢速测试 smoke: 冒烟测试 security: 安全测试--strict-markers建议保留它能防止你把标记名拼错却毫无察觉。testpaths限定在tests/目录避免 pytest 误扫到虚拟环境里的第三方测试。4. 运行验证与覆盖率检查4.1 生成并运行执行生成器python test_generator.py输出会列出每个接口生成了多少条用例 生成 conftest.py 生成 test_createUser.py (12 个测试用例) 生成 test_listUsers.py (3 个测试用例) 生成 test_getUser.py (5 个测试用例) 生成 test_updateUser.py (8 个测试用例) 生成 test_deleteUser.py (5 个测试用例) 生成 test_loginUser.py (10 个测试用例) 生成 test_getUserOrders.py (5 个测试用例) 生成 pytest.ini 测试用例生成完成 接口数量: 7 运行命令: pytest tests/ -v --htmlreport.html7 个接口产出 48 条用例。跑起来pytest tests/ -v --htmlreports/full_report.html --self-contained-html--self-contained-html把 CSS 和 JS 内联进报告方便直接发给别人不用附带静态资源目录。4.2 覆盖率检查动作接口测试的“覆盖率”和单元测试的代码覆盖率不是一回事。这里要检查的是接口覆盖率和参数覆盖率接口覆盖率 已生成用例的接口数 / OpenAPI 中定义的接口总数。解析器输出的接口列表长度和tests/下test_*.py文件数对一下就知道正常情况下应该 1:1。参数覆盖率 每个接口被测试到的参数组合数 / 该接口参数空间。这个没法自动算但可以人工抽查打开某个接口的测试文件看parametrize里是否覆盖了每个有约束的字段。如果某个字段有enum但测试里没出现枚举值就是漏了。更实用的做法是让 Codex 帮你做一次覆盖率审计读取 tests/ 目录下所有测试文件对照 openapi.yaml 列出每个接口的测试覆盖情况 1. 哪些接口没有测试文件 2. 哪些字段的约束min/max/enum/format没有对应的测试用例 3. 哪些响应状态码没有被断言覆盖 输出一份缺口清单按接口分组。这份清单直接就是下一轮补用例的待办列表。4.3 性能测试补充功能用例跑通后如果接口有响应时间要求用 Locust 补一层压力测试。提示词创建 performance_test.py使用 locust 对 API 进行性能测试 包含用户创建、列表查询、详情查询三个场景。 配置并发用户数和请求频率。中文注释。运行方式# 带 Web UI浏览器打开 http://localhost:8089 locust -f performance_test.py --hosthttp://localhost:8000 # 无头模式适合 CI locust -f performance_test.py --hosthttp://localhost:8000 \ --users 50 --spawn-rate 5 --run-time 2m --headless --csvperf_report性能测试的断言标准和功能测试不同关注的是 P95、P99 响应时间和错误率不是状态码对不对。这两类测试建议分开跑别混在一个 pytest 会话里。5. 本篇常见报错排查5.1 生成用例全部 404最常见的原因是base_url指向的服务没启动或者路径前缀不对。OpenAPI 里的servers[0].url如果是http://localhost:8000而你的服务实际跑在http://localhost:8080/api/v1那所有请求都会 404。排查动作先手动 curl 一个接口确认服务可达再检查conftest.py里的BASE_URL是否和实际一致。如果服务有统一前缀改servers配置比改测试代码更干净。5.2 边界值用例误报如果age_最小值_1这条期望成功却返回 400先别急着改断言。检查两件事一是服务端校验逻辑是否真的允许age1二是请求体里其他字段是否合法。边界值用例只改一个字段其他字段用正常值填充如果正常值本身有问题所有边界用例都会连带失败。还有一种情况是minimum语义理解偏差。OpenAPI 的minimum: 1默认是包含 1 的如果服务端实现成了“大于 1”那age1确实该失败。这时候要改的是规范文档加上exclusiveMinimum: true然后重新生成用例。5.3 响应 Schema 校验失败jsonschema报ValidationError时先看错误信息里的path它会指出是哪个字段不符合。常见原因是服务端返回的字段类型和规范不一致比如规范写age: integer实际返回25字符串。这类问题正是接口测试要抓的别绕过断言去修服务端。如果确认服务端没问题是规范写错了改openapi.yaml后重新跑生成器。规范是唯一事实来源测试和服务端都应该向它对齐。5.4 测试数据污染导致列表断言失败列表接口的分页断言依赖数据总量如果前面的创建用例没有清理数据跑几轮之后total会一直涨分页断言就挂了。conftest.py里的created_userfixture 用yield加清理逻辑解决这个问题但前提是清理请求真的成功。如果删除接口本身有 bug清理会静默失败。排查动作在清理逻辑后加一行日志打印删除请求的状态码。如果经常是 404说明创建时拿到的 ID 有问题如果是 500那是服务端删除逻辑的 bug正好被测试抓出来了。5.5 Codex 生成中断或超时长任务生成到一半断掉通常是单次请求的 token 超限。解决办法是把生成拆成两步先让 Codex 输出接口清单和测试计划确认无误后再逐个接口生成测试文件。提示词里加一句“每次只处理一个接口输出后等待确认”能显著降低中断概率。如果频繁超时检查config.toml里的base_url是否写成了带路径的形式。网关地址只写到/api多余的路径会导致路由失败表现为请求挂起而不是立即报错。6. 把测试接进 CI 与后续动作本地跑通只是第一步真正省时间的是让它在每次 PR 时自动跑。GitHub Actions 配置让 Codex 生成就行生成 GitHub Actions 工作流配置在每次 PR 时自动运行 API 测试 先跑冒烟测试通过后再跑全量测试最后上传 HTML 报告作为 artifact。生成的工作流会先执行python run_tests.py smoke通过后再跑all失败时把reports/目录上传。这样 PR 里能直接下载报告看哪条用例挂了不用翻 CI 日志。如果你打算把这类生成任务长期跑在 CI 或本地定时任务里建议用 Coding Plan 管理额度避免按次调用把预算跑飞Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入细节和参数说明都在文档里遇到网关配置问题先查这里接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后给一个实操建议把openapi.yaml纳入版本控制每次接口变更先改规范再重新生成用例。这样测试用例永远和接口定义同步不会出现“接口改了但测试还在测老字段”的情况。生成器本身也可以定期重跑把新增接口自动纳入覆盖你只需要 review 生成的断言是否符合业务预期。