Contract-Based Mock Server for Consumer Tests

Hello! Welcome to the next lesson in our module on microservices testing.

In our last lesson, we played the role of the API provider. We successfully configured our service to verify itself against a contract and, upon a successful build, generate a stubs.jar file. This file is the tangible output of our contract—a portable, verifiable definition of our API's behavior.

Today, we switch roles and become the API consumer. Your goal is to implement a mock server in consumer-side tests based on a contract to enable isolated development. We will take the stubs.jar generated by the provider and use it to run a mock server, allowing us to test our client-side code without needing the actual provider service to be running.

For your senior-level interviews, explaining how you test consumer services in isolation is critical. It demonstrates your understanding of building decoupled, resilient systems and enabling independent, fast-paced development cycles for different teams—a cornerstone of a successful microservices architecture.

1. The Consumer-Side Workflow: From Stub to Mock Server

Let's revisit our workflow diagram. We are now focusing on the right-hand side, where the consumer takes the stubs and uses them for local testing.

The workflow shows the consumer downloading the provider's stubs and using them to run a mock server. This allows the consumer's tests to validate their client code against the contract in complete isolation.

The process on the consumer side is straightforward and consists of three main steps:

1. Add the Dependency: Include the spring-cloud-starter-contract-stub-runner dependency in your consumer service's pom.xml.
2. Configure the Test: Annotate your test class with @AutoConfigureStubRunner to tell Spring where to find the provider's stubs and how to run the mock server.
3. Write the Test: Implement a standard integration test that uses your HTTP client to call the mock server and asserts the expected behavior.

2. Setting Up the Consumer Project

First, we need to add the necessary tools to our project. The magic on the consumer side is powered by a single dependency.

This stub-runner dependency pulls in everything needed to download stubs, parse them, and launch a pre-configured WireMock server for your tests.

3. Configuring the Mock Server with @AutoConfigureStubRunner

With the dependency in place, the next step is to configure your test class. This is done with a single, powerful annotation: @AutoConfigureStubRunner.

This annotation instructs Spring Boot to find a specific stub, start a mock server based on it, and make it available for the duration of your test.

Let's break down the key attributes of @AutoConfigureStubRunner:

• ids: This is the most important attribute. It's an array of strings that specifies the Maven coordinates of the stubs you want to use. The format is groupId:artifactId:version:classifier:port.

  • com.example:contract-rest-service:0.0.1-SNAPSHOT:stubs:8100
  • groupId:artifactId: Identifies the provider service.
  • version: Specifies the version of the stub. Crucially, you can use + (e.g., 0.0.1-SNAPSHOT:+) to always pull the latest available version. This is a common practice in CI/CD pipelines to ensure you're always testing against the most recent contract.
  • classifier: Usually stubs, indicating you want the stubs JAR.
  • port: The port on which the mock server will run. Your client code must be configured to call localhost on this port during the test.

• stubsMode: This tells the stub runner where to find the stubs JAR. The two most common values are:

  • StubRunnerProperties.StubsMode.LOCAL: The default. It looks for the stubs in your local Maven repository (~/.m2/repository). This works perfectly when you run mvn clean install on the provider first.
  • StubRunnerProperties.StubsMode.REMOTE: It downloads the stubs from your configured remote Maven repository (like Nexus or Artifactory). This is used in CI pipelines where different services are built independently.

4. A Practical Demonstration: Seeing It in Action

Now, let's watch a full demonstration of this process. This video will walk you through setting up the consumer test, running it, and seeing how it immediately catches a breaking change.

This video powerfully illustrates the core value proposition: you find integration bugs in milliseconds during a unit test, not hours or days later during manual QA or, even worse, in production.

5. Beyond Spring: Stubs for Any Client

What if your consumer isn't a Spring application? For example, it could be a React frontend, an Android app, or a service written in Python. The stubs generated by Spring Cloud Contract are still incredibly valuable. You can run the stub runner as a standalone executable JAR, which starts the same WireMock server that any non-JVM client can make HTTP requests to.

Mentioning this capability in an interview shows you think about the entire ecosystem, not just the Java backend.

Conclusion

In this lesson, you've mastered the consumer side of contract testing. By leveraging the provider's stubs, you can create fast, reliable, and isolated tests for your client code. This decouples your team's development and release cycles from the provider's, enabling true microservice agility.

Key Takeaways:

• The spring-cloud-starter-contract-stub-runner dependency is all you need to get started on the consumer side.
• The @AutoConfigureStubRunner annotation is the command center, telling your test which stubs to use and how to run the mock server.
• Using stubs provides an instant feedback loop, catching integration issues early in the development cycle.
• This approach enables fully isolated development, as the consumer no longer depends on a running instance of the provider service for its tests.
• The stubs are portable and can be used by non-JVM clients via the standalone stub runner JAR.

Next Up

We've now seen how to implement both provider-side and consumer-side contract tests. But how do these tests fit into the bigger picture alongside other tests, like the integration tests we wrote with Testcontainers? In our next lesson, we will Compare the roles of integration tests and contract tests in a CI/CD pipeline, clarifying when to use each and how they complement each other to build a robust testing strategy.