Contract testing

Contract testing checks the agreement between two services in isolation. Each side is tested against a shared description of the interactions, the contract, instead of against the other service running live. If the provider changes a field name that a consumer relies on, a contract test fails in the provider’s own pipeline, before anything is deployed. It sits between integration tests and end-to-end tests in cost and confidence.

How consumer-driven contract testing works

The most common form, popularised by the Pact tool, is consumer-driven:

1. The consumer writes a test against a mock provider, stating the requests it sends and the parts of the response it actually uses. For example: GET /orders/42 returns 200 with an id number and a status string.
2. Running that test produces a contract file (a “pact”) recording those interactions.
3. The contract is shared, usually through a broker service.
4. The provider verifies the contract by replaying each recorded request against its real implementation and checking the responses match.
5. Before deploying, a team checks that the version they are about to release is compatible with the versions of the other side already in that environment.

Because the consumer only lists fields it uses, the provider is free to add fields or change anything no consumer depends on.

How it differs from related checks

• Schema validation checks a response against the provider’s published schema. It tells you the provider is consistent with its own documentation, not that it still meets each consumer’s needs.
• Integration tests call the real provider. They need both services and their dependencies running, and they tend to be slower and flakier.
• End-to-end tests prove a full journey works but are a slow and expensive way to discover that a field was renamed.

Provider-driven contracts, where the provider publishes an OpenAPI specification and consumers test against it, are an alternative when the provider cannot know or coordinate with all its consumers, as with a public API.

Common mistakes

• Specifying too much. Asserting exact values or every field turns contracts into brittle functional tests. Use type matchers and include only what the consumer reads.
• Testing business logic in contracts. Contracts check the shape of the conversation; correctness belongs in the provider’s own tests.
• Skipping provider states. “Order 42 exists” must be set up on the provider side during verification, or verification fails for the wrong reason.