测试设计 · Agent 执行

接口回归用例设计

从接口文档和校验代码生成回归用例、测试数据与断言。缺失、null、空串分开测；预期结果逐条追到依据。

下载完整技能包查看 SKILL.md

网页展示方法和成果样例；任务由你的 Agent 结合实际材料执行，不在此页面发送接口请求。

输入什么，得到什么

需要的材料

OpenAPI、接口文档或服务端校验代码，至少提供一种。

交付成果

得到可交给开发或测试执行的用例表，包含前置条件、输入变体、HTTP 与业务断言、数据清理方式。

不从一份 JSON 示例猜测必填或错误码；没有授权的测试环境时仅生成计划，不调用接口。

完整输入样例

以下为合成演示材料，不代表真实业务数据。

POST /reservations，仅用户自己的仓库可用。 Authorization 必须提供；无认证返回 401，仓库不属于当前用户返回 403。 HTTP 201 且业务 code=0 表示创建成功；校验失败 HTTP 400、code=VALIDATION_ERROR，不得新增预留记录。 JSON 对象必填 warehouseId（非 null 字符串，minLength=1）和 quantity（integer，minimum=1，maximum=100）。 note 是可选字符串，允许空串，不允许 null，maxLength=20。没有提供幂等协议、库存不足错误码或数据库访问方式。只生成测试计划，不调用服务。

成果样例

以下为合成演示材料，不代表真实业务数据。

状态：全部未执行。这是基于 input.md 人工编写的成果样例。基线：测试用户 A 拥有 warehouse-A；请求 {"warehouseId":"warehouse-A","quantity":1,"note":""}。测试前后用唯一测试关联键核对预留记录；数据库尚不可访问时副作用断言标记“未验证”。

ID	优先级	输入/前置条件	HTTP 断言	业务与数据断言	依据
R01	P1	基线	201	code=0；仅新增 1 条预留	成功协议
R02	P1	删除 quantity	400	VALIDATION_ERROR；新增 0 条	必填
R03	P1	quantity=null	400	同 R02	integer 不含 null
R04	P1	quantity=0	400	同 R02	minimum=1
R05	P1	quantity=100	201	code=0；新增 1 条，数量为 100	maximum=100
R06	P1	quantity=101	400	同 R02	maximum=100
R07	P1	quantity="1"	400	同 R02；若实际被转换则报告合同/实现冲突	integer
R08	P1	quantity=1.5	400	同 R02	integer
R09	P1	删除 warehouseId / 设为 null / 设为空串，分 3 次	400	每次同 R02	required、string、minLength=1
R10	P1	note 缺失 / 空串 / 20 个“中”，分 3 次	201	每次新增 1 条	可选、空串合法、maxLength=20
R11	P1	note 为 21 个“中” / null，分 2 次	400	每次同 R02	maxLength、类型
R12	P0	A 请求 B 的 warehouse-B	403	不新增，响应不含 B 的库存明细	仓库归属
R13	P0	无 Authorization	401	不新增	认证协议

成功用例需预置充足库存；用例执行后仅撤销本次测试创建的预留。不允许直接清空仓库库存或复用生产数据。

尚不能下结论

幂等协议缺失：列为待确认，不生成“重复提交必定只建一条”的断言。
库存不足：缺少业务码与回滚语义，不能推断为 400。
无运行环境和数据库权限：不执行；不得声称通过。

本包 examples/fixtures.json 已列出基线与输入变体，examples/questions.md 记录缺口；它们是计划数据，不会自动发送请求。

使用指令

请阅读 api-regression-planner/SKILL.md，按其中的方法为我提供的接口生成 cases.md、fixtures.json 和 questions.md。每个预期必须标明合同或代码依据，缺失信息单列；本次先生成计划，不发送请求。接口材料：
（在这里附上文档、OpenAPI 或仓库文件路径）

完整方法与执行规则

交付测试人员或开发者能执行的回归计划。每个用例必须说明依据、输入变化、预期断言与数据恢复方法。不要用通用测试清单替代针对当前接口的分析。

输入与取证

先查用户提供的接口文档、OpenAPI 和仓库中的控制器、DTO 校验、鉴权、异常处理及已有测试。记录文件位置、接口方法及路径、文档版本和代码版本；不同来源冲突时分别列出，不能用实现覆盖合同或反过来。

至少需要一个接口定义；只有一份 JSON 示例时，只能确认示例结构，不能推断必填、枚举全集、成功码或最大长度。先产出可确认部分，将缺口写进 questions.md，不要把推测写成通过条件。

若输入为 OpenAPI：

区分参数自身的 required、requestBody.required 和对象的 required 属性数组。
解析可访问的本地 $ref；循环引用、外部引用或复杂组合无法确认时列出未覆盖节点，不凭空补定义。
区分 OpenAPI 3.0 的 nullable 与 3.1 的含 null 类型；required 仅约束属性存在，不意味着非空或非 null。
读取接口级与全局 security；接口覆盖全局，security: [] 表示本接口不要求安全机制。security 数组中的方案是备选，同一对象内的多个机制需组合满足。
example/default 不是已被服务端执行的验证规则；format 的校验强度需依据运行时实现确认。

用例选择

使用 references/case-design.md 生成与证据匹配的用例。先构造一条满足所有已知约束的基线请求，再一次仅改变一个条件，避免一个请求同时违反多个规则导致无法定位失败原因。

优先覆盖会造成越权、重复业务操作、数据损坏和客户端中断的变化。权限、幂等和并发只有在接口涉及这些语义时展开；测试所需的第二个租户、用户或资源均需说明准备条件。

分开写 HTTP 状态、业务码、响应字段与持久化副作用的断言。例如“HTTP 200”不能代替“订单创建成功”；“返回错误”不能代替“数据库没有新增记录”。错误码无文档依据时标为待确认，不臆造 400/422 等精确值。

交付

在用户指定目录，或默认 artifacts/api-regression/ 下生成：

cases.md：基线请求与用例表。每行包含 ID、优先级、合同/实现依据、前置条件、输入变更、HTTP 断言、业务/数据断言、清理方式、状态。未运行时统一写“未执行”，不填通过率。
fixtures.json：与用例对应的演示请求及变量，使用合成数据；不能把真实凭据写进文件。
questions.md：冲突、缺失约束、未解析引用和未覆盖分支；说明各自阻塞哪些用例。

需要自动化时，沿用项目现有测试框架生成针对性测试；不要在用户只要求计划时额外安装依赖或调用接口。只有环境和调用范围已获授权时才执行请求。写入、重试或并发测试需限定在获准的测试环境及可清理数据中。

验收

每个精确预期都有合同或代码依据；建议项与已确认规则明确区分。
必填的缺失/null/空串分别判断；边界的取值仍满足其他规则。
涉及分页/筛选时验证总数、范围、稳定排序与隔离，而不只检查列表非空。
计划、生成测试代码、实际执行结果分别报告；不能把文件生成成功当作接口通过。

查看 examples/input.md 与 examples/result.md 了解交付粒度。它们是人工编写的演示，不是线上实测结果。