Contract Testing

Contract testing

Replace slow, flaky cross-service end-to-end suites with fast tests that prove a consumer and a provider still agree on the messages they exchange.

When to invoke

• "Set up Pact between our services."
• "How do we stop the provider from breaking consumers?"
• "Can we deploy this service independently?"
• "Our end-to-end suite is too slow and flaky."
• "Add provider verification to CI."

What a contract test actually proves

A contract test verifies the interaction between two services, not the behavior of either one.

Contract tests do not replace unit tests or a small end-to-end smoke suite. They replace the large, brittle middle layer.

Consumer-driven flow

The consumer states what it actually uses. The provider proves it still delivers that.

1. Consumer test runs against a mock provider and records expectations.
2. A pact file is produced describing each request and expected response.
3. The pact is published to a broker, tagged with branch and version.
4. Provider verification replays every interaction against the real provider.
5. can-i-deploy gates the release by checking verification results for the target environment.

// Consumer expectation: only the fields this consumer reads
await provider.addInteraction({
  state: 'user 42 exists',
  uponReceiving: 'a request for user 42',
  withRequest: { method: 'GET', path: '/users/42' },
  willRespondWith: {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
    body: { id: like(42), email: like('a@b.com') },
  },
});

Use matchers such as like for types rather than exact literals. Asserting exact values couples the contract to fixture data and produces false failures.

Provider states

Each interaction declares the precondition it needs. The provider implements a handler that establishes it.

• Keep state handlers fast and isolated; they run once per interaction.
• Set up data through the fastest safe path, not through the public API.
• Never let one state handler depend on another having run first.

Only specify what you consume

The strongest rule in contract testing: a consumer must assert only the fields it actually reads.

Over-specifying makes the provider unable to add fields without breaking a consumer that never used them. That converts an additive, backward-compatible change into a false breakage and destroys trust in the suite.

CI integration

Publish verification results back to the broker. Without them, can-i-deploy has no evidence and either blocks everything or nothing.

Limits

• Do not use contract testing for performance, authorization depth, or business-rule correctness; those need their own tests.
• Do not use it to test a third-party API you do not control; you cannot run provider verification there. Use recorded integration tests instead.
• Do not use it as the only integration signal for asynchronous flows without also verifying message ordering and delivery semantics.

Gotchas

• A pact is not an API specification. It captures only observed interactions from real consumers, so it is deliberately incomplete.
• Unpublished verification results silently disable the gate. Confirm results reach the broker.
• Branch and tag hygiene drives correctness. Verifying only main while deploying a feature branch proves nothing about that branch.
• Exact-value matchers create false failures. Prefer type matchers except where the exact value is genuinely part of the contract.
• Removing a consumer does not remove its pact. Stale pacts block providers; retire them deliberately.

Output template

## Contract testing result

**Status:** verified | broken-contract | not-configured
**Summary:** <consumer, provider, and the outcome>

### Details
| Interaction | Provider state | Result |
| --- | --- | --- |
| <description> | <state> | <pass or fail with reason> |

Broker: <where pacts and results are published>
Deploy gate: <can-i-deploy outcome for the target environment>

### Validation
- Consumer asserts only consumed fields: <checked and result>
- Verification results published: <checked and result>

Quality gate

• The consumer asserts only fields it actually reads.
• Type matchers are used except where an exact value is part of the contract.
• Every interaction has a fast, isolated provider state handler.
• Pacts are published with meaningful version and branch tags.
• Provider verification results are published back to the broker.
• A deploy gate consults verification results for the target environment.
• Scope boundaries are stated; contract tests are not presented as end-to-end proof.

References

• Pact documentation
• Pact Broker
• can-i-deploy