git:20260814.8c16c95 to git:20261015.f440cbb

9 added, 93 removed. Audit A to A.

---

name: api-testing

- description: Use when testing APIs or designing API test strategies — contract testing, REST/GraphQL testing, and integration testing. Triggers on "test API", "contract testing", "integration test", "API 测试", "接口测试", "契约测试".

+ description: Verify API contracts against a real controlled service. Triggers on "test API", "API 测试".

---

# API Testing Patterns

- API testing verifies contracts and behavior from the consumer perspective —

- correct responses, proper error handling, acceptable performance. Focus on what

- matters to consumers, not implementation details.

## When to use

- - Testing REST or GraphQL APIs

- - Validating microservice contracts

- - Designing API test strategies

- - Preventing breaking API changes

- - Triggers on "test API", "contract testing", "integration test", "API 测试", "接口测试", "契约测试"

+ - Verify API contracts against a real controlled service.

- **Not for:** generating test scaffolds for non-API code (use `test-generation`); browser/E2E flows (use `e2e-testing`); the TDD loop itself (use `tdd`).

+ **Not for:** api-design for defining contracts; e2e-testing for UI journeys.

## Steps

- ### 1. Identify the testing level

- |-------|---------|--------------|-------|

- ### 2. Test the contract, not implementation

- Test from the consumer perspective using schema validation, not exact values.

- Consumers depend on the contract (status codes, response shape); they don't

- care about internal structure.

- **Pattern — Consumer-Driven Contracts:** schema validation against the contract (status codes, response shape), not exact values — code example in [references/templates/api-test-scaffold.md](references/templates/api-test-scaffold.md). Use **Pact** or **Spring Cloud Contract** for consumer-driven contract testing in microservice architectures.

- ### 3. Cover critical scenarios

- | Scenario | Must test | Example |

- |----------|----------|---------|

- | Auth | 401/403 handling | Expired token, wrong user, cross-user access |

- | Input | 400 validation | Missing fields, wrong types, out-of-range values |

- | Errors | 500 graceful handling | DB down, timeout, upstream failure |

- | Idempotency | Duplicate prevention | Same idempotency key → same result |

- | Concurrency | Race conditions | Parallel checkout on shared inventory |

- **Idempotency:** send the same request twice with an `Idempotency-Key` header;

- both responses must return the same `orderId` (no duplicate created).

- ### 4. REST CRUD pattern

- Test the full resource lifecycle — CREATE, READ, UPDATE, DELETE — as a sequence

- that proves each operation and its side effects. Code example in

- [references/templates/api-test-scaffold.md](references/templates/api-test-scaffold.md).

- ### 5. GraphQL-specific checks

- - Query validation: reject invalid queries, enforce typed schemas

- - Complexity limits: prevent abusive nested queries (depth/complexity analysis)

- - Introspection: test against staging schema (production may disable it)

- ### 6. Automate and monitor

- Automate all API tests in CI/CD with schema validation. Version API tests

- alongside the API to prevent breaking changes. Monitor production APIs for

- contract drift between deployed behavior and the spec.

- ## Best practices

- **Do:**

- - Test from consumer perspective

- - Use schema validation (not exact field values)

- - Test error scenarios extensively — not just happy paths

- - Version API tests with the API

- - Mock external services to keep tests fast and deterministic

- **Avoid:**

- - Testing implementation, not contract

- - Ignoring HTTP semantics (status codes)

- - No negative testing

- - Asserting on field order or extra fields

- - Slow tests (mock external services)

+ 1. Identify protocol, contracts, authorized environment, isolated data and tooling.

- ## Gotchas

+ 2. Exercise actual requests, authentication, ownership, invalid input and lifecycle; check GraphQL transport and operation errors.

- - Tests generated against the documented API must be validated against the

- running service first — docs and reality drift

- - Auth tokens expire between runs — use fixtures with refresh logic

- - Rate limiting in CI causes intermittent 429s — add retry with exponential

- backoff

- - Idempotency tests need unique request IDs per run — hardcoded IDs cause false

- passes on retry

- - GraphQL introspection may be disabled in production — test against staging

+ 3. Test relevant pagination, concurrency and repeated requests using the contract idempotency mechanism, not tracing headers.

- **Output:** API test files (contract + integration) under `test/` — code, not a report.

+ 4. Run, inspect logs and clean only test-owned state; determine whether failures violate tests or implementation from contract evidence.

## Verify

- - [ ] Contract tests cover every consumer expectation

- - [ ] Auth: 401 without token, 403 for wrong user, expired token rejected

- - [ ] Input validation: missing fields, wrong types, out-of-range values → 400

- - [ ] Error states: 500 graceful, timeout handled

- - [ ] Idempotency: duplicate request with same key → same result

- - [ ] REST resources tested across full CRUD lifecycle

- - [ ] Tests automated in CI with schema validation

+ - Real service success and failure match contracts; cleanup is scoped and mock results are not labelled integration.

## References

- - [${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md](${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md) — discipline every skill shares

+ - [engineering-principles.md](../../../references/engineering-principles.md) — shared decision boundaries, scope and verification.

- [references/templates/api-test-scaffold.md](references/templates/api-test-scaffold.md) — REST API test scaffold template (Jest/Supertest)