Spring Cloud Contract

Spring Cloud Contract is an umbrella project holding solutions that help users in successfully implementing the Consumer Driven Contracts approach. Currently Spring Cloud Contract consists of the Spring Cloud Contract Verifier project.

Spring Cloud Contract Verifier is a tool that enables Consumer Driven Contract (CDC) development of JVM-based applications. It is shipped with Contract Definition Language (DSL) written in Groovy. Stating with version 1.1.0 you can define your own way of defining contracts - the only thing you have to provide is a converter. Contract definitions are used to produce following resources:

  • by default JSON stub definitions to be used by WireMock (HTTP Server Stub) when doing integration testing on the client code (client tests). Test code must still be written by hand, test data is produced by Spring Cloud Contract Verifier. Starting with version 1.1.0 you can provide your own implementation of the HTTP Server Stub.

  • Messaging routes if you’re using one. We’re integrating with Spring Integration, Spring Cloud Stream and Apache Camel. You can however set your own integrations if you want to.

  • Acceptance tests (by default in JUnit or Spock) used to verify if server-side implementation of the API is compliant with the contract (server tests). Full test is generated by Spring Cloud Contract Verifier. Starting with version 1.1.0 you can provide your own way of generating tests (e.g. in a different language).

Spring Cloud Contract Verifier moves TDD to the level of software architecture.

Quick Start
Fork me on GitHub


When trying to test an application that communicates with other services then we could do one of two things:

  • deploy all microservices and perform end to end tests

  • mock other microservices in unit / integration tests

Both have their advantages but also a lot of disadvantages. Let’s focus on the latter.

Deploy all microservices and perform end to end tests


  • simulates production

  • tests real communication between services


  • to test one microservice we would have to deploy 6 microservices, a couple of databases etc.

  • the environment where the tests would be conducted would be locked for a single suite of tests (i.e. nobody else would be able to run the tests in the meantime).

  • long to run

  • very late feedback

  • extremely hard to debug

Mock other microservices in unit / integration tests


  • very fast feedback

  • no infrastructure requirements


  • the implementor of the service creates stubs thus they might have nothing to do with the reality

  • you can go to production with passing tests and failing production

To solve the aforementioned issues Spring Cloud Contract Verifier with Stub Runner were created. Their main idea is to give you very fast feedback, without the need to set up the whole world of microservices.

Spring Cloud Contract Verifier features:

  • ensure that HTTP / Messaging stubs (used when developing the client) are doing exactly what actual server-side implementation will do

  • promote acceptance test driven development method and Microservices architectural style

  • to provide a way to publish changes in contracts that are immediately visible on both sides of the communication

  • to generate boilerplate test code used on the server side

Quick Start


The recommended way to get started using spring-cloud-contract in your project is with a dependency management system – the snippet below can be copied and pasted into your build. Need help? See our getting started guides on building with Maven and Gradle. The example below is showing how to use the Spring Cloud Contract plugin. In order to use Spring Cloud Contract Stub Runner you just have to use different libraries as presented in the later part of this guide. Of course instead of adding the BOM of the concrete dependency you can add the release train BOM and you won't have to take care of versioning manually.

For a very detailed step by step guide check out the docs. Below you can find a simplified verstion.

Server / Producer side

On the server (HTTP) / producer (Messaging) side add the Spring Cloud Contract Verifier Maven / Gradle plugin. Let us assume that our project's group id is com.example and artifact id is http-server.

