Master Consumer‑Driven Contracts with Spring Cloud Contract: From Stub Generation to Testing

Background and Problem

In a micro‑service architecture, different teams own and maintain services, which can cause interface breakages when a provider changes its API without informing consumers. Traditional provider‑first contracts are fragile because they rely on the provider to notify consumers of changes.

Consumer‑Driven Contracts (CDC)

Ian Robinson introduced Consumer‑Driven Contracts (CDC), where the consumer defines the contract and the provider implements it. The contract is enforced by test cases, allowing the provider to modify its implementation as long as the tests (the contract) still pass.

Spring Cloud Contract Integration

If you use Spring Cloud as the micro‑service platform, Spring Cloud Contract is the natural choice. It eliminates the need to start all dependent services during testing.

Project Structure

The example project contains three modules:

common : shared entities such as Customer and Page.

provider : the service that will be stubbed.

consumer : the client that consumes the provider.

Provider Module

Key Maven dependencies:

Add spring-cloud-starter-contract-verifier to verify contracts.

Add spring-cloud-contract-maven-plugin to generate stubs.

The contract is written in Groovy DSL and placed under src/test/resources/contracts. Example shouldReturnAllCustomers.groovy defines description, request (URL and method), and response (headers and JSON body with two customers).

Generating the Stub JAR

Run the Maven command to build the stub JAR and install it locally: clean install -Dmaven.test.skip=true After installation, you can verify the generated stubs with the contract plugin UI.

Running the stub JAR starts a mock server that serves the contract‑defined responses, e.g., http://localhost:8080/api/customers returns the predefined JSON.

Consumer Module

Add the dependency spring-cloud-starter-contract-stub-runner to automatically start the stub during tests.

In the consumer test, use the annotation @AutoConfigureStubRunner with parameters:

@AutoConfigureStubRunner(ids = {"com.importsource.springcloud:spring-cloud-contract-provider:+:8080"}, workOffline = true)

The ids format is groupId:artifactId:version:classifier:port. Setting workOffline = true forces Maven to use the locally installed stub JAR.

Write a test that calls the provider’s endpoint; the stub runner intercepts the call and returns the contract‑specified response, allowing the consumer test to pass without a real provider.

Conclusion

By defining a consumer‑driven contract, generating a stub JAR with Spring Cloud Contract, and using @AutoConfigureStubRunner in consumer tests, you can fully test service interactions without starting the actual provider. This approach improves decoupling, reduces integration‑time failures, and supports continuous delivery in micro‑service environments.

Other CDC tools such as Pact, Janus, and Pacto are also available.