Testing the Contract, Not Just the Code

API testing is a portfolio, and each layer earns its place by the failures it catches per unit of cost. Unit tests exercise handler logic fast and in isolation — necessary, and silent about the contract (a handler can be perfectly unit-tested while returning a shape no consumer expects). Integration tests run the real HTTP stack against real serialization and (ideally) a real database, catching the gap between "the function returns the object" and "the wire carries the JSON". Contract tests verify recorded consumer expectations against the running provider. Compatibility tests diff today's schema against the shipped one. End-to-end tests thread whole consumer journeys and are reserved for the few flows worth their flake. Load tests check that the promises hold at production shapes — pagination at page 4,000, the rate limiter at the limit.

The ordering principle is cheapest-catcher-wins: a field rename should die in a schema diff (milliseconds, exact blame), not in an e2e suite (minutes, vague blame), and never in a consumer's production (days, your reputation). Most teams over-invest at the ends of the pyramid — thousands of unit tests, a flaky e2e suite — and leave the middle empty, which is exactly where contract breakage lives.

A contract test inverts the usual direction of testing. The *consumer* records what it actually depends on — "when I GET /orders/o1, I need id, status, and total.amount as an integer" — and the *provider* runs those recorded expectations against its real service in CI. Now the provider's build fails when it breaks the checkout team, before deploy, with the consumer's name on the failure. This is Consumer-Driven Evolution: Telemetry Before Breakage made mechanical: the consumer registry stops being a YAML file and becomes an executable veto.

Two disciplines keep contract tests honest. Consumers must record only what they *use* — an expectation that pins the entire response body re-freezes the API just like Hyrum's Law would, and turns every additive change into a false alarm; good contract tests assert presence and type of needed fields and stay silent about the rest (which is also the forward-compatible posture Backward Compatibility: The Real Rules asks of clients). Providers must run the expectations of *every registered consumer*, not just the loudest — the value of the mechanism is precisely the consumer you forgot about.

Schema-level compatibility checks are the cheap sibling: diff the current OpenAPI/protobuf/GraphQL schema against the released version and fail the build on the breaking-change list — removed field, renamed field, type change, new required parameter, narrowed enum (see OpenAPI: Describing the Contract, Not Designing It and Removing Fields Without Removing Consumers). They know nothing about behavior, but they catch the whole mechanical class of breaks for the price of a linter.

Half the contract is about what happens when things go wrong, and that half is the least tested. Negative tests send what the docs say is invalid and assert the *documented* failure: the right status, the right machine-readable code from your An Error Taxonomy Clients Can Branch On, the field-level detail Validation Errors: Feedback, Not Verdicts promises, Retry-After on 429s, request_id present in every error body. An API whose error paths are untested has an error contract that exists only in the documentation — consumers will discover the divergence in production, in their retry loops.

Fuzzing extends negative testing past your imagination: generate malformed JSON, wrong types, absurd sizes, negative numbers, unicode edge cases and unknown fields — cheaply derivable from the schema — and assert one property: the API responds with a *controlled* 4xx, never a 500, a hang, or a stack trace in the body (a 500 on malformed input means unvalidated input reached your internals, which is a security finding as much as a bug — the input-validation boundary Validation Errors: Feedback, Not Verdicts describes, probed automatically). Reliability clauses deserve the same directness: replay a mutation with the same Idempotency Keys: The Mechanism value and assert one effect; send two conflicting updates and assert the Optimistic Concurrency: Versions and If-Match 409; walk pagination under concurrent writes and assert no skips or duplicates (Cursor Pagination: An Opaque Bookmark, Not a Position).

Finally, test at production *shapes*, not just production *rates*: page 4,000 of a deep collection, the tenant with 3,000 tasks, a batch of exactly the maximum size, the response at the payload cap. Load testing that replays median traffic validates the median — your incidents live in the p99 shapes (see Payload Size: 20KB, 200KB, 5MB and Unbounded Collections: The Anti-Pattern With a Fuse).