A food delivery company has an Orders service and a separate Restaurant service, owned by two teams sitting on different floors. One Friday the Restaurant team renames a response field from prepTime to preparationMinutes, because it reads better. Their unit tests pass. Their API tests pass. The Orders team’s tests also pass, because they mock the Restaurant service using last month’s response. On Monday, estimated delivery times on the app show blank. Nobody’s tests were wrong; they were just checking each side against its own assumptions.

Contract testing is designed to catch this specific class of failure: two independently built components that each work, but no longer agree on how to talk to each other.

The contract as a shared artefact

A contract is a precise record of the interactions one service (the consumer) relies on from another (the provider): which requests it sends, and which parts of the responses it reads. The important word is “relies”. The Orders service probably reads four fields out of the twenty the Restaurant service returns. The contract lists only those four. If the provider changes the other sixteen, nothing breaks, and the contract says so.

The contract is checked from both ends, at different times, without the two services ever running together.

How consumer-driven contract testing works, step by step

Pact is the most widely used tool for this style, and its workflow is a good model of the idea.

  1. The consumer writes a test against a mock. The Orders team writes a test saying: given a restaurant with ID 42 exists, when I request its details, I expect a 200 response containing a numeric prepTime and a string name. Pact starts a local mock provider that answers exactly that way, and the Orders client code runs against it. This proves the consumer’s own code can handle that response.
  2. The test produces a contract file. As a by-product, Pact records the interaction in a JSON “pact” file. This file is the contract.
  3. The contract is shared. Teams usually publish it to a Pact Broker (open source) or a hosted equivalent, tagged with the consumer’s version and branch.
  4. The provider verifies it. In the Restaurant team’s pipeline, a verification step fetches every contract that consumers have published, replays each recorded request against the real Restaurant service, and checks that the real responses satisfy what was recorded. If prepTime has vanished, verification fails in the Restaurant team’s build, before they deploy.
  5. Deployment checks the matrix. Before either side deploys, a check (Pact’s is called can-i-deploy) asks the broker whether this version has been verified against the versions of its partners currently in the target environment.

The phrase “given a restaurant with ID 42 exists” is a provider state. The provider team implements a small hook that sets up that data before the replayed request, so verification does not depend on whatever happens to be in a shared database.

How this differs from integration testing

AspectIntegration / end-to-end testContract test
What must be runningBoth services, plus their databases and dependenciesOne service at a time
When a failure appearsAfter both changes are deployed to a shared environmentIn the build of the team that broke the agreement
What it provesThe two services work together end to end, including behaviourThe two services agree on request and response shape for the interactions the consumer uses
Main costEnvironments, data setup, slow and flaky runsDiscipline to write and publish contracts; a broker to run

The second row is the real benefit. With integration tests, the Restaurant team’s rename would be discovered in a shared staging environment, often by someone on the Orders team, and then argued about. With contract tests, the Restaurant team’s own pipeline tells them, with the name of the affected consumer, before the change leaves their hands.

What contracts do not check

Contract testing is about shape and agreed examples, not full business correctness. A provider could return a perfectly formed prepTime of 0 for every restaurant, and the contract would pass if the consumer only asked for a number. Functional tests inside the provider must still check that the value is right. Pact’s own documentation warns against using contracts to test provider business logic: each extra rule in a contract couples the teams more tightly and makes legitimate changes harder.

Contracts also say nothing about performance, security, or behaviour under load, and very little about long chains of calls across five services. A small number of end-to-end journeys is still worth keeping for those.

Variations and practical decisions

Provider-driven or schema-based contracts. Some teams treat an OpenAPI specification as the contract and check both sides against it. This is simpler to adopt, especially with public APIs where you do not know your consumers, but a schema describes everything the provider might return, not what each consumer actually uses, so it cannot tell you which changes are safe for whom. PactFlow offers a “bi-directional” approach that compares consumer pacts against the provider’s OpenAPI document, as a middle path.

Messages, not just HTTP. Event-driven systems using Kafka or RabbitMQ have the same problem: a producer changes an event’s payload and consumers break silently. Pact and similar tools support message contracts, where the consumer records the event shape it expects and the producer verifies it can generate it.

Loose matching. Contracts should usually match on type and format rather than exact values (“a number”, “an ISO date”) so that the provider can return realistic data. Exact matching on values creates contracts that fail for irrelevant reasons.

Organisational fit. Consumer-driven contracts work best when teams can talk to each other and the provider is willing to run consumers’ contracts in its pipeline. For a third-party API such as a payment gateway, you cannot make them verify your contract; the best you can do is record their responses and re-check your assumptions regularly against their sandbox.

The underlying shift is cultural as much as technical. Integration testing asks, after the fact, “does it all still work together?” Contract testing makes each team responsible, at build time, for not breaking the promises it has made to others.

Written by the RP Strativa Team. The company, services and field names in the examples are illustrative.

Leave a Reply

Trending