The base class for the tests passed in the configuration could look like this (we're assuming that we're using Rest Assured and we want to do CDC for a FraudDetectionController that you're writing)

package com.example;

import com.jayway.restassured.module.mockmvc.RestAssuredMockMvc;

public class MvcTest {

  public void setup() {
    RestAssuredMockMvc.standaloneSetup(new FraudDetectionController());


In the src/test/resources/contracts add a Stub definition. For example named shouldMarkClientAsFraud.groovy

org.springframework.cloud.contract.spec.Contract.make {
  request {
    method 'PUT'
    url '/fraudcheck'
    headers {
      header('Content-Type', 'application/vnd.fraud.v1+json')
response {
  status 200
    "fraudCheckStatus": "FRAUD",
    "rejectionReason": "Amount too high"
  headers {
    header('Content-Type': 'application/vnd.fraud.v1+json')

Once you try to build your application from your contracts tests will be generated in the output folder under /generated-test-sources/contracts.

package org.springframework.cloud.contract.verifier.tests;

import com.example.MvcTest;
import com.jayway.jsonpath.DocumentContext;
import com.jayway.jsonpath.JsonPath;
import com.jayway.restassured.module.mockmvc.specification.MockMvcRequestSpecification;
import com.jayway.restassured.response.ResponseOptions;
import org.junit.Test;

import static com.jayway.restassured.module.mockmvc.RestAssuredMockMvc.*;
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson;
import static org.assertj.core.api.Assertions.assertThat;

public class ContractVerifierTest extends MvcTest {

  public void validate_shouldMarkClientAsFraud() throws Exception {
    // given:
      MockMvcRequestSpecification request = given()
          .header("Content-Type", "application/vnd.fraud.v1+json")

    // when:
      ResponseOptions response = given().spec(request)

    // then:
    // and:
      DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
      assertThatJson(parsedJson).field("rejectionReason").isEqualTo("Amount too high");

Once you make them pass and re-run the build and installation of your artifacts then Spring Cloud Contract Verifier will convert the contracts into an HTTP server stub definitions. Currently we're supporting WireMock. The stub will be present in the output folder under stubs/mappings/ and will look like this:

  "uuid" : "6c509a40-18f3-498c-a19c-c9f8b56957de",
  "request" : {
    "url" : "/fraudcheck",
    "method" : "PUT",
    "headers" : {
      "Content-Type" : {
        "equalTo" : "application/vnd.fraud.v1+json"
    "bodyPatterns" : [ {
      "matchesJsonPath" : "$[?(@.loanAmount == 99999)]"
    }, {
      "matchesJsonPath" : "$[?(@.clientId == '1234567890')]"
    } ]
  "response" : {
    "status" : 200,
    "body" : "{\"fraudCheckStatus\":\"FRAUD\",\"rejectionReason\":\"Amount too high\"}",
    "headers" : {
      "Content-Type" : "application/vnd.fraud.v1+json"

The idea behind CDC (Consumer Driven Contracts) is to share the contract between the sides of the communication. Gradle and Maven plugins help you with that by generating a jar with stubs and contract definitions with a stubs classifier. Just upload it to some central repository where others can reuse it for their integration tests.

Client / Consumer side

On the client (HTTP) / consumer (Messaging) side it's enough to provide a dependency to a proper Spring Cloud Contract Stub Runner implementation. In this case since our example consists of HTTP communication with WireMock as the HTTP Server Stub. We will pick the following dependencies:





buildscript {
    repositories {
    dependencies {
      classpath "org.springframework.boot:spring-boot-gradle-plugin:${springBootPluginVersion}"

apply plugin: 'spring-boot'

dependencyManagement {
    imports {
      mavenBom "org.springframework.cloud:spring-cloud-contract-dependencies:${springCloudDependencies}"

dependencies {
    testCompile "org.springframework.cloud:spring-cloud-contract-wiremock"
    testCompile "org.springframework.cloud:spring-cloud-starter-contract-stub-runner"

The last step is to setup Stub Runner in your tests to automatically download the required stubs. To achieve that you have to pass the @AutoConfigureStubRunner annotation. That annotation has a bunch of properties that you can set. If you don't like such an approach you can set those values in your test properties too.

@AutoConfigureStubRunner(ids = {"com.example:http-server:+:stubs:8080"}, workOffline = true)
public class LoanApplicationServiceTests {

That way an artifact with group id com.example, artifact id http-server, in latest version, with stubs classifier will be registered at port 8080. Since the workOffline flag was passed then the stubs will not be downloaded from a remote repository - it will be searched for in the local Maven repo. Once your test context got booted up, executing the following code will not lead to a 404 because the Spring Cloud Contract Stub Runner will automatically start a WireMock server inside your test and feed it with the stubs generated from the server side.

HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.add("Content-Type", "application/vnd.fraud.v1+json");
String response = restTemplate.exchange("http://localhost:8080/fraudcheck", HttpMethod.PUT,
            new HttpEntity<>("{\"clientId\":\"1234567890\",\"loanAmount\":99999}", httpHeaders),
assertThat(response).isEqualTo("{\"fraudCheckStatus\":\"FRAUD\",\"rejectionReason\":\"Amount too high\"}");