Spring Cloud Contract: Producer Contracts, Stub Runner, Consumer Verification

What Spring Cloud Contract is

• Producer-driven contract testing framework from Spring Cloud
• Producer writes contracts in Groovy or YAML DSL
• Maven plugin auto-generates two artifacts: JUnit tests that verify the producer, and a WireMock stub JAR published alongside the service
• Consumers pull the stub JAR and test against WireMock as if it were the real producer
• No live producer needed in consumer tests; no shared integration environment

The producer setup

• Add spring-cloud-starter-contract-verifier dependency in test scope
• Add spring-cloud-contract-maven-plugin with baseClassForTests configured
• Write contracts under src/test/resources/contracts in Groovy DSL
• Contracts describe request and response: method, URL, headers, body, matchers
• Create a base class that sets up Spring context and mocks collaborators so generated tests can call real controllers
• mvn verify generates tests, runs them, builds the stub JAR

The consumer setup

• Add spring-cloud-starter-contract-stub-runner dependency
• Use @AutoConfigureStubRunner with ids = group:artifact:version:stubs:port
• StubsMode REMOTE pulls from artifactory; LOCAL uses ~/.m2; CLASSPATH uses classpath
• Consumer code hits localhost:port and sees WireMock responses that match the contract

The key workflow

• Producer writes contract in its own repo
• Producer CI runs mvn verify, fails if implementation drifts
• Producer publishes stub JAR to artifactory
• Consumer CI pulls stub, runs tests against it
• If producer changes contract in a breaking way, either producer's own test fails or consumer's test fails — CI catches it before deploy

Contrast with Pact

• Pact is consumer-driven: consumers record expectations, producer verifies them against the broker
• SCC is producer-driven: producer is the source of truth
• Pact fits polyglot orgs and diverse consumer expectations
• SCC fits Spring-heavy orgs; also excels at messaging contracts

Messaging contracts

• SCC supports Kafka and RabbitMQ contracts the same way
• sentTo and outputMessage describe produced messages
• triggeredBy runs a producer method that emits the message
• Consumer tests assert correct consumption without running real brokers

Version pinning strategy

• Pin specific stub version in release branches for stability
• Use + (latest) in canary jobs to detect drift early
• Automate bumps with Renovate or similar

Common pitfalls

• Forgetting to configure BaseClass — generated tests fail at compile
• Publishing stubs only to local Maven — consumers in CI can't pull
• Writing contracts so loose they catch nothing — add bodyMatchers with regexes
• Mixing contract tests with integration tests — keep them separate; contract for shape, integration for logic
• Hardcoding ports in consumer tests — use ${stubrunner.runningstubs...port}

Limitations to acknowledge

• Static stubs cannot model stateful server logic
• Producer must coordinate breaking changes; SCC tells you what broke, not how to fix it
• Base class maintenance grows with contract count

The strategic answer

• SCC makes the contract executable on both sides: producer test + consumer stub from one DSL
• Replaces many end-to-end integration tests with fast, offline contract tests
• Use it where producer owns the API and can afford to maintain contracts
• Pair with OpenAPI for external API docs; SCC is internal CI discipline