1. LandOffer
  2. Blog
  3. All articles
  4. Use Contract Tests to Catch Integration Mismatches Before Deployment

Engineering Practice

Use Contract Tests to Catch Integration Mismatches Before Deployment

Connect consumer expectations with provider-version evidence before deployment. Use an original local HTTP contract example, retained field and type failures, and a completed version matrix to distinguish interface compatibility from business correctness.

9 min readLandOffer team

Use contract tests to verify the messages an actual consumer needs and the responses a provider version produces before deciding that the pair can be deployed together. Test the consumer against the agreed example, then replay that contract against the provider implementation. Keep the version pair and verification result together. A mock that satisfies the consumer establishes its handling assumption; the provider version still needs its own verification.

This LandOffer.ai guide uses an original local HTTP example with two consumer contracts and three provider variants. We actually ran the isolated requests and compatibility checks described below. All services, versions, session records and deployment decisions are fictional; no production API, Pact SDK, Pact Broker, CI pipeline, account or deployment was operated.

Two workshop specialists hold separate metal couplings above a paper assembly drawing on a wooden bench.

Separate consumer assumptions from provider evidence

Pact's explanation of its workflow describes interactions containing the request a consumer sends and the response it needs. Consumer testing exercises request generation and response handling against a mock. Provider verification replays those interactions against provider code and compares the response with the contract.

These are complementary checks. A consumer can work perfectly with its own mock while the real provider returns another field name. A provider's unit tests can pass while none of them represent what a currently deployed consumer reads. Check the exact consumer/provider pair instead of treating those separate successes as compatibility evidence.

Contracts should describe consumed interface requirements, not every internal detail of the provider. An extra response field may be harmless if the consumer ignores it. A removed required field, changed type or different request path can break that consumer even when the provider regards the change as cleanup.

The example here implements that distinction with a small handwritten matcher and Python's HTTP standard library. Its JSON contract files are illustrative artifacts, not Pact-format files, and its results are not Pact verification output. The primary Pact documentation explains the production workflow; the local implementation makes a limited compatibility mismatch inspectable without claiming a framework or Broker installation.

Worked asset: a consumer contract and a breaking provider change

The fictional consumer displays capacity for workshop session S42. Consumer C1 reads remainingSeats; candidate C2 reads the proposed name seatsRemaining. Each needs an integer count, the session identity and a boolean waitlist field. No reservation is made, and the service does not establish actual availability at any venue.

Both consumers send the same request:

GET /sessions/S42/capacity
Accept: application/json

The complete minimal interaction packet is filled as follows:

Contract item C1 requirement Candidate C2 requirement
Request GET at the exact session-capacity path with Accept: application/json Same method, path and Accept value
Successful response HTTP 200 with application/json media type Same status and media type
Identity sessionId equals S42 for this requested fixture Same identity
Required count remainingSeats exists and is a nonnegative integer seatsRemaining exists and is a nonnegative integer
Other consumed field waitlistOpen is a boolean Same field and type
Extra fields Allowed; this consumer ignores unconsumed fields Allowed under the same narrow matcher
Provider preconditions Independently prepare “seven seats available” and “session full” Prepare the same two independent fixture states

For the available state, baseline provider P1 returns:

{"sessionId":"S42","remainingSeats":7,"waitlistOpen":false}

Candidate P2 removes the old field and serializes the new count as text:

{"sessionId":"S42","seatsRemaining":"7","waitlistOpen":false}

Those are actual responses from the authored loopback HTTP fixture. P2 breaks C1 because remainingSeats is absent. It also fails C2's contract because the new value is a string, not an integer. Renaming the field and repairing the type are distinct compatibility questions. Recording both failures tells the owners why updating only the consumer field name would still leave the integration broken.

The revised P3 variant returns both names as integers, along with an additional revision field. In this example both aliases come from the same fixture count, so they agree. That additive transition supports the two tested consumers without requiring them to change at exactly the same time. Provider owner Soren must preserve alias consistency and verify all relevant active consumers before proposing retirement. The local aliases share one synthetic count; no real database or deployed consumer registry was checked.

Prove that the consumer uses the contract

Our consumer checks make real HTTP requests to a local mock bound only to 127.0.0.1 on an ephemeral port. The server verifies method, path and Accept value. C1 and C2 each consume their expected response for the seven-seat and full-session states, producing a parsed count and waitlist boolean. All four consumer checks pass in Python 3.12.14. The retained receipt records each request, parsed output and provider response; the loopback server is shut down after the run.

The zero-count example matters: the consumer retains integer zero rather than treating a full session as missing data. These checks verify the authored consumer's request and handling for those supplied responses. They do not establish that a provider calculates available seats correctly or that any booking can be completed.

The mock represents an assumption the consumer can handle. Keep that assumption attached to the consumer version that generated it. A manually edited response example that the consumer never parses can drift away from actual code. Likewise, a consumer test that supplies a completed domain object rather than exercising its HTTP-facing adapter may miss request or parsing assumptions.

In this package the expected fields are explicit and the original consumer functions actually parse the response. There is no authentication implementation: Accept is a content-negotiation header, not a credential. No success in this fixture should be described as identity, permission or security verification.

