qa-api-testing-contracts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QA API Testing and Contracts

QA API测试与契约

Use this skill to turn an API schema into enforceable checks (lint, diff, contracts, and negative/security cases) and wire them into CI so breaking changes cannot ship silently.

使用本技能可将API架构转化为可强制执行的检查项（包括语法检查、差异对比、契约验证以及负面/安全测试用例），并将其集成到CI流程中，确保破坏性变更不会被悄悄发布。

Ask For Inputs

请求输入信息

API type and canonical schema artifact (OpenAPI 3.1, SDL, proto) and where it lives in-repo.
Environments, auth method(s), and how to provision stable test identities/keys.
Critical endpoints/operations and business flows (rank by risk and revenue impact).
Data constraints (idempotency keys, pagination, ordering), rate limits, and error format (prefer RFC 7807
```
application/problem+json
```
for REST).
Versioning + deprecation policy, consumer inventory, and release cadence.
Current test tooling/CI and what “blocking” means for your org.

API类型与标准架构制品（OpenAPI 3.1、SDL、proto）及其在代码仓库中的存储位置。
测试环境、认证方式，以及如何获取稳定的测试身份/密钥。
核心端点/操作以及业务流程（按风险和收入影响程度排序）。
数据约束（幂等键、分页、排序）、速率限制以及错误格式（REST推荐使用RFC 7807定义的
```
application/problem+json
```
格式）。
版本控制与弃用策略、消费者清单以及发布节奏。
当前使用的测试工具/CI系统，以及贵组织中「阻塞性检查」的定义。

Outputs (What to Produce)

输出成果

A minimal CI gate set (lint + breaking diff + contract suite) wired to PRs.
A coverage map derived from the schema (critical operations first).
A negative/security baseline aligned to OWASP API risks.

一套集成到PR流程中的最小化CI门禁集合（语法检查+破坏性差异对比+契约测试套件）。
基于架构生成的测试覆盖映射表（优先覆盖核心操作）。
符合OWASP API风险标准的负面/安全测试基线。

Quick Start

快速开始

Lint the schema (syntax + best-practice rules) and fix issues before writing tests.
Add breaking-change checks against the base branch on every PR.
Pick a contract strategy (CDC, schema-driven, or both) and run it in CI against an ephemeral environment.
Add negative/security cases for auth, validation, and error handling.
Make gates explicit (what blocks merge/release) and publish results.

在编写测试前，先对架构进行语法检查（语法规范+最佳实践规则）并修复问题。
为每个PR添加针对基准分支的破坏性变更检查。
选择一种契约测试策略（消费者驱动契约CDC、架构驱动，或两者结合），并在CI中针对临时环境运行测试。
为认证、数据验证和错误处理添加负面/安全测试用例。
明确门禁规则（哪些检查会阻止合并/发布）并发布测试结果。

Workflow

工作流程

1) Establish Contract Artifacts (Source of Truth)

1) 确立契约制品（唯一可信源）

REST: single OpenAPI 3.1 file or a compiled artifact; avoid drift across fragments.
GraphQL: checked-in SDL (and federation/composition config if relevant).
gRPC: checked-in
```
.proto
```
+
```
buf.yaml
```
(or equivalent) with a stable module layout.

REST：使用单个OpenAPI 3.1文件或编译后的制品；避免多个片段之间出现差异漂移。
GraphQL：已入库的SDL（若涉及联邦/组合，需包含相关配置）。
gRPC：已入库的
```
.proto
```
文件+
```
buf.yaml
```
（或等效配置），并保持稳定的模块结构。

2) Validate the Schema (Fast, Deterministic)

2) 验证架构（快速、确定性）

Run spec linting (Spectral / GraphQL Inspector / buf lint).
Enforce a small, explicit ruleset (naming, descriptions, auth annotations, consistent error model).

执行规范语法检查（使用Spectral / GraphQL Inspector / buf lint工具）。
强制执行一套简洁明确的规则集（包括命名规范、描述要求、认证注解、统一错误模型）。

3) Detect Breaking Changes (PR Gate)

3) 检测破坏性变更（PR门禁）

REST: OpenAPI diff with a breaking-change policy (remove/rename/type change/requiredness).
GraphQL: schema diff with breaking checks (field removals, type changes, non-null tightening).
gRPC:
```
buf breaking
```
(do not reuse/renumber fields; avoid changing request/response shapes incompatibly).

REST：使用OpenAPI差异对比工具，并遵循破坏性变更判定规则（删除/重命名/类型变更/必填性修改）。
GraphQL：架构差异对比并进行破坏性检查（字段删除、类型变更、非空约束收紧）。
gRPC：使用
```
buf breaking
```
工具（不要复用/重命名字段；避免修改请求/响应结构导致不兼容）。

4) Execute Contract Tests (CI Gate)

