Consumer-Driven Contract Testing with Pact and Spring Cloud Contract

Contract testing verifies that two services agree on their interaction — the consumer's expectations match the provider's behavior — without spinning up both services together.

Consumer-driven means consumer writes the contract first

• Consumer declares exactly what calls it makes and what responses it expects
• Provider verifies its real implementation against that contract
• Catches breaking API changes before they hit production
• Runs fast and in isolation

vs other approaches

• Integration tests require both services
• E2E requires the full system
• Schema validation only checks structure, not semantics
• Contract tests are fastest, cheapest, most targeted for service-boundary regressions

Two main tools

• Pact: cross-language, broker-based
• Spring Cloud Contract: Java-first, Groovy/YAML DSL, auto-generates stubs

Workflow

• Contract checked into Pact Broker (or Git)
• CI runs consumer publish + provider verify
• can-i-deploy gates ensure no incompatible release ships

The problem it solves

• Microservices: A calls B, evolve independently
• B changes response format → A breaks at runtime
• A sends new field → B silently ignores or crashes
• A relies on field B considers internal → A breaks on B refactor

Classic solutions and limits

• Integration with both running: slow, brittle, requires orchestration
• E2E in shared env: even slower; flaky; hard to isolate
• Schema (OpenAPI, JSON Schema): structure not behavior
• Manual coordination: doesn't scale

Contract testing flow

1. 1
   A's tests define contract (request → expected response)
2. 2
   A runs against mock provider built from contract
3. 3
   Contract published to shared broker
4. 4
   B's tests replay contract against B's real implementation, asserting response matches
5. 5
   If A or B changes incompatibly, verification fails in CI

Why consumer-driven

• Consumers know what they actually need
• Provider implements at least what consumers consume
• Anything not in any consumer's contract is fair game to change

Benefits

• Fast (no shared envs)
• Independent (one service at a time)
• Catches breaking changes before merge
• Documents the actual integration, not aspirational specs

Comparison table | Approach | Speed | Catches behavior | Catches schema | Both services? | Maintenance | | Schema (OpenAPI) | Fast | No | Yes | No | Low | | Contract (Pact) | Fast | Yes | Yes | No | Medium | | Integration WireMock | Fast | Partial | No | No | Low | | Integration both | Slow | Yes | Yes | Yes | High | | E2E | Very slow | Yes | Yes | Full system | Very high | | Prod canary | Real-time | Yes | Yes | Yes | Operational |

Pact consumer side (Java)

• @ExtendWith(PactConsumerTestExt.class)
• @PactTestFor(providerName=...)
• @Pact returns RequestResponsePact built via PactDslWithProvider
• given(...) describes precondition; uponReceiving describes interaction
• willRespondWith with status + body matchers (integerType, stringType, regex)
• @Test runs client against MockServer
• Generates target/pacts/-.json

Publish

• mvn pact:publish -Dpact.broker.url=...

Pact provider side

• @Provider, @PactBroker, @SpringBootTest(RANDOM_PORT)
• @LocalServerPort + HttpTestTarget
• @TestTemplate + PactVerificationInvocationContextProvider
• @State methods arrange data per precondition

Spring Cloud Contract alternative

• Groovy DSL contracts in provider's repo
• Build generates JUnit tests verifying real endpoint matches
• Publishes stub jar to Maven repo
• Consumer uses @AutoConfigureStubRunner with stub jar

Pact vs Spring Cloud Contract

• Pact: cross-language (JVM, Node, .NET, Python, Go, Ruby); Pact Broker; consumer-driven; great for polyglot
• Spring Cloud Contract: Java-first; provider-side DSL; great for Java-only; stub-runner for consumers

Message contracts (Kafka, RabbitMQ)

• Both tools support async/message
• Producer publishes events; consumer subscribes
• Contract: 'when event X, payload looks like Y'
• Producer test asserts event matches; consumer test runs against generated stub
• Pact MessagePactBuilder: given/expectsToReceive/withContent

Bidirectional contracts (Pact 2023+)

• Provider publishes OpenAPI spec; consumer publishes Pact contract
• Broker compares automatically
• Useful when one side can't/won't write Pact tests

