Evolving contracts safely and the limits of contract testing

The pricing team needs to rename amount_cents to price_minor_units — a name three downstream consumers read. Sam’s instinct is to do it in one PR: rename the field, update the schema, ship. The provider’s own contract tests stay green, because the broker only has the current consumer pacts and they all still expect amount_cents… wait, no — they expect the old name, so verification against the renamed provider fails for all three. Good, the gate caught it. But now Sam is stuck: he can’t deploy without breaking three teams, and he can’t make three teams change in lockstep with him. The contract gate told him the change is breaking; it did not tell him how to ship it anyway. The whole quarter, contract tests have quietly replaced a dozen flaky cross-service e2e suites — and that success is exactly why nobody noticed the one bug they never caught: last month pricing returned a structurally-perfect amount_cents: -500 for a refund, every contract passed, and checkout charged a negative balance. The shape was right. The number was wrong. No contract test on earth asserts that.

Expand-then-contract: how to break a provider without breaking consumers

A consumer-driven contract gate has a built-in asymmetry that feels like a trap the first time you hit it: it will block a breaking provider change, but blocking is not the same as enabling. You still have to ship the rename. The technique is expand-then-contract (also called parallel change or additive change), and it turns one breaking change into three non-breaking deploys, each of which keeps every contract green.

1. Expand. Deploy a provider that supports both the old and the new shape simultaneously. For Sam’s rename, that means returning amount_cents and price_minor_units with the same value. Every existing pact still verifies — consumers read amount_cents and it’s still there — so can-i-deploy says yes and the provider ships with zero consumer changes.
2. Migrate. One at a time, on their own schedule, each consumer updates its test to read price_minor_units, which regenerates its pact to expect the new field. The provider already returns it, so each migrated consumer’s pact verifies immediately. There is no lockstep: three teams migrate across three sprints if they want.
3. Contract. Once can-i-deploy confirms no consumer pact in production still references amount_cents — the broker knows this from the deployment matrix — the provider deploys a version that drops the old field. Nothing depends on it anymore, so the removal is non-breaking.

The discipline is that you never delete in the same step you add. The window where both shapes exist is the price of zero-downtime evolution; the broker’s can-i-deploy is what tells you when that window can safely close. Skip the expand step and you are back to coordinating a flag-day rename across three teams — the exact pain contracts exist to eliminate.

Pending and WIP pacts: don’t let a not-yet-built feature redden the provider

Expand-then-contract handles provider-led change. The mirror problem is consumer-led change: a consumer adds a new expectation (a new endpoint, a new field) before the provider has implemented it. The consumer publishes the new pact, the provider’s next verification run replays it, the provider doesn’t satisfy it yet — and the provider’s main build goes red over a feature the provider team hasn’t even started. That is backwards: a consumer’s work-in-progress should not break an unrelated provider’s pipeline.

Pending pacts fix this. When a consumer publishes contract content the provider has never successfully verified, the broker flags it as pending. The provider still runs verification against it and still reports the result back to the consumer — so the consumer gets honest feedback — but a pending failure does not change the provider build’s exit code. The build stays green. The moment that pact is verified successfully once, it transitions out of pending; from then on, a failure is a real regression and will fail the build. Enable it with enablePending: true on the provider’s verification config.

WIP pacts build on top of pending. Pending still requires the provider to be told which pacts to pull (by tag or branch). WIP pacts (includeWipPactsSince with a date) make the provider automatically pull in any new, not-yet-verified pact applicable to it — no config change per consumer feature. For WIP pacts the pending flag is hardcoded on, so they can never fail the build either. Together they let a consumer push a new expectation on Monday, see real verification feedback, and the provider team picks it up when they’re ready — without a red build pressuring either side into a flag day.

Bi-directional contract testing: compare two artifacts, run no provider code

Classic consumer-driven verification has a cost most teams underweight: the provider must execute the consumer’s pacts. The provider runs its real service, sets up each providerState, replays every interaction, and asserts the responses. That requires the provider team to wire up state handlers and run consumer tests they don’t own — friction that grows with every consumer.

Bi-directional contract testing (BDCT) decouples the two sides. The provider publishes the artifact it already produces — its OpenAPI spec — to the broker, with no provider-side test execution at all. Each consumer publishes its pact as usual. The broker then statically compares the consumer’s pact against the provider’s OpenAPI: does the spec contain every endpoint, field, and type the pact expects? Compatibility is a document-vs-document check, not a code run. That is the appeal — the provider adds no test code, just publishes a spec it likely maintains anyway, and the broker tells both sides whether they fit.

The trade is trust placed in the spec. CDC verifies the consumer’s expectations against the provider’s actual running behavior; BDCT verifies them against the provider’s declared behavior. If the OpenAPI spec lies — describes a field the code doesn’t return, or omits one it does — BDCT passes a contract that CDC would have failed. BDCT is only as honest as the spec, so mature BDCT setups generate or validate the spec from the provider’s own tests rather than hand-maintaining it. Note also that BDCT is a PactFlow/SmartBear feature, not part of the OSS Pact Broker.

The hard limits: shape is not semantics, and known consumers are not all consumers

Contract testing is bounded by what a contract can express, and a senior earns trust by naming those bounds before someone discovers them in production.

• It tests shape and interaction, never business logic or semantics. A contract asserts amount_cents is an integer; it cannot assert the integer is the correct price, is non-negative, or matches the order total. The refund that returned -500 had a perfect shape and broke checkout. Contract tests catch structural breaks between services; they are blind to wrong values, wrong calculations, corrupted data, and broken multi-step workflows.
• It needs known consumers. A consumer-driven contract is the union of what known consumers declare. For a public API with unknown, external consumers, there is no one to author the pacts and no way to enumerate what’s depended on — so CDC simply doesn’t apply. (Spec-first or BDCT against a published OpenAPI is the better fit there, but even that can’t know which external clients read which field.)
• It adds real infrastructure. A broker to run and secure, pact publishing wired into every consumer’s CI, verification wired into every provider’s CI, can-i-deploy gates, deployment recording. That overhead is justified between a handful of internal services that change often; it is overkill for two services that talk via a stable, rarely-changing interface.
• It can give false confidence when provider states diverge from real data. Verification runs against the data you set up in each providerState. If your fixtures are tidier than production — no nulls, no legacy rows, no the-currency-was-once-stored-as-a-string mess — every contract passes while the real provider, fed real data, returns shapes your fixtures never produced. Green contracts then certify a fiction.

This is why the senior judgment call is not “contracts or e2e” but both, in proportion. Contract tests can correctly replace most cross-service e2e for known internal consumers — they are faster, more stable, isolate the failing pair, and don’t need a full environment. But they are not a substitute for a few real end-to-end smoke tests that exercise the actual deployed services together on real-ish data. Keep a thin layer of e2e for the things only a real run catches: business-logic correctness across hops, data that doesn’t match your fixtures, auth and config wired end to end. The pyramid is many contract tests, a few e2e smoke tests — not all of one.