Contract Testing Fundamentals

## Three workflows, three obligations A contract-testing workflow is settled by three organisational facts, not by cleverness: **who authors the artefact first**, **where that artefact lives**, and **whose build turns red when the two sides disagree**. Pact, Spring Cloud Contract and bi-directional contract testing answer those three questions differently, and every other difference follows from the answers. | Workflow | Artefact written by | Published to | Red build lands on | Guarantee bought | | --- | --- | --- | --- | --- | | Consumer-driven (Pact) | The consumer, as a by-product of its own test | A Pact Broker | The provider's verification job | The running provider satisfies expectations a real consumer holds | | Producer-first (Spring Cloud Contract) | The provider, by hand | The provider's repo, plus a stub jar in an artifact repository | The provider's generated tests, and any consumer whose stub run drifts | The provider does what it declared, and consumers build against that declaration | | Bi-directional | Both sides, independently | A broker that cross-checks the two documents | Whichever side published the incompatible document | Two documents agree on paper | ## Consumer-driven: the consumer writes the obligation In Pact the consumer writes an ordinary test whose HTTP calls go to Pact's **local mock provider**. The mock answers with the response the test declared, the test asserts the consumer's own client code handled it, and the run emits a **pact file**: a JSON document naming a `consumer` and a `provider` and listing the interactions that were exercised. The consumer publishes that file to a **Pact Broker**. The provider later fetches the pacts written for it and replays each interaction against the real service, publishing the results back. The consequence is organisational rather than technical: **a mismatch fails the provider's build, over an expectation the provider's team never wrote.** That is the entire point of the workflow, because it turns one consumer's real needs into a blocking concern for the provider. It is also its cost, because it only functions where the provider team accepts that obligation. Two properties follow. First, a pact protects exactly what some consumer exercised; a response field no consumer test touches is not covered by anything. Second, the consumer cannot unilaterally impose new behaviour: a newly recorded expectation is a request until the provider agrees to satisfy it. The artefact carries a conversation, it does not replace one. ## Producer-first: the provider declares and ships stubs Spring Cloud Contract reverses the direction. The provider authors contracts — Groovy DSL or YAML files — inside its own repository. Its build plugin does two things with them. It **generates provider-side verification tests** that fail if the service stops matching its own declaration, and it packages the same contracts into a **stub jar** published to an artifact repository. Consumers pull that stub jar and run their tests against it using Stub Runner, instead of against a hand-written mock they maintain themselves. The obligation is reversed with the direction. The provider is never surprised by an expectation, because it wrote every one of them; consumers, in exchange, lose the ability to state a need in a form that blocks the provider's release. What they gain is a stub guaranteed to behave like the provider, because both are generated from the same file. This workflow suits an organisation where the provider is the design authority for its API and the consumers are numerous, downstream, or simply not going to write tests for someone else's service. ## Bi-directional: cross-checking two documents Bi-directional contract testing keeps both sides independent. The provider publishes a specification of its API, each consumer publishes its recorded expectations, and a broker supporting this mode cross-checks whether every consumer expectation could be satisfied by the provider's specification. Nothing is replayed against a running service. That buys the lowest adoption cost — neither team adds a job to the other's pipeline, and neither has to wait for the other — and, in exact proportion, the weakest guarantee. The comparison is between a declaration and an expectation, so the verdict inherits the accuracy of the provider's specification. If that document has drifted from the deployed code, the cross-check will approve a pair that cannot actually talk. Consumer-driven verification catches exactly that drift, because it executes the provider. ## Choosing between them 1. **Can every consumer be asked to write and maintain a test?** If yes, consumer-driven produces the strongest evidence available. 2. **Will the provider's pipeline treat a verification failure as blocking?** If not, consumer-driven degrades into a wish list, and producer-first or bi-directional is the more honest choice. 3. **Is the provider the design authority, with many or unknown consumers?** Producer-first scales better: one declaration, stubs for everybody. 4. **Do you need behavioural evidence for this interface at all?** Bi-directional is a deliberate trade for a low-churn edge, not a lesser tool. The failure worth avoiding is running two workflows on one interface without deciding which verdict wins. A stub-jar consumer and a recorded pact on the same endpoint give two sources of truth, two maintenance costs, and two unrelated ways for a release to go red.