A mobile team ships a release. Two days later, the account screen goes blank. The provider's tests passed, the consumer's tests passed, and the bug still reached production — because one side renamed a JSON field and nothing checked the agreement between them. Contract testing exists to close that gap. It turns an informal understanding between two services into something a build pipeline can verify in seconds.
What a Contract Actually Contains
A contract is not a full API specification. It is the subset of an interface that a specific consumer depends on: the request it sends, the response shape it parses, the status codes it handles, and the error format it reads. Everything else is noise.
Consider a payments service exposing GET /orders/{id}. A checkout consumer needs a 200 response with id, total, and currency. The provider is free to add loyaltyPoints or estimatedDelivery whenever it likes — those fields are additive and harmless. But remove currency, change total from a number to a formatted string, or start returning 404 where the consumer expects 200, and the contract is broken. That distinction — additive changes are fine, subtractive or type-changing ones are not — is the whole point.
Consumer-Driven Contracts, Step by Step
The most common model is the consumer-driven contract. Instead of the provider team guessing what clients need, each consumer team writes tests that describe its expectations.
The flow
- The consumer writes a test that mocks the provider and asserts on the request it sends and the response it can handle.
- That test produces a contract file — a small JSON document describing the interaction.
- The contract is published to a broker, tagged with the consumer's version and branch.
- The provider's CI job pulls every contract that targets it and replays each request against the real implementation.
- If any expectation fails, the provider build fails before deployment.
The symmetry matters. The consumer's build also fails if it asks for something no provider version has agreed to serve, which stops teams from quietly inventing endpoints that do not exist yet.
Use matchers, not literal values
A common early mistake is asserting that total equals 42.50. That passes once and fails forever, because test data changes. Assert that total is a number and let the provider return whatever it wants. Reserve exact matching for things that genuinely must be stable, such as an enum of status values or a fixed error code.
How Contract Testing Differs From Integration Testing
These two are complements, not substitutes, and confusing them leads teams to over-test in one place and under-test in another.
- Integration tests start real dependencies — a database, a message broker, sometimes the actual downstream service. They catch wiring mistakes, misconfigured connection strings, migration problems, and timeouts. They are also slow, prone to flakiness, and when they fail they usually tell you that something broke, not which team's assumption was wrong.
- Contract tests never touch the network. The consumer side runs against a mock in milliseconds; the provider side replays recorded requests against the service in-process. They fail in the exact pull request that introduced the incompatibility, with a message naming the consumer that will break.
A practical split: keep a small end-to-end suite for the paths that carry money or identity, and let contracts cover the dozens of ordinary boundaries between internal services. Integration tests still catch what contracts cannot — authentication middleware, gateway routing rules, serialization configuration, TLS, and actual latency.
The Breaking Changes Contracts Catch Early
Most production incidents between services fall into a handful of categories, and all of them are detectable at build time:
- A field renamed or removed from a response body.
- A type change, such as an ID moving from string to integer.
- An enum narrowed so a value the consumer sends is now rejected.
- A new required field added to a request body.
- A status code swap — 200 becoming 202, or a validation failure returning 400 instead of 422.
- An error payload reshaped, so a consumer reading message suddenly gets detail.
- A field that was always present becoming nullable or conditionally omitted.
None of these are exotic. They are the everyday result of refactoring, and each one costs far more to fix after a release than before it.
Where Contract Testing Does Not Help
Be honest about the limits. Contracts say nothing about whether the provider computes the right total, whether a query performs acceptably under load, or whether a background job eventually runs. Asynchronous messaging can be covered with message contracts, but ordering, retries, and duplicate delivery remain outside their scope. Third-party APIs you do not control cannot be verified this way; use schema validation against recorded responses and runtime monitoring instead.
There is also a cost to over-specifying. If a consumer asserts on twenty fields it never reads, every harmless provider cleanup becomes a false alarm, and teams start ignoring failures. Test what you use.
A Workflow You Can Run This Sprint
Pick the boundary that has broken most often in the last few months. Write one consumer test with type matchers for the three or four fields that matter, publish the contract, and add a verification step to the provider's pipeline. When that works, gate deployment on the verification result — a failing contract should block a release, not just post a warning. Retire contracts when consumers are decommissioned, or the provider team will spend years satisfying a service nobody runs.
Start Small and Gate the Deploy
Contract testing pays off as soon as it covers one fragile boundary. The suite runs in milliseconds, lives beside the code it describes, and gives both teams the same answer to the question that causes most cross-service outages: did anyone agree to this change? Set it up on a single integration, prove it catches a real break, then widen it. The goal is not perfect coverage — it is knowing about a breaking change while the pull request is still open, rather than from an alert at two in the morning.
Photo: ccfb / Pixabay