CI integration

Consumer pipeline

• build → unit → pact consumer tests (generates pact)
• publish to broker (tagged: branch, version)
• can-i-deploy --version --to production
• pass = deploy; fail = block

Provider pipeline

• build → unit → fetch consumer pacts from broker
• verify each against current build (publishes results)
• can-i-deploy gate

Versioning and tagging

• Each pact published with version (git SHA) + tags (branch, env)
• Provider verifies against pacts tagged for prod/staging
• After deploy: tag with env name (prod)
• can-i-deploy --to prod checks compatibility with everything in prod

The matrix

• Provider versions × consumer versions × verification status
• can-i-deploy uses matrix to decide if your version is safe
• Magic that makes contract tests safe for independent deploys

Webhooks

• Consumer publishes new pact → broker triggers provider verify
• Pass → consumer deploy unblocks
• Fail → broker notifies both teams

Typical workflow

1. 1
   Consumer team adds dependency on provider field that doesn't exist yet
2. 2
   Consumer test passes locally (mock returns expected shape)
3. 3
   Publish pact (tagged with feature branch)
4. 4
   Provider CI sees new pact, fails verification
5. 5
   Provider team adds field, verifies, publishes
6. 6
   Consumer can-i-deploy passes; merge unblocked

Anti-patterns

1. 1
   Over-specifying matchers (exact UUIDs); use type/regex matchers for shape
2. 2
   Contracts as schema only; include behavior in given()
3. 3
   Skipping provider verification (defeats purpose)
4. 4
   Letting contracts drift (no CI; stale contracts)
5. 5
   One mega-contract; split per logical use case
6. 6
   No can-i-deploy gate (verification without gating = theater)
7. 7
   Testing trivial things (200 OK no body)
8. 8
   Provider state leakage (@State mutates shared DB)
9. 9
   Confusing 'shouldn't break consumer' with 'consumer's actual needs'
10. 10
    Testing internal API as contract

Where contract testing wins

• Microservices with multiple consumers of one provider
• Polyglot orgs (Pact's cross-language)
• Independent deploy pipelines per team
• Async/event-driven (message contracts)
• API gateway/BFF patterns

Where it adds less value

• Internal monolith calls (regular tests simpler)
• Single-consumer single-provider same team
• Public APIs with unknown consumers (use OpenAPI + versioning)
• Stable APIs that rarely change

vs OpenAPI

• OpenAPI = surface spec (structure, types, errors)
• Pact = runtime verification of actual interactions
• Use both: OpenAPI for docs + schema; Pact for verification
• OpenAPI doesn't catch 'consumer assumes field always non-null but provider sometimes returns null'
• Pact doesn't catch 'forgot to document endpoint'

vs WireMock

• WireMock: hand-written mocks; no link to real provider; drifts
• Pact: mock + verification on other side; prevents drift

vs E2E

• E2E: real services, real data, slow, flaky
• Pact: targeted, fast, isolated
• Both have value at different levels

Operational

• Pact Broker is essential infrastructure
• Self-hosted (OSS) or PactFlow (managed)
• Handles: storage, versioning, can-i-deploy, webhooks, dashboards
• Maintenance: prune old contracts from deleted branches
• Auth/RBAC for multi-team

Team dynamics

• Changes how teams collaborate
• Consumer responsible for stating expectations clearly
• Provider can't break without coordination
• Forces explicit communication; good
• Feels slow if teams used to YOLO breaking changes

Evolution and versioning

• API versioning (v1, v2) is orthogonal to contracts
• Contracts let you safely evolve within a version
• For breaking changes, version + run multiple until consumers migrate
• Backward-compatible additions don't break (ensure matchers don't reject extra fields)

Recommendations

• Polyglot microservices, independent deploys: Pact + Broker + can-i-deploy is gold standard
• Java-only, Spring-heavy: Spring Cloud Contract very ergonomic
• Event-driven: message contracts essential; both support
• Public APIs: stick with OpenAPI + versioning
• Always gate deploys with can-i-deploy
• Pair with OpenAPI-as-documentation; complementary not competing