Skip to content
System Design Lab
Microservice Patterns

Consumer-Driven Contract Testing

Let each consumer publish the exact parts of an API it relies on, and make the provider's build verify them — so breaking changes are caught in CI instead of in production, without slow end-to-end test environments.

Intermediate 4 min read· Updated 2026-11-18

What you will learn

  • Explain why provider unit tests and shared environments miss breaking changes.
  • Write a consumer contract and verify it in the provider build.
  • Evolve APIs safely with additive changes and expand/contract.
  • Place contract tests among unit, component and end-to-end tests.

Before you start

Overview

A plug manufacturer could test its plugs alone and still ship ones that do not fit anyone's socket. Better: socket makers send their exact measurements, and every new plug design is checked against them before it leaves the factory.

In microservices, the provider's tests prove it does what *it* thinks is right, not what its consumers depend on. End-to-end environments catch mismatches, but slowly and flakily. With consumer-driven contracts, each consumer records the requests it sends and the fields it reads (a contract), publishes it to a broker, and the provider's CI verifies every contract against the real provider code before it can deploy.

Run it

Customers v2 renames a field that checkout reads. In A the change reaches production; in B the contract test failed in CI and an additive version shipped instead. Compare Checkouts failed.

Loading simulation…

A Pact contract

Consumer side: checkout describes what it needs
@Pact(consumer = "checkout", provider = "customers")
V4Pact customerTier(PactDslWithProvider builder) {
    return builder
        .given("customer 42 is a gold member")
        .uponReceiving("get customer 42")
            .path("/customers/42").method("GET")
        .willRespondWith()
            .status(200)
            .body(newJsonBody(b -> { b.stringType("name", "Ada"); b.stringValue("tier", "gold"); }).build())
        .toPact(V4Pact.class);
}
Provider side: the customers build replays every consumer's contract
@Provider("customers")
@PactBroker                                            // fetch contracts of all consumers
@SpringBootTest(webEnvironment = RANDOM_PORT)
class CustomersContractTest {
    @TestTemplate @ExtendWith(PactVerificationInvocationContextProvider.class)
    void verify(PactVerificationContext ctx) { ctx.verifyInteraction(); }

    @State("customer 42 is a gold member")
    void gold() { customers.save(new Customer(42, "Ada", Tier.GOLD)); }
}
// CI gate: `pact-broker can-i-deploy --pacticipant customers --to-environment production`

Trade-offs

BenefitsCosts
FeedbackBreaking changes fail the provider's build within minutes.Only checks what consumers wrote down; behaviour beyond the contract is untested.
SpeedNo shared end-to-end environment needed for integration confidence.Teams must maintain contracts and provider states.
AutonomyProviders know exactly who uses what, and can change the rest freely.Needs a broker and CI discipline across teams.

Production considerations

  • Gate deployments with can-i-deploy for both consumers and providers.
  • Keep contracts minimal: only the fields the consumer actually reads (use type matchers).
  • Combine with service component tests (the service with its dependencies stubbed) and a thin layer of end-to-end smoke tests.
  • Apply the same idea to events: contract-test message schemas between producers and consumers.

Further reading

Related topics