API Contract Testing Explained: Catch Breaking Changes Before They Ship

The orders team renames total to amount because it reads better. Their own tests pass, and they deploy. Ten minutes later the mobile app shows every order as costing nothing, and the invoice service crashes. Each team tested its own code, but nobody tested the agreement between them. That gap is what contract testing fills.

We built a small contract as a JSON Schema and checked five realistic provider responses against it with the Python jsonschema library (version 4.26). The results below come from that run. Pact and OpenAPI tooling are described from their documentation; we did not run them for this article.

The problem with testing services in isolation

In a system of many services, each team writes unit tests and API tests for its own service. Those tests use the team’s own idea of what other services send and expect, often as mocks. When a provider changes, the consumer’s mocks still return the old shape, so the consumer’s tests keep passing. The mismatch is only discovered when both versions meet in a shared environment or in production. Full end-to-end tests can catch it, but they are slow, fragile and need everything deployed together.

What is contract testing?

Contract testing checks that two parties, a consumer that calls an API and a provider that serves it, agree on how they communicate: endpoints, methods, headers, request bodies, response fields, types and status codes. The agreement is written down as a machine-readable contract. Each side is then tested against the contract on its own: the consumer against a mock built from the contract, and the provider by replaying the contract’s requests against the real service.

Compared with other test types

Contract tests sit between API tests and integration tests in the test pyramid. They are nearly as fast as unit tests but catch problems that previously needed integration environments.

A contract check we ran

Here is a simple contract for an order response, written as a JSON Schema:

contract = {
  "type": "object",
  "required": ["id", "status", "total"],
  "properties": {
    "id":     {"type": "integer"},
    "status": {"enum": ["paid", "pending", "refunded"]},
    "total":  {"type": "number", "minimum": 0}
  }
}

We validated five versions of the provider’s response:

v1 provider              PASS
v1 + new field           PASS
renamed total->amount    FAIL: 'total' is a required property
id as string             FAIL: '101' is not of type 'integer'
new status value         FAIL: 'on_hold' is not one of ['paid', 'pending', 'refunded']

Adding a currency field was safe, because consumers ignore fields they do not know about. Renaming total, sending the ID as text, and introducing a new status value all broke the contract. Each of these would have passed the provider’s own tests.

Breaking vs safe changes

The enum case is subtle. Adding on_hold looks harmless to the provider, but a consumer with a switch statement over known statuses may crash or show nothing. Well-written consumers handle unknown values gracefully, and contracts make that expectation explicit. For versioning strategies when a breaking change is unavoidable, see semantic versioning and our REST API best practices.

Consumer-driven contracts

In consumer-driven contract testing, each consumer writes down exactly what it needs from the provider: the requests it makes and the fields it reads. The provider must satisfy every consumer’s contract. This has a big advantage: a provider can freely change or remove anything that no consumer uses, and it knows exactly which consumer would break if it changes something that is used.

Our demo checked a single schema, which is closer to the provider-driven style. A real consumer-driven contract would usually list only the fields that consumer actually reads, so a field used by nobody could be removed without any failure.

How Pact works

Pact is the most widely used consumer-driven contract tool, with libraries for many languages. The flow, from its documentation:

1. Consumer test: the consumer’s unit tests call a Pact mock server, declaring each expected request and the minimal response they need.
2. Pact file: those expectations are saved as a JSON contract, the “pact”.
3. Share: the pact is published to a Pact Broker or PactFlow.
4. Provider verification: the provider’s CI fetches all pacts, replays each request against the real provider, and checks the responses.
5. Can I deploy? Before deploying either side, a check confirms that the versions about to run together have verified contracts.

Provider states, such as “order 101 exists”, let the provider set up test data for each interaction. This is where most teams spend their effort when adopting Pact.

Provider-driven contracts with OpenAPI

Many teams start from the other direction: the provider publishes an OpenAPI specification, and tests check that the real API matches it, and that consumers only use what it describes. Tools can validate live responses against the spec, generate tests from it, or compare two versions of the spec and flag breaking changes. This works well for public APIs with many unknown consumers, where collecting consumer contracts is impossible. The trade-off is that it checks the grammar of messages, not which parts any consumer actually relies on.

Contract tests in CI

• Consumer pipeline: run consumer contract tests and publish the contract on every change.
• Provider pipeline: verify against all consumer contracts on every change; fail the build on any break.
• Before deploy: check compatibility between the exact versions going to each environment.
• Webhooks: when a consumer publishes a changed contract, trigger the provider’s verification immediately.

Fitting this into a CI/CD pipeline turns “did we break anyone?” from a meeting into a build status.

Pitfalls

• Over-specifying: asserting exact values instead of types and required fields makes contracts brittle.
• Treating contracts as functional tests: a contract checks shape and agreement, not business correctness. Keep functional tests too.
• Skipping provider states: without realistic setup data, verification passes for the wrong reasons.
• No ownership: someone must own the broker and respond when verifications fail.
• Forgetting asynchronous messages: events on queues are contracts too, and tools like Pact support message contracts.

When to use contract testing

Contract testing pays off when several teams own services that call each other, deployments are independent, and integration environments are slow or unreliable. For a single team with one API and one front end deployed together, good API tests may be enough. Our API testing guide covers that starting point.

Getting started without boiling the ocean

1. Pick one pair: the consumer and provider whose integration breaks most often, or matters most.
2. Write the consumer’s expectations for two or three key interactions, asserting only the fields it reads.
3. Verify the provider against them locally, fixing provider states until it passes for the right reasons.
4. Add both sides to CI, so either team learns within minutes when it breaks the agreement.
5. Review after a few weeks: did it catch anything, and did anything break that it missed? Then extend to the next pair.

Starting small keeps the effort visible and builds trust. Teams that try to put every service under contract at once often stall on tooling and test data before seeing any benefit.

Final thoughts

Contract testing catches the breaking changes that each team’s own tests cannot see: renamed fields, changed types and new enum values. Start with one important consumer-provider pair, keep contracts focused on what the consumer really uses, verify the provider in CI, and add a deployment check. In our simple test, three of five plausible changes would have broken consumers, all invisible to the provider’s own suite.

Frequently asked questions

Keep learning