Consumer-driven contract tests: verifying integrations without a shared environment

What it is

A contract test checks that two sides of an integration agree on the shape of their exchange without running both together. In the consumer-driven variant the consumer, which the Pact documentation defines as the side that initiates the request or reads the message, writes the contract: each interaction records an expected request and a minimal expected response, the parts of the response the consumer actually uses. The consumer test runs against a mock provider generated from that description, and the result is a pact file. Provider verification replays each request against the real provider and passes if the response contains at least the described data. Provider states ("user 123 exists") set up preconditions instead of chaining calls. Fowler's bliki describes the general form: contract tests confirm that a test double still matches the real service, and they run on the rhythm of the external service's changes rather than the consumer's pipeline.

Why it matters

Environments that start every service find breaking changes late, are shared, and fail for reasons unrelated to the change under test. Contract tests move detection into each service's own unit-test run and make coupling explicit: a provider can see which fields consumers depend on and which are free to change. The Pact Broker records which consumer and provider versions were verified against each other; the can-i-deploy command checks a version against the versions recorded as deployed to an environment and exits non-zero when a verification is missing or failed.

How to apply

• Generate interactions from the consumer's real client code; describe only the fields the consumer reads, and use type matchers where the exact value is not the point.
• Keep interactions independent; express preconditions as provider states, never as a sequence of calls.
• Publish pacts from the consumer pipeline, verify in the provider pipeline, record deployments, and gate releases on the compatibility check rather than on a shared staging run.
• Treat a failed verification as a conversation: either the provider's change breaks a consumer, or the consumer's expectation was stricter than what it needs.

Pitfalls

A contract that copies the provider's whole response is a second copy of the API and breaks on every change. Contract tests check shape and agreed semantics, not business rules, performance or authorisation. The contract is only as honest as the consumer about what it uses. Without a broker or an equivalent record of verified versions, the matrix is lost and teams fall back to "run everything together". Message-based integrations need the same discipline: the pact then describes the minimal message the consumer can handle.