Contract Testing with Spring Cloud Contract

16 min readAug 20, 2026

You changed a field name in your OrderService API response — customerId became customer_id. Your service's tests are green. You deploy. Three hours later, the BillingService team is paging you because their JSON parsing silently dropped the field and every invoice now has a null customer.

This is the integration-test gap, and it’s structurally unsolvable with the testing tools most teams reach for. Contract testing closes it. In this article we’ll cover why end-to-end tests don’t scale, what consumer-driven contracts are, how Spring Cloud Contract generates producer tests and consumer stubs from a single contract definition, the full workflow, and how it compares to Pact.

The Integration-Test Gap Between Services

In a microservices architecture, the dangerous bugs live between services, in the shape of the messages they exchange. Two strategies try to catch them, and both fall short.

Unit/integration tests per service verify each service in isolation. The producer’s tests confirm it behaves correctly. The consumer’s tests run against a mock of the producer. The problem: the consumer’s mock encodes the consumer team’s belief about the producer’s API. When the producer changes and the consumer’s hand-written mock doesn’t, both suites stay green while production breaks. Nobody tested the agreement.

End-to-end tests spin up every service and exercise real calls. They genuinely catch integration bugs — but they’re slow, flaky, expensive to maintain, and combinatorially explosive. With N services and many interaction paths, you cannot test every pair under every scenario. E2E suites become the bottleneck everyone disables “just for this release.”

Contract testing threads the needle:

Aspect Per-service tests End-to-end tests Contract tests Catches inter-service breaks No Yes Yes Speed Fast Slow Fast Flakiness Low High Low Infra to run One service All services One service Scales with #services Yes No Yes

The trick: instead of testing services together, you test each service against a shared, machine-checkable contract — separately. If both sides honor the contract, they’re compatible. No full environment required.

Consumer-Driven Contracts

A contract is a formal description of one interaction: given a request shape, the response shape the producer promises. Consumer-driven means the consumers drive what goes into the contract — they declare what they actually need from the producer, and the producer commits to delivering exactly that.

This inverts the usual dynamic. Rather than the producer publishing a giant API and hoping consumers cope, each consumer states its real expectations, those expectations become contracts, and the producer is tested against the union of them. If a consumer doesn’t use a field, breaking it is allowed. If a consumer depends on it, breaking it fails the producer’s build.

From one contract, Spring Cloud Contract derives two artifacts:

A generated test on the producer side that asserts the producer actually returns what the contract promises.
A stub (a WireMock stub for HTTP) the consumer uses in its tests, so the consumer runs against a fake producer that provably matches the contract.

Because both artifacts come from the same contract, drift is impossible: if the producer breaks the contract, its generated test fails before the stub ever reaches a consumer.

Writing a Contract

Spring Cloud Contract contracts are typically written in a Groovy DSL (YAML and Kotlin DSL are also supported), living under src/test/resources/contracts/ in the producer repository.

// src/test/resources/contracts/shouldReturnOrderById.groovy
import org.springframework.cloud.contract.spec.Contract

Contract.make {
    description "should return an order by id"    request {
        method GET()
        url "/orders/42"
    }    response {
        status OK()
        headers {
            contentType applicationJson()
        }
        body([
                id        : 42,
                customerId: "cust-7",
                status    : "CONFIRMED",
                total     : 99.99
        ])
        bodyMatchers {
            jsonPath('$.id', byEquality())
            jsonPath('$.customerId', byRegex('[a-z]+-[0-9]+').asString())
            jsonPath('$.status', byRegex('CONFIRMED|PENDING|CANCELLED'))
            jsonPath('$.total', byType())
        }
    }
}

The bodyMatchers block is the key to robust contracts. The literal body values serve as the example used to build the stub response; the matchers define what the producer test actually verifies. Using byRegex, byType, and byEquality keeps the contract from being brittle about exact values while still pinning the shape. A contract that hard-asserts total == 99.99 would fail for any real order — you want it to assert "a number is present," via byType().

The Producer Side: Generated Tests

On the producer, add the plugin. It scans the contracts and generates JUnit tests at build time.