Verify independent provider states and retain failures

Pact's provider-state guidance treats a state as a precondition for an interaction and recommends verifying interactions independently. Preparing a full session should not require a previous contract test to create enough bookings first. That would introduce an order-dependent business workflow into what is meant to be a focused interface check.

For each local verification, the harness sets one synthetic provider state directly in memory before requesting the endpoint. There is no state-setting production route or external database. It then compares the actual HTTP status, media type and consumed response fields against the selected contract.

The matcher checks count presence and nonnegative integer type, explicitly excluding Python booleans from the integer rule. The stored raw responses show seven and zero in the two fixtures, but the generic count matcher does not prove that a full session always computes zero or that count and waitlist reflect real capacity. Those semantic rules need separate functional evidence; two well-shaped fixture responses do not establish correct real-world capacity.

Pact's verification documentation separates the recorded contract from the provider run and its published verification result. Our local harness follows the conceptual replay/check sequence only. It does not publish a result anywhere, invoke a Pact verifier or claim equivalence with all Pact matching semantics.

Across three provider variants, two contracts and two states, the harness performs twelve provider checks. Combined with the four consumer checks, it makes sixteen local HTTP requests. P2's expected incompatibilities remain recorded failures; they are not hidden to make every cell green. A successful harness run means those observed pass/fail results match the explicit expectations.

Two specialists examine brass fittings beside a tray of metal connectors and a paper connection drawing.

Worked asset: the filled version-compatibility decision matrix

The matrix below aggregates each pair's two provider-state checks. Pass means that both interactions satisfy the narrow local contract. Fail means at least one does not; here the same mismatch occurs in both states. It is not a Pact Broker matrix or a real deployment inventory.

Consumer and required field P1: old integer field P2: renamed string field P3: both integer aliases
C1: remainingSeats Pass, two states Fail: required old field missing Pass, two states; extra fields allowed
C2: seatsRemaining Fail: required new field missing Fail: new field is string Pass, two states

The accompanying fictional environment record says C1 is currently active with P1, while C2 and P3 are candidates. This is an authored planning premise, not information retrieved from a deployment system. Delivery owner Petra uses it to complete the following decisions.

Do not deploy P2 against active C1. Its field removal breaks the known consumer contract. Do not deploy C2 against P1 either: the required new field is absent. P2 is not a working bridge for C2 because its count type is also wrong.

Consider P3 before C2, subject to the remaining gates. P3 passes the C1 and C2 contracts in both local states. Provider owner Soren retains the old field for C1; consumer owner Nelle can then evaluate C2 against the actually deployed provider version. These results justify that proposed compatibility order in the example, not immediate production deployment.

Keep removing remainingSeats unapproved. A new consumer version passing does not prove all old instances or other consumers have disappeared. Soren needs evidence of the versions still active in the target environment and verification for every relevant consumer before removing the alias. A contract absent from the repository is not evidence that its user retired.

Petra's completed memo is: “Reject the P2 route and hold C2 against P1. Retain P3 as the compatibility candidate, preserving both integer fields. Nelle owns consumer evidence; Soren owns provider verification and active-version reconciliation. Operational, security and release checks remain pending. No deployment is authorized by this local matrix.”

Ask the deployment question about the right versions

Pact Broker's can-i-deploy guidance describes evaluating verified consumer/provider version relationships against recorded environment deployments or releases. A result for the latest development branch is not necessarily a result for the versions that must coexist in production. Correct version identity and environment records are part of the evidence, not optional administrative detail.

In a real pipeline, preserve immutable application versions, the contract identity and the verification result for that pair. Reconcile deployed versions before making a compatibility decision. Missing verification should remain unknown and block the relevant decision under the team's policy; it should not quietly turn into a pass because no test failed.

This article does not execute can-i-deploy or invent a Broker response. Its finite local matrix shows how the question changes when the consumer or provider changes. The actual deployment gate also needs the team's release authority and evidence beyond interface compatibility.

Keep contract coverage narrower than end-to-end correctness

A passing contract can show that a tested provider emits fields the consumer can handle. It does not establish that the database is current, concurrency preserves seat counts, an authorization boundary is correct, reservations succeed or a user completes their task. Failure responses, timeout behavior and other endpoints are outside this deliberately small packet.

Extend coverage when a consumer genuinely depends on those interface cases. Avoid adding unused provider fields simply to duplicate the complete response schema. Retain functional, security, resilience and end-to-end tests for the questions they answer, with their own environments and limits.

For the next integration change, bring one consumed interaction, its consumer execution, provider-state setup, provider result and exact version pair to review. More engineering guides are available from LandOffer.ai. Keep the incompatible route on hold. Before a real release, reverify the replacement against the versions that must coexist and retain the separate operational and authorization decisions.

Sources and Further Reading

  • Pact: How Pact works — updated December 23, 2024; current primary body checked October 27, 2026.
  • Pact: Provider states — updated July 5, 2024; current primary body checked October 27, 2026.
  • Pact: Verifying Pacts — updated August 19, 2020; current primary body checked October 27, 2026.
  • Pact Broker: Can I Deploy — updated October 5, 2022; current primary body checked October 27, 2026. No Broker or deployment command was run.