API Testing

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 测试", "接口测试", "契约测试"

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

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. Use Pact or Spring Cloud Contract for consumer-driven contract testing in microservice architectures.

3. Cover critical scenarios

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.

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)

Gotchas

• 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

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

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

References

• ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — discipline every skill shares
• references/templates/api-test-scaffold.md — REST API test scaffold template (Jest/Supertest)