<plugin>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-contract-maven-plugin</artifactId>
    <version>4.1.4</version>
    <extensions>true</extensions>
    <configuration>
        <testFramework>JUNIT5</testFramework>
        <baseClassForTests>com.example.orders.ContractBaseClass</baseClassForTests>
    </configuration>
</plugin>

You provide a base class that sets up the context the generated tests run in. The generated test extends it. With RestAssured’s MockMvc integration, you stand up the controller (real or awith mocked collaborators) and the plugin's generated test fires the contract's request at it.

package com.example.orders;

import io.restassured.module.mockmvc.RestAssuredMockMvc;
import org.junit.jupiter.api.BeforeEach;
import org.mockito.Mockito;import java.math.BigDecimal;import static org.mockito.Mockito.when;public abstract class ContractBaseClass {    @BeforeEach
    void setup() {
        OrderService orderService = Mockito.mock(OrderService.class);
        when(orderService.findById(42L)).thenReturn(
                new Order(42L, "cust-7", "CONFIRMED", new BigDecimal("99.99")));        OrderController controller = new OrderController(orderService);
        RestAssuredMockMvc.standaloneSetup(controller);
    }
}

When you run mvn test, the plugin generates something like this (you never write it, but it's worth seeing):

// generated under target/generated-test-sources
public class ContractVerifierTest extends ContractBaseClass {

    @Test
    public void validate_shouldReturnOrderById() {
        // given
        MockMvcRequestSpecification request = given();        // when
        ResponseOptions response = given().spec(request)
                .get("/orders/42");        // then
        assertThat(response.statusCode()).isEqualTo(200);
        assertThat(response.header("Content-Type"))
                .matches("application/json.*");        // and (from bodyMatchers)
        DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
        assertThat(parsedJson.read("$.id", Integer.class)).isEqualTo(42);
        assertThat(parsedJson.read("$.customerId", String.class))
                .matches("[a-z]+-[0-9]+");
        assertThat(parsedJson.read("$.status", String.class))
                .matches("CONFIRMED|PENDING|CANCELLED");
    }
}

If your controller stops returning customerId, this generated test fails — in the producer's build, before anything ships. That's the gap closed.

On a successful build, the plugin also packages the contracts into stub JARs (order-service-1.0.0-stubs.jar) and installs/deploys them to your artifact repository. These stubs are what consumers consume.

The Consumer Side: Stubs

The consumer doesn’t see the producer’s code or its running instance. It pulls the stub artifact and runs against it using @AutoConfigureStubRunner. Stub Runner downloads the stub JAR, boots an embedded WireMock server primed with the contract's responses, and points your consumer's HTTP client at it.

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-contract-stub-runner</artifactId>
    <scope>test</scope>
</dependency>

import org.springframework.cloud.contract.stubrunner.spring.StubRunnerProperties;
import org.springframework.cloud.contract.stubrunner.spring.AutoConfigureStubRunner;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
@AutoConfigureStubRunner(
        ids = "com.example:order-service:+:stubs:8090",
        stubsMode = StubRunnerProperties.StubsMode.LOCAL)
class OrderClientContractTest {    @Autowired
    OrderClient orderClient; // a Feign/RestClient wrapper hitting http://localhost:8090    @Test
    void fetchesOrderAgainstProducerStub() {
        Order order = orderClient.getOrder(42L);        assertThat(order.customerId()).isEqualTo("cust-7");
        assertThat(order.status()).isEqualTo("CONFIRMED");
    }
}

The ids coordinate breaks down as groupId:artifactId:version:classifier:port. The + means "latest version." stubsMode can be LOCAL (use the local Maven repo / installed stubs), REMOTE (download from an artifact repo or Git), or CLASSPATH.

The consumer is now testing its parsing, its client config, and its model mapping against a fake that is guaranteed to match the contract the producer is verified against. If the consumer’s Order record can't deserialize the stub response, the consumer's build fails — locally, fast, no OrderService instance required.

The End-to-End Workflow

Here’s how it fits together as a process:

Consumer proposes a contract. The consumer team opens a PR against the producer repo (or a shared contracts repo) adding a contract describing what they need. This makes the dependency explicit and reviewable.
Producer accepts and implements. The producer team merges the contract. The plugin generates a failing test; the producer implements the endpoint until the generated test passes.
Producer publishes stubs. A green producer build installs/deploys the stub JAR to the artifact repository.
Consumer verifies against stubs. The consumer’s CI pulls the latest stubs and runs its contract tests. Green means the two are compatible.
Either side changes. If the producer later breaks the contract, its own build goes red. If the consumer needs more, the loop restarts at step 1.

The discipline this enforces: no API change ships without the contract changing first, and the contract is reviewed by both teams. The contract becomes the negotiated, version-controlled source of truth for the integration.

Spring Cloud Contract also supports messaging contracts the same way — define an input message and the expected output message, and it generates producer tests plus stubs for brokers like Kafka or RabbitMQ. The DSL uses input/outputMessage blocks instead of request/response.

Comparison to Pact

Pact is the other major contract-testing tool. Both implement consumer-driven contracts; they differ in mechanics and ecosystem.

Dimension Spring Cloud Contract Pact Where contracts live Producer repo (or shared repo) Generated from consumer tests Contract authoring Groovy/YAML/Kotlin DSL, written upfront Code-first, emitted by consumer test runs Primary ecosystem JVM / Spring-centric Truly polyglot (JS, Ruby, Go, .NET, JVM…) Contract sharing Artifact repo (stub JARs) or Git Pact Broker (versioning, can-i-deploy) Stub server Embedded WireMock Pact mock server Best fit Spring Boot estates Heterogeneous polyglot estates

The philosophical difference: Pact is consumer-first and code-driven — the consumer’s tests produce the pact file, which the producer then verifies. Spring Cloud Contract is contract-first — you write the contract explicitly, and both the producer test and consumer stub are generated from it.

Practical guidance: if your services are predominantly Spring Boot and you’re already in the Spring ecosystem, Spring Cloud Contract integrates with near-zero friction and the contract-first model gives you an explicit, reviewable artifact. If you have a polyglot fleet — a Node frontend-for-backend, Go services, .NET — Pact’s broker and language coverage make it the more natural fit. Many large orgs even run both, picking per team.

Pitfalls

Over-specifying response bodies. Hard-asserting exact values (total == 99.99) makes contracts brittle and couples them to test fixtures. Use bodyMatchers with byType(), byRegex(), and byEquality() to assert shape, not incidental values.
A broken or heavy base class. The producer base class must reliably set up the controller. If it boots the full application context or hits a real DB, generated tests become slow and flaky. Keep it minimal — standaloneSetup with mocked collaborators is usually right.
Stubs drifting from reality. Stubs only protect you if they come from a verified producer build. Never hand-edit stub JARs or commit stale ones. Treat the producer’s green build as the gate that publishes them.
Wrong stubsMode. LOCAL reads from the local Maven repo; if you forgot to install the producer stubs locally, the consumer test can't find them. In CI, use REMOTE against your artifact repo and pin or use + deliberately.
Contracts as documentation only. A contract that isn’t wired into both builds catches nothing. The value is entirely in the generated producer test and the consumer stub test both running in CI.
Versioning confusion with +. + pulls the latest stubs, which is great for catching breaks early but can surprise you when an unrelated producer change lands. For reproducible CI, consider pinning the version and bumping it deliberately.
Ignoring the consumer→producer PR flow. Skipping the proposal step and having the producer guess at consumer needs reintroduces the exact assumption-mismatch problem contract testing exists to prevent. The human workflow is part of the technique.
Treating contract tests as a replacement for everything. Contracts verify the message shape and protocol, not business correctness end to end. You still need unit tests for logic and a thin layer of E2E smoke tests for critical happy paths.

Wrapping Up

The bugs that take down distributed systems hide in the seams between services, and neither isolated unit tests nor brittle end-to-end suites reliably catch them. Consumer-driven contract testing does — by turning the agreement between two services into a single, version-controlled artifact that generates a verifying test on one side and a guaranteed-accurate stub on the other.

Spring Cloud Contract makes this nearly free for Spring Boot teams: write a contract, get a producer test and a consumer stub, wire both into CI, and breaking changes light up in the responsible team’s build before they ever reach production. Pair it with focused unit tests and a thin E2E smoke layer, and you get the integration confidence of end-to-end testing without the cost.

Get Marcelo Domingues’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

If this clarified contract testing for you, follow devdomain for more microservices and testing deep-dives. Drop a comment about how your team handles cross-service breaking changes today — the messier the story, the better the next article.You changed a field name in your OrderService API response — customerId became customer_id. Your service's tests are green. You deploy. Three hours later, the BillingService team is paging you because their JSON parsing silently dropped the field and every invoice now has a null customer.

The Integration-Test Gap Between Services

In a microservices architecture, the dangerous bugs live between services, in the shape of the messages they exchange. Two strategies try to catch them, and both fall short.

Contract testing threads the needle:

Consumer-Driven Contracts

From one contract, Spring Cloud Contract derives two artifacts:

A generated test on the producer side that asserts the producer actually returns what the contract promises.
A stub (a WireMock stub for HTTP) the consumer uses in its tests, so the consumer runs against a fake producer that provably matches the contract.

Because both artifacts come from the same contract, drift is impossible: if the producer breaks the contract, its generated test fails before the stub ever reaches a consumer.

Writing a Contract

Spring Cloud Contract contracts are typically written in a Groovy DSL (YAML and Kotlin DSL are also supported), living under src/test/resources/contracts/ in the producer repository.

// src/test/resources/contracts/shouldReturnOrderById.groovy
import org.springframework.cloud.contract.spec.Contract

Contract.make {
    description "should return an order by id"    request {
        method GET()
        url "/orders/42"
    }    response {
        status OK()
        headers {
            contentType applicationJson()
        }
        body([
                id        : 42,
                customerId: "cust-7",
                status    : "CONFIRMED",
                total     : 99.99
        ])
        bodyMatchers {
            jsonPath('$.id', byEquality())
            jsonPath('$.customerId', byRegex('[a-z]+-[0-9]+').asString())
            jsonPath('$.status', byRegex('CONFIRMED|PENDING|CANCELLED'))
            jsonPath('$.total', byType())
        }
    }
}

The Producer Side: Generated Tests

On the producer, add the plugin. It scans the contracts and generates JUnit tests at build time.

<plugin>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-contract-maven-plugin</artifactId>
    <version>4.1.4</version>
    <extensions>true</extensions>
    <configuration>
        <testFramework>JUNIT5</testFramework>
        <baseClassForTests>com.example.orders.ContractBaseClass</baseClassForTests>
    </configuration>
</plugin>

package com.example.orders;

import io.restassured.module.mockmvc.RestAssuredMockMvc;
import org.junit.jupiter.api.BeforeEach;
import org.mockito.Mockito;import java.math.BigDecimal;import static org.mockito.Mockito.when;public abstract class ContractBaseClass {    @BeforeEach
    void setup() {
        OrderService orderService = Mockito.mock(OrderService.class);
        when(orderService.findById(42L)).thenReturn(
                new Order(42L, "cust-7", "CONFIRMED", new BigDecimal("99.99")));        OrderController controller = new OrderController(orderService);
        RestAssuredMockMvc.standaloneSetup(controller);
    }
}

When you run mvn test, the plugin generates something like this (you never write it, but it's worth seeing):

// generated under target/generated-test-sources
public class ContractVerifierTest extends ContractBaseClass {

    @Test
    public void validate_shouldReturnOrderById() {
        // given
        MockMvcRequestSpecification request = given();        // when
        ResponseOptions response = given().spec(request)
                .get("/orders/42");        // then
        assertThat(response.statusCode()).isEqualTo(200);
        assertThat(response.header("Content-Type"))
                .matches("application/json.*");        // and (from bodyMatchers)
        DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
        assertThat(parsedJson.read("$.id", Integer.class)).isEqualTo(42);
        assertThat(parsedJson.read("$.customerId", String.class))
                .matches("[a-z]+-[0-9]+");
        assertThat(parsedJson.read("$.status", String.class))
                .matches("CONFIRMED|PENDING|CANCELLED");
    }
}

If your controller stops returning customerId, this generated test fails — in the producer's build, before anything ships. That's the gap closed.

The Consumer Side: Stubs

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-contract-stub-runner</artifactId>
    <scope>test</scope>
</dependency>

import org.springframework.cloud.contract.stubrunner.spring.StubRunnerProperties;
import org.springframework.cloud.contract.stubrunner.spring.AutoConfigureStubRunner;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
@AutoConfigureStubRunner(
        ids = "com.example:order-service:+:stubs:8090",
        stubsMode = StubRunnerProperties.StubsMode.LOCAL)
class OrderClientContractTest {    @Autowired
    OrderClient orderClient; // a Feign/RestClient wrapper hitting http://localhost:8090    @Test
    void fetchesOrderAgainstProducerStub() {
        Order order = orderClient.getOrder(42L);        assertThat(order.customerId()).isEqualTo("cust-7");
        assertThat(order.status()).isEqualTo("CONFIRMED");
    }
}

The End-to-End Workflow

Here’s how it fits together as a process:

Consumer proposes a contract. The consumer team opens a PR against the producer repo (or a shared contracts repo) adding a contract describing what they need. This makes the dependency explicit and reviewable.
Producer accepts and implements. The producer team merges the contract. The plugin generates a failing test; the producer implements the endpoint until the generated test passes.
Producer publishes stubs. A green producer build installs/deploys the stub JAR to the artifact repository.
Consumer verifies against stubs. The consumer’s CI pulls the latest stubs and runs its contract tests. Green means the two are compatible.
Either side changes. If the producer later breaks the contract, its own build goes red. If the consumer needs more, the loop restarts at step 1.

Comparison to Pact

Pact is the other major contract-testing tool. Both implement consumer-driven contracts; they differ in mechanics and ecosystem.

Pitfalls

Over-specifying response bodies. Hard-asserting exact values (total == 99.99) makes contracts brittle and couples them to test fixtures. Use bodyMatchers with byType(), byRegex(), and byEquality() to assert shape, not incidental values.
A broken or heavy base class. The producer base class must reliably set up the controller. If it boots the full application context or hits a real DB, generated tests become slow and flaky. Keep it minimal — standaloneSetup with mocked collaborators is usually right.
Stubs drifting from reality. Stubs only protect you if they come from a verified producer build. Never hand-edit stub JARs or commit stale ones. Treat the producer’s green build as the gate that publishes them.
Wrong stubsMode. LOCAL reads from the local Maven repo; if you forgot to install the producer stubs locally, the consumer test can't find them. In CI, use REMOTE against your artifact repo and pin or use + deliberately.
Contracts as documentation only. A contract that isn’t wired into both builds catches nothing. The value is entirely in the generated producer test and the consumer stub test both running in CI.
Versioning confusion with +. + pulls the latest stubs, which is great for catching breaks early but can surprise you when an unrelated producer change lands. For reproducible CI, consider pinning the version and bumping it deliberately.
Ignoring the consumer→producer PR flow. Skipping the proposal step and having the producer guess at consumer needs reintroduces the exact assumption-mismatch problem contract testing exists to prevent. The human workflow is part of the technique.
Treating contract tests as a replacement for everything. Contracts verify the message shape and protocol, not business correctness end to end. You still need unit tests for logic and a thin layer of E2E smoke tests for critical happy paths.

devdomain

Contract Testing with Spring Cloud Contract

The Integration-Test Gap Between Services

Consumer-Driven Contracts

Writing a Contract

The Producer Side: Generated Tests

The Consumer Side: Stubs

The End-to-End Workflow

Comparison to Pact

Pitfalls

Wrapping Up

Get Marcelo Domingues’s stories in your inbox

The Integration-Test Gap Between Services

Consumer-Driven Contracts

Writing a Contract

The Producer Side: Generated Tests

The Consumer Side: Stubs

The End-to-End Workflow

Comparison to Pact

Pitfalls

Wrapping Up

Written by Marcelo Domingues

Published in devdomain

No responses yet

More from Marcelo Domingues and devdomain

Hexagonal Architecture (Ports and Adapters) in Spring BootMost Spring Boot codebases rot in the…

Hexagonal Architecture — Alistair Cockburn’s “Ports and Adapters” — is a direct answer to this decay. The core idea is almost…

Domain-Driven Design in Practice with Java and SpringDomain-Driven Design has a reputation problem.

This article skips the philosophy and gets practical. We’ll build the tactical patterns — entities, value objects, aggregates…

JVM Performance Tuning for Spring Boot: GC, Heap, and Profiling

Most Spring Boot performance problems are not in your code. They are in the runtime contract you never explicitly signed: heap sizing…

Spring Boot Error Handling: @ControllerAdvice and ProblemDetail (RFC 7807)Most APIs leak.

The fix is a single, consistent error contract enforced in one place. Spring Boot gives you the tools: @ControllerAdvice for centralized…

Recommended from Medium

What Does the Embedded Apache Tomcat Server Actually Do in a Spring Boot Application?

Ever wondered how your Spring Boot application receives HTTP requests without you installing or configuring a web server? Let’s understand…

Virtual Threads in Spring Boot: One Property, Five Surprises

That one line can let your service hold 5,000 requests in flight where it used to hold 200. It can also remove the only thing protecting…

Spring Boot + Kafka: Step-by-Step Configuration for Production

Modern applications often need to process events without making users wait for every operation to finish.

Spring Boot 4.2: 15 Things That Change When You Upgrade From 4.1,

RestTemplate deprecated, the AMQP starter repurposed, relative redirects, one forwarded header dropped. Each run on 4.1.2 vs 4.2.0-RC1.

10 Spring Boot Performance Optimization Techniques That Actually Make a Difference

1. Fix N+1 Queries Before Optimizing Java Code

🚨 Your Spring Boot JWT Still Works After Logout — And That’s a Security Problem

SEO title: Spring Boot JWT Logout Explained: Why Tokens Still Work and How to Revoke Them

No responses yet

More from Marcelo Domingues and devdomain

Hexagonal Architecture (Ports and Adapters) in Spring BootMost Spring Boot codebases rot in the…

Hexagonal Architecture — Alistair Cockburn’s “Ports and Adapters” — is a direct answer to this decay. The core idea is almost…

Domain-Driven Design in Practice with Java and SpringDomain-Driven Design has a reputation problem.

This article skips the philosophy and gets practical. We’ll build the tactical patterns — entities, value objects, aggregates…

JVM Performance Tuning for Spring Boot: GC, Heap, and Profiling

Most Spring Boot performance problems are not in your code. They are in the runtime contract you never explicitly signed: heap sizing…

Spring Boot Error Handling: @ControllerAdvice and ProblemDetail (RFC 7807)Most APIs leak.

The fix is a single, consistent error contract enforced in one place. Spring Boot gives you the tools: @ControllerAdvice for centralized…

Recommended from Medium

What Does the Embedded Apache Tomcat Server Actually Do in a Spring Boot Application?

Ever wondered how your Spring Boot application receives HTTP requests without you installing or configuring a web server? Let’s understand…

Virtual Threads in Spring Boot: One Property, Five Surprises

That one line can let your service hold 5,000 requests in flight where it used to hold 200. It can also remove the only thing protecting…

Spring Boot + Kafka: Step-by-Step Configuration for Production

Modern applications often need to process events without making users wait for every operation to finish.

Spring Boot 4.2: 15 Things That Change When You Upgrade From 4.1,

RestTemplate deprecated, the AMQP starter repurposed, relative redirects, one forwarded header dropped. Each run on 4.1.2 vs 4.2.0-RC1.

10 Spring Boot Performance Optimization Techniques That Actually Make a Difference

1. Fix N+1 Queries Before Optimizing Java Code

🚨 Your Spring Boot JWT Still Works After Logout — And That’s a Security Problem

SEO title: Spring Boot JWT Logout Explained: Why Tokens Still Work and How to Revoke Them