API 契约测试

何时使用

• 用户说"给这个接口写测试""测一下这个 API";
• 用户说"帮我验证这个接口通不通""接口改完测一遍";
• 接口文档和实现对不上,想验证真实行为;
• 改完接口要确认没破坏现有调用方;
• 上线前想快速知道哪些接口是好的、哪些是坏的。

使用步骤

第 1 步:找到真实契约

从代码里找,而不是听用户描述:

1. 路由定义(Flask/FastAPI/Express/Spring 等框架的路由文件);
2. 入参定义(请求体 schema、query 参数、路径参数);
3. 出参定义(响应模型、状态码);
4. 已有测试或文档,作为补充参考。

如果代码里找不到完整定义,列出缺口,请用户补充或允许按经验推断并标注"推断"。

第 2 步:列出测试用例

每个接口至少三类用例:

用例表格式:

| # | 接口 | 场景 | 请求 | 预期状态码 | 预期响应要点 |

第 3 步:确认环境与授权

执行前必须和用户确认:

1. 测试环境地址(本地、staging、还是线上);
2. 认证方式(token、cookie、还是无需认证);
3. 测试数据是否允许创建/修改/删除;
4. 有没有不能碰的接口或数据。

没确认就不执行。写测试只写测试,不对生产数据下手。

第 4 步:生成并执行测试

• 有 JSON 契约时,用 api_test_gen.py 生成 pytest 骨架(见下面的辅助脚本),再按实际契约核对补全;
• 用项目已有的测试框架(curl 脚本、pytest、Jest 等);
• 测试用例与契约一一对应,能追溯到第 2 步的用例表;
• 执行后把结果和预期对照,失败的标出差异。

第 5 步:输出测试报告

# API 测试报告

## 环境与时间
## 通过/失败统计
## 失败用例明细(接口、请求、实际响应、差异)
## 疑似缺陷(按严重程度排序)
## 建议

完整示例

一个可运行的登录接口契约测试见 examples/login-api:自动起服务、跑 5 个用例、出报告,改坏契约就能看到用例变红。

用例设计参考

用例类型、断言要点、框架写法见 references/CASE_DESIGN.md。

输入与输出

• 输入:接口相关代码或文档 + 测试环境信息;
• 输出:测试用例表 + 测试代码/脚本 + 测试报告。

示例

用户输入: "帮我把登录接口测一下。"

契约(从代码确认): POST /api/login,入参 {username, password},成功返回 200 + {token},密码错返回 401。

用例表:

报告节选:

## 通过/失败
4 个用例,3 通过,1 失败
## 失败用例
用例 3:账号不存在返回 404,契约预期 401。响应体提示"账号不存在",存在账号枚举风险。

辅助脚本

scripts/api_test_gen.py 把契约 JSON 转成 pytest 测试骨架,支持路径参数、查询参数、请求头、响应字段类型断言:

# 生成契约模板
python skills/api-tester/scripts/api_test_gen.py --new contract.json

# 填好契约后生成测试
python skills/api-tester/scripts/api_test_gen.py contract.json -o tests/test_login.py

生成的是骨架,用例和断言按实际契约核对后再执行。运行:API_BASE_URL=<地址> pytest tests/test_login.py。

注意事项

• 契约以代码为准,文档对不上代码时标出来;
• 执行前必须确认环境,默认不碰生产;
• 测试产生的数据要清理,或提前和用户确认保留;
• 失败用例区分"接口 bug"和"测试写错",先复核再下结论。

不适用场景

• 接口还没实现,只能做契约设计(那是另一件事);
• 用户拒绝提供环境信息;
• 第三方外部接口且没有测试账号。

验证方式

1. 触发:"给这个接口写测试";
2. 跑脚本:有 JSON 契约时用 api_test_gen.py 生成骨架,核对后执行;
3. 检查:用例表覆盖正常/边界/异常,执行前有环境确认记录;
4. 复核:任选一个失败用例,人工确认差异真实存在。