| name | contract-testing |
| description | Applies consumer-driven contract testing to verify API compatibility between packages or services without full E2E tests. Use when designing or evolving API boundaries between loosely coupled modules. |
Contract Testing (Consumer-Driven Contracts)
Rule Anchor
AGENTS.md > "Build Requirements"AGENTS.md > "Type System (Strict)"
For an API boundary between independently developed modules (HTTP, WebSocket, or typed interface):
- The consumer defines the contract — a version-controlled file (JSON/TS) of the
request/response pairs it depends on — and tests against a mock derived from it.
- The provider verifies the contract — replays the consumer's expectations against its real
handlers in its own tests, without either side needing the other running.
- CI runs both sides; a contract violation blocks the merge. When the API changes, update the
contract first, then the implementation (breaking vs. additive goes through review).
Anti-patterns: hand-written consumer mocks that drift from the real API; provider changes without
a contract update; contracts that test internal implementation instead of the boundary shape;
relying solely on E2E tests for compatibility.