4) 执行契约测试（CI门禁）

Choose one or combine:

CDC (Pact): best when many independent consumers exist and behavior matters beyond schema.
Schema-driven (Specmatic): best when schema is the contract and you want fast coverage across operations.
Property-based (Schemathesis): best when you want systematic edge cases and server hardening.

选择以下一种或多种策略组合：

消费者驱动契约（CDC，基于Pact）：适用于存在大量独立消费者，且关注点超出架构本身、更注重实际行为的场景。
架构驱动（基于Specmatic）：适用于以架构作为契约，且希望快速覆盖所有操作的场景。
属性驱动（基于Schemathesis）：适用于需要系统性覆盖边缘用例、强化服务器安全性的场景。

5) Add Negative + Security Cases (Minimum Set)

5) 添加负面/安全测试用例（最小集合）

AuthN/AuthZ: missing/expired token (401), insufficient scope/role (403), tenant isolation.
Validation: missing required fields, invalid types, boundary values, empty strings, large payloads.
Error handling: stable error shape, safe messages, correct status codes, correlation IDs.
Abuse & limits: rate limiting (429), pagination limits, idempotency replay, retry-safe semantics.
- For GraphQL, also validate operations checks (known/persisted queries) if you have an operation registry (GraphOS/Hive/etc.).

认证/授权：缺失/过期令牌（401错误）、权限范围/角色不足（403错误）、租户隔离验证。
数据验证：必填字段缺失、类型无效、边界值、空字符串、大负载测试。
错误处理：稳定的错误结构、安全的错误信息、正确的状态码、关联ID验证。
滥用与限制：速率限制（429错误）、分页限制、幂等性重放、重试安全语义验证。
- 若使用GraphQL操作注册表（如GraphOS/Hive等），还需验证操作检查（已知/持久化查询）。

6) Define CI Quality Gates (Merge + Release)

6) 定义CI质量门禁（合并+发布）

Pre-merge: schema lint + breaking-change diff (blocking).
Pre-release: contract suite (blocking), plus smoke/functional tests for critical flows.
Reporting: publish artifacts (diff report, contract verification, failing cases) and link in PR.

合并前：架构语法检查+破坏性差异对比（阻塞性检查）。
发布前：契约测试套件（阻塞性检查），加上核心流程的冒烟/功能测试。
报告：发布测试制品（差异报告、契约验证结果、失败用例）并在PR中添加链接。

Quality Checks

质量检查准则

Fail fast: schema violations and breaking changes block merge.
Determinism: isolate data, freeze time where needed, avoid shared mutable fixtures.
Flake hygiene: separate network instability from contract failures; retry only for known-transient classes.
Alignment: contracts reflect versioning/deprecation policy and consumer inventory.
Scope control: keep load/resilience tests separate unless explicitly requested.

快速失败：架构违规和破坏性变更直接阻止合并。
确定性：隔离测试数据，必要时冻结时间，避免使用共享可变测试夹具。
消除不稳定测试：将网络不稳定与契约失败区分开；仅对已知的临时故障进行重试。
一致性：契约需与版本控制/弃用策略以及消费者清单保持一致。
范围控制：除非明确要求，否则将负载/弹性测试与契约测试分开执行。

Use the Bundled Templates

使用内置模板

Coverage plan:
```
assets/api-test-plan.md
```
Release review:
```
assets/contract-change-checklist.md
```
Tooling map:
```
assets/schema-validation-matrix.md
```

测试覆盖计划：
```
assets/api-test-plan.md
```
发布评审清单：
```
assets/contract-change-checklist.md
```
工具映射表：
```
assets/schema-validation-matrix.md
```

AI Assistance (Use Carefully)

AI辅助使用（谨慎操作）

Use AI to draft tests, suggest missing edge cases, and tighten matchers.
Treat AI output as untrusted until verified against the schema and real behavior.
Avoid uploading sensitive payloads; sanitize examples and logs.
For a tool comparison and workflows, read
```
references/ai-contract-testing.md
```
.

使用AI辅助编写测试用例、建议缺失的边缘场景，并优化匹配规则。
在未针对架构和实际行为验证之前，请勿信任AI生成的输出内容。
避免上传敏感负载；对示例数据和日志进行脱敏处理。
如需工具对比和工作流参考，请阅读
```
references/ai-contract-testing.md
```
。

Read These When Needed

必要时阅读以下文档

Change safety and CDC patterns:
```
references/contract-testing-patterns.md
```
AI-assisted tooling and decision matrix:
```
references/ai-contract-testing.md
```
Curated authoritative links:
```
data/sources.json
```

变更安全与CDC模式：
```
references/contract-testing-patterns.md
```
AI辅助工具与决策矩阵：
```
references/ai-contract-testing.md
```
精选权威链接：
```
data/sources.json
```