成功响应通常最先被写进文档。然后消费者分别收到三种不同的校验、授权和依赖失败结构，最后有人把这叫作 API 契约。

为什么需要这个 Skill

API 错误契约测试用于检查失败响应是否具有稳定结构、清晰分类、安全细节，以及足够支持客户端选择下一步动作的信息。

Skill 用来做什么

根据提供的 Schema、状态码约定、错误码目录、鉴权规则、日志和脱敏要求，建立按操作与错误分类的对照表。将每个响应与对应请求和契约版本关联，再区分违反适用规则的情况、有来源的操作专属例外，以及尚未解决的规则。

使用 AEC-## 记录候选的对象、前置条件、关注行为、来源证据、验证方法、影响/优先级、责任角色和关闭条件。这是设计复核；候选数量不等于测试覆盖率。

Awesome QA Skills 按语言和测试阶段组织 Skill；系列总览 介绍通用安装方式。

它不做什么

这个 Skill 不执行请求、不虚构状态码或重试策略、不要求不同请求共用一个关联 ID，也不会把响应差异一概认定为缺陷。只有找到适用的契约规则和合法对照后，差异才可能成为发现。

它主要检查哪些内容

契约维度从来源记录什么在响应中比对什么
HTTP 与业务分类状态码映射、业务码目录和明示例外当前操作与错误对应的状态码和业务码
必需字段必填键、类型、是否可空和字段路径结构字段缺失、类型不符或位置错误
关联信息如何在响应与日志之间关联同一个请求单次交互可追踪；不同请求的 ID 不作横向比较
重试含义哪些错误应修正、重试、等待、重新认证或停止错误码和客户端动作是否符合文档规则
信息披露对服务商、数据库和内部细节的脱敏规则响应或日志是否泄露受限信息

跨操作比较通用规则，同时保留有来源的例外。结构不同不代表一定有错；只有违背适用于该操作的规则时，才形成候选发现。

开始之前先审计输入

围绕“错误发现”开始分析时，先把输入分成六种状态。缺口不会自动变成失败，但也不能被隐藏在结论里。

状态含义本 Skill 的处理方式
known材料直接证明的事实标出来源、版本和时间，允许进入判断
missing本轮需要但尚未提供的材料列出最小补证动作，结论保持受限
conflicting来源之间互相矛盾并列来源和冲突点，交给负责人裁决
stale材料存在但版本或时间已经过期标出新鲜度，不把旧结论当当前事实
out_of_scope有关但不在本轮范围内明确排除，避免分析悄悄扩大
assumptions为继续分析而暂时采用的假设写出验证方式和失效条件

至少把输入版本、范围、环境、证据位置和负责人放在一起。没有运行记录时，只能交付分析、设计或验证计划，不能写执行通过。

从问题到结构化发现

AEC-## 发现字段

每条候选要注明操作/错误组合、适用的契约来源与版本、前置条件、观察到的问题、证据状态、影响/优先级、责任角色、关闭条件和最小验证方法。事实、推断、建议和 Human 决策要分开。没有来源规则的响应差异仍是待确认问题。

一个完整案例

本节按输入、分析、发现、决策和验证展开；材料不足时保留 missing、conflicting 或 assumptions，不把它们改写成通过。

输入

材料这次提供什么缺失时怎么处理
错误契约错误信封、错误码、消息、字段路径、请求 ID 和状态码映射标出客户端实际依赖的可选字段
失败矩阵校验、认证、授权、冲突、限流和依赖失败不同动作不能都归为一个通用错误
消费者行为重试、展示、日志、回退和客服查询把每个动作接回错误字段

可以这样调用：


请使用 api-error-contract-testing Skill。

任务：验证结算服务和移动端共同使用的支付 API 错误响应
输入材料：[需求、版本、链接、日志、报告或数据路径]
范围：[本次包含和排除的对象]
未知项：[缺失的环境、账号、数据或权限]
期望输出：[按风险排序的发现、证据状态和下一步动作]

先审计输入。分开写事实、假设和待确认问题。没有运行记录时不要声称已经执行。

分析

先从一个边界清楚的小回合开始：验证结算服务和移动端共同使用的支付 API 错误响应。通过同一个结算接口提交无效卡号、过期授权令牌和网关超时。先断言错误结构，再断言客户端动作分别是修正输入、重新认证或延迟重试，同时检查网关内部细节已经脱敏。

交接产物要同时保留输入版本、时间窗口、证据索引、负责人和下一次验证动作。Skill 可以整理不确定性，不能制造缺失的产物。

发现

以下是记录格式示例，不是执行结果：

字段示例
编号与对象AEC-01 —— 结算操作中支付服务商超时后的重试含义
前置条件与关注行为有来源的契约将该条件标为可重试，但移动客户端未执行文档规定的动作
证据状态复核契约版本和对应客户端追踪记录前为 UNASSESSED
影响/优先级与负责人说明消费者影响；指定 API 契约与客户端负责人；有项目标准后再评分
关闭条件与验证对齐适用契约和客户端行为，再做隔离的契约检查并保留原始证据

必须先证明规则适用，才能把差异认定为缺陷。

决策

由 API 契约负责人确认该规则是否适用于此操作，客户端负责人确认预期消费者动作。来源冲突时，不要因为某个响应更常见就选它作为正确答案。

验证

针对一次交互关联请求、响应、日志和契约版本，并与合法对照比对后保留原始证据；不同请求的关联 ID 不要求相同。

发现如何进入下一阶段

交接产物

输出字段它要回答什么示例状态
错误发现结构、分类、字段位置或安全问题契约来源与影响
消费者动作重试、修正输入、重新认证、等待或停止预期决策
兼容性说明破坏或削弱客户端假设的改动迁移或版本动作

没有运行记录、查询结果或原始产物时，不要写“已通过”。好的测试从客户端决策开始，而不是从服务端实现开始。如果移动端无法区分临时网关故障和无效银行卡，那么即使每个响应都是合法 JSON，错误契约也已经失败。

下一步路由

将未解决的错误码目录、重试或脱敏规则连同受影响操作和来源版本交给负责人。保留操作专属例外，不要把它们压成全局规则。

怎样准备更好的输入

提供错误 Schema 和错误码目录、操作清单、契约版本、请求/响应样例、对应日志、客户端动作和脱敏策略。若材料不全，要明确指出当前无法判断对照表中的哪一部分。

和其他 Skill 怎么配合

容易踩的坑

  1. 只断言 HTTP 状态码。
  2. 让面向人的消息变成机器依赖的契约。
  3. 返回暴露内部状态的网关或数据库细节。

安装与调用

全局安装这个 Skill：


npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/api-error-contract-testing -g

安装后使用 api-error-contract-testing Skill，并附上真实项目材料。

常见问题

每种错误都必须有唯一错误码吗？

不一定，但每个错误码都要支持不同的消费者动作，或明确共享同一策略。

快照可以证明契约吗？

快照可以发现结构变化，但可重试性、隐私和客户端行为仍需要语义断言。

参考

源 Skill 与执行契约

完整执行契约位于 API 错误契约测试 提示词。调用 Skill 前先阅读它；提示词定义了详细流程和输出契约。源目录 中还包含入口文件以及实际存在的配套资料。

入口文件重点约束错误信封、错误码分类、字段路径、可重试性、脱敏和客户端处理。写结论前先阅读配套提示词，并保留这个 Skill 的决策边界。

参考链接

安全测试白盒测试背靠背测试本地化测试边界测试
分享