在真实测试环境验证 REST/GraphQL API 契约…

为 REST/GraphQL API 编写自动化契约测试，断言响应形状、状态码、headers、鉴权边界和响应时间，防止接口漂移与回归。

适用场景

解决思路

1. 开始前检查 `.agents/qa-project-context.md`；若存在则直接使用，并跳过其中已回答的问题。
2. 确认目标 API 是 REST、GraphQL 还是两者；REST-only 套件用标准 HTTP assertions，GraphQL 需要 query/mutation builders，并可从 introspection-diff snapshot 获益。
3. 确认鉴权机制是 JWT、API key、OAuth 2.0 还是 session cookies，并为每种选择不同的 fixture 策略。
4. 确认是否有 OpenAPI/Swagger spec；若有，用 `orval` 或 `openapi-zod-client` 自动生成 Zod schemas 作为 contracts，并考虑用 Schemathesis 做 spec-driven fuzzing。
5. 测试 contracts，而非 implementations：断言 response shape、status codes 和 headers，不要断言内部逻辑或 database state。
6. 用 schema validation 在 consumer 被破坏前捕获漂移；schema 测试失败意味着在 frontend 之前就抓住了 breaking change。
7. 把 auth flows 也当作测试；不要只 hardcode tokens，要测试 login、refresh、expiration 和 permission boundaries。
8. 把 response time 作为可测试断言；在 CI 中捕获 performance regressions 比 production incidents 更便宜。
9. 区分 API 探索（debugging、manual probing、OpenAPI playground）与自动化 API 测试，为不同任务选对工具。
10. 用 Bruno (v3.4+) 做基于文件的 collections、可 git-review 的 workflows、FOSS Postman replacement；filesystem-first，无需 cloud sync，支持 gRPC + OAuth + GraphQL query builder。
11. 用 Hurl (8.x) 做纯文本 HTTP 测试、CI smoke checks；一个文件等于多个 requests + assertions，可在 curl 能运行的地方运行，支持 certificate + JSONPath (RFC 9535) queries。
12. 用 Hoppscotch 做基于 Web 的 Postman 风格探索；开源、浏览器运行，适合快速检查。
13. 用 Playwright `APIRequestContext` 在 test runner 中做自动化测试。
14. 用 Supertest (Node) / httpx (Python) 对自有应用做 in-process API tests；双方都可控时反馈最快。
15. 新项目跳过 Postman/Insomnia，除非团队已有投入；基于文件的工具（Bruno、Hurl）更易在 PR 中 review，且 collections 漂移时仍可用。
16. `APIRequestContext` 支持无需启动浏览器的 standalone API tests，并与 browser contexts 共享 cookie/storage state。
17. 用 `request.get/post/...` 做 standalone API tests，并断言 status、header 和 body。
18. 用 combined browser + API tests：通过 API seed data，断言其出现在 UI，然后通过 API clean up。
19. 用 authenticated fixtures：在 fixture 中登录一次，把预认证的 `APIRequestContext` 交给测试，并在 teardown 中 dispose；不要 hardcode tokens。
20. 参考 `references/playwright-setup.md` 获取 `playwright.config.ts`、standalone tests、combined browser+API test 和 authenticated API fixture。
21. 用 schema 验证 response shape，而不是用 `toHaveProperty` 抽查单个字段。
22. Zod 4：定义 schema，对 response 做 `safeParse`，断言 `result.success`；失败时记录 `result.error.issues` 获得精确 diff；使用 Zod 4 原生字符串格式 `z.email()`、`z.uuid()`、`z.iso.datetime()`，链式 `z.string().email()` 形式已弃用并计划移除。
23. AJV with JSON Schema：当已有 JSON Schema（例如来自 OpenAPI spec）时，用 `ajv` + `ajv-formats` 编译并验证。
24. Schema-as-contract：让 API 和测试 import 同一个 schema 文件；如果 response shape 变化，consumer tests 立即失败。
25. 有 OpenAPI spec 时，用 `orval` 或 `openapi-zod-client` 自动生成 schema。
26. 对 spec-first 团队，在 CI 中增加 Schemathesis job，针对 live API 按 spec fuzz，捕获未文档化 shapes 和 edge-case 500s。
27. 参考 `references/schema-validation.md` 获取 Zod 4、AJV、schema-as-contract 和 Schemathesis 实现。
28. 每个 endpoint 覆盖一个 happy-path 测试和至少一个 error-path 测试。
29. CRUD lifecycle：用 `describe.serial` 块依次 create、read、update、delete，然后验证 404；跨步骤携带 resource id。
30. Auth flows：测试 login success、invalid credentials (401)、expired token (401)、token refresh、permission boundary (403)；把 auth 作为自己的 describe block。
31. Error responses：测试 400 malformed body、422 validation with field details、429 rate limit + `retry-after`；不要只发布 happy-path-only 套件。
32. Response headers：直接断言 `content-type`、`cache-control` 和 rate-limit headers，不要放在可能永不触发的条件里。
33. Pagination：测试 first-page metadata、out-of-bounds empty page、拒绝 invalid page size。
34. File upload/download：测试 multipart upload 和 `content-disposition` header 验证。
35. GraphQL：写一个小 `gql` helper，然后测试 query / mutation / invalid-query (errors array) 案例，并增加 introspection-diff snapshot 捕获被静默移除的字段。
36. Webhooks：启动一个一次性 HTTP server，注册 webhook，触发事件，并断言投递。
37. 参考 `references/test-patterns.md` 获取上述所有 pattern 的完整可运行实现以及 performance assertions。
38. Response headers 代码模式：用 `response.headers()` 获取 headers，并以小写名称索引；不要用 `if (rateLimited)` 门控断言，因为可能不触发。对 rate-limit 和 `retry-after` 变体见 `references/test-patterns.md` (Response Header Validation)。
39. Performance assertions：断言 hot endpoint 在预算内响应（例如 500ms）、payload 保持在 size ceiling 以下、API 在 burst of concurrent requests 下不出现 5xx；代码见 `references/test-patterns.md` (Performance Assertions section)。
40. 不要 hardcode auth tokens：token 会过期、轮换、跨环境不同；用 login fixture 动态获取 tokens。
41. 不要对 production 测试：API 测试会 create、modify、delete 数据；在 dedicated test environment 或 local instance 上运行。
42. 不要不验证 error responses：只 happy-path 的套件会漏掉最常见的 production 问题；为每个 endpoint 测试 400、401、403、404、500 responses。
43. 不要只在条件满足时断言 headers：headers 携带 cache directives、rate limit info、content type、CORS policy；在每个相关 response 上直接断言；埋在 `if (rateLimited)` 里的检查可能永不运行且证明不了什么。
44. 不要在创建测试数据后不清理：会污染 database；用 `afterEach`/`afterAll` hooks 或 fixture teardown。
45. 不要把 API 测试当 unit tests：不要 mock database；API 测试从 consumer 视角验证 contract；只 mock 你不拥有的真实第三方（payment gateways、external SaaS）。
46. 不要忽略 idempotency：PUT 和 DELETE 应该 idempotent；测试调用两次产生相同结果。
47. 完成标准：每个目标 endpoint 至少有 happy-path 和一个 error-path 测试（验证 4xx 或 5xx response）。
48. 完成标准：Auth flow 作为自己的 describe block 测试：successful login、invalid credentials、expired token、permission boundary (403)。
49. 完成标准：使用 Zod 4 或 AJV 对 response shape 做 schema validation assertions，而不只是 `toHaveProperty` 抽查。
50. 完成标准：至少对 `content-type` 和 API 设置的任何 cache/rate-limit headers 存在 header assertions，并无条件断言。
51. 完成标准：任何被不同团队或服务消费的 endpoint 都有 contract tests（共享 schema 文件；consumer-driven verification 用 `contract-testing`）。
52. 完成标准：真实第三方调用（payment gateways、external SaaS）被 mock 或 virtualized；API 及其 database 真实运行。
53. 完成标准：CI job 在 test environment 上退出 0（green）。
54. 参考文件：`references/playwright-setup.md`、`references/schema-validation.md`、`references/test-patterns.md`。

适用边界 · 注意事项

• 不适用于 consumer-driven contract verification（Pact、broker）；应改用 `contract-testing`。
• 不适用于 browser UI flows；应改用 `playwright-automation`。
• 不适用于对 production 环境运行会 create/modify/delete 数据的 API 测试；应在专用 test environment 或 local instance 上运行。