Spring Framework Tutorials, Testing Tutorials

Consumer-Driven Contracts with Spring Cloud Contract

Last Updated: August 27, 2021 | Published: May 26, 2019

Fetching data from other systems is common in a microservice-based architecture. Besides the downtime of the other service, a broken API contract is one of the worst things that can happen. As a client of an external API, you must trust that the data contract is stable and changes are made known in advance. When it comes to testing the interaction with the external service, you can mock the response of the targeted service using frameworks like WireMock. Manually writing mock results can become quite cumbersome if you call many services and if the response is rather big. Luckily there is a nice solution to tackle these two tasks: Consumer-Driven Contracts with Spring Cloud Contract.

With this blog post, you'll learn how to use and write consumer-driven contracts with Spring Cloud Contract using Java 11, Spring Boot 2.4.6, JUnit 5, and Spring Cloud 2020.0.

Introduction to Spring Cloud Contract

Spring promotes this umbrella project with the following 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

generate boilerplate test code used on the server side

To demonstrate these features of Spring Cloud Contract, we'll work with a system architecture that contains two services: the book-store-server (aka. producer) and the book-store-client (aka. consumer).

The book store client fetches all available books from the book store server endpoint /books. During integration tests for the client, we'll use a stub of the book server that we'll automatically generate with Spring Cloud Contract to ensure the API contract:

Setting Up the Server-Side (Book Store Server)

The required Maven dependencies for the book store server are the following:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.4.6</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <groupId>de.rieckpil.blog</groupId>
  <artifactId>book-store-server</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>book-store-server</name>
  <description>Book Store Server</description>

  <properties>
    <java.version>11</java.version>
    <spring-cloud.version>2020.0.2</spring-cloud.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>com.github.javafaker</groupId>
      <artifactId>javafaker</artifactId>
      <version>1.0.2</version>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-contract-verifier</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-dependencies</artifactId>
        <version>${spring-cloud.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <build>
    <!-- explained later -->
  </build>

</project>

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

</parent>

<groupId>de.rieckpil.blog</groupId>

<artifactId>book-store-server</artifactId>

<version>0.0.1-SNAPSHOT</version>

<name>book-store-server</name>

<description>Book Store Server</description>

<java.version>11</java.version>

<spring-cloud.version>2020.0.2</spring-cloud.version>

</properties>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<groupId>com.github.javafaker</groupId>

<artifactId>javafaker</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-test</artifactId>

</dependency>

<groupId>org.springframework.cloud</groupId>

<artifactId>spring-cloud-starter-contract-verifier</artifactId>

</dependency>

</dependencies>

<groupId>org.springframework.cloud</groupId>

<artifactId>spring-cloud-dependencies</artifactId>

<version>${spring-cloud.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<build>

</build>

</project>

For demonstration purposes, we'll keep our REST endpoint for this example quite simple:

@RestController
public class BookController {

  private BookService bookService;

  public BookController(BookService bookService) {
    this.bookService = bookService;
  }

  @GetMapping("/books")
  public ResponseEntity<List<Book>> getTodos() {
    return ResponseEntity.ok(bookService.getBooks());
  }
}

@RestController

public class BookController {

private BookService bookService;

public BookController(BookService bookService) {

this.bookService = bookService;

}

@GetMapping("/books")

public ResponseEntity<List<Book>> getTodos() {

return ResponseEntity.ok(bookService.getBooks());

}

With the help of Java Faker, ourBookService returns ten random books:

@Service
public class BookService {

  public List<Book> getBooks() {
    Faker faker = new Faker();
    List<Book> books = new ArrayList();

    for (int i = 0; i < 10; i++) {
      Book book = new Book();
      book.setGenre(faker.book().genre());
      book.setTitle(faker.book().title());
      book.setIsbn(UUID.randomUUID().toString());
      books.add(book);
    }

    return books;
  }
}

@Service

public class BookService {

public List<Book> getBooks() {

Faker faker = new Faker();

List<Book> books = new ArrayList();

for (int i = 0; i < 10; i++) {

Book book = new Book();

book.setGenre(faker.book().genre());

book.setTitle(faker.book().title());

book.setIsbn(UUID.randomUUID().toString());

books.add(book);

}

return books;

}

Creating Contracts with Spring Cloud Contract

What's next is to define the contracts for our /books API endpoint. As part of these contracts, we define the specifications of our endpoint and how the response (i.e., API contract) looks like.

We can define these contracts with either Groovy or YAML. By default, Spring Cloud Contract expects our contract files as part of the folder src/test/resources/contracts.

For this example, we'll create one contract test that will make sure a GET call to /books returns the given data as application/json with an HTTP 200 status. Therefore we'll create a shouldReturnBooks.groovy file and declare the contract:

package contracts

import org.springframework.cloud.contract.spec.Contract

Contract.make {
  description 'Should return one book in a list'

  request {
    method GET()
    url '/books'
  }
  response {
    status OK()
    body '''\
            [
                {
                    "title": "Java 11",
                    "genre": "Technology",
                    "isbn": "42"
              }
            ]
        '''
    headers {
      contentType('application/json')
    }
  }
}

package contracts

import org.springframework.cloud.contract.spec.Contract

Contract.make {

description 'Should return one book in a list'

request {

method GET()

url '/books'

}

response {

status OK()

body '''\

[

{

"title": "Java 11",

"genre": "Technology",

"isbn": "42"

}

]

'''

headers {

contentType('application/json')

}

For Spring Cloud Contract to automatically generate the contracts test, we'll need a base test class later on. As part of this base class, we define our test setup and configure RestAssuredMockMvc for our controllers.

We'll mock any collaborator of our controller classes with Mockito:

@ExtendWith(MockitoExtension.class)
public abstract class BaseTest {

  @Mock
  private BookService mockedBookService;

  @BeforeEach
  void setup() {
    when(mockedBookService.getBooks())
      .thenReturn(List.of(new Book("Java 11", "Technology", "42")));

    RestAssuredMockMvc.standaloneSetup(new BookController(mockedBookService));
  }
}

@ExtendWith(MockitoExtension.class)

public abstract class BaseTest {

@Mock

private BookService mockedBookService;

@BeforeEach

void setup() {

when(mockedBookService.getBooks())

.thenReturn(List.of(new Book("Java 11", "Technology", "42")));

RestAssuredMockMvc.standaloneSetup(new BookController(mockedBookService));

}

Next, we need to point to this base class as part of the Spring Cloud Contract Maven plugin configuration:

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
    <plugin>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-contract-maven-plugin</artifactId>
      <version>3.0.2</version>
      <extensions>true</extensions>
      <configuration>
        <baseClassForTests>de.rieckpil.blog.BaseTest</baseClassForTests>
      </configuration>
    </plugin>
</build>

<build>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

</plugin>

<groupId>org.springframework.cloud</groupId>

<artifactId>spring-cloud-contract-maven-plugin</artifactId>

<baseClassForTests>de.rieckpil.blog.BaseTest</baseClassForTests>

</configuration>

</plugin>

</build>

During the build step (after the maven-compiler-plugin), the Maven plugin will generate a test based on this contract under target/generated-test-sources/contracts and execute this test during the test step.

In addition a book-store-server-0.0.1-SNAPSHOT-stubs.jar is created, containing the WireMock stub:

public class ContractVerifierTest extends BaseTest {

  @Test
  public void validate_shouldReturnBooks() throws Exception {
    // given:
      MockMvcRequestSpecification request = given();

    // when:
      ResponseOptions response = given().spec(request)
          .get("/books");

    // then:
      assertThat(response.statusCode()).isEqualTo(200);
      assertThat(response.header("Content-Type")).matches("application/json.*");
    // and:
      DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
      assertThatJson(parsedJson).array().contains("['genre']").isEqualTo("Technology");
      assertThatJson(parsedJson).array().contains("['isbn']").isEqualTo("42");
      assertThatJson(parsedJson).array().contains("['title']").isEqualTo("Java 11");
  }

}

public class ContractVerifierTest extends BaseTest {

@Test

public void validate_shouldReturnBooks() throws Exception {

// given:

MockMvcRequestSpecification request = given();

// when:

ResponseOptions response = given().spec(request)

.get("/books");

// then:

assertThat(response.statusCode()).isEqualTo(200);

assertThat(response.header("Content-Type")).matches("application/json.*");

// and:

DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());

assertThatJson(parsedJson).array().contains("['genre']").isEqualTo("Technology");

assertThatJson(parsedJson).array().contains("['isbn']").isEqualTo("42");

assertThatJson(parsedJson).array().contains("['title']").isEqualTo("Java 11");

}

We have to make sure to run mvn install so that the created .jar files (especially the stub jar) are installed in our local Maven (.m2 folder) repository.

To make these stubs available for other developers/the internet, we can upload the XYZ-stubs.jar to, e.g., Artifactory or Maven Central during our CI pipeline run.

Setting Up the Client-Side for Spring Cloud Contract

The setup for the client-side is a little bit different:

<?xml version="1.0" encoding="UTF-8"?>
<project
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://maven.apache.org/POM/4.0.0"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.4.6</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <groupId>de.rieckpil.blog</groupId>
  <artifactId>book-store-client</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>book-store-client</name>
  <description>Book Store Client</description>

  <properties>
    <java.version>11</java.version>
    <spring-cloud.version>2020.0.2</spring-cloud.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>

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

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-dependencies</artifactId>
        <version>${spring-cloud.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

</project>

<?xml version="1.0" encoding="UTF-8"?>

<project

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://maven.apache.org/POM/4.0.0"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

</parent>

<groupId>de.rieckpil.blog</groupId>

<artifactId>book-store-client</artifactId>

<version>0.0.1-SNAPSHOT</version>

<name>book-store-client</name>

<description>Book Store Client</description>

<java.version>11</java.version>

<spring-cloud.version>2020.0.2</spring-cloud.version>

</properties>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-webflux</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-test</artifactId>

</dependency>

<groupId>org.springframework.cloud</groupId>

<artifactId>spring-cloud-starter-contract-stub-runner</artifactId>

</dependency>

</dependencies>

<groupId>org.springframework.cloud</groupId>

<artifactId>spring-cloud-dependencies</artifactId>

<version>${spring-cloud.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<build>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

</plugin>

</plugins>

</build>

</project>

Instead of the spring-cloud-contract-verifier, the spring-cloud-contract-stub-runner is used here. Note that we don't have to include the XYZ-stubs.jar in our project to make use of it.

We're using the Spring WebFlux WebClient to fetch all available books from our book-store-server (producer):

@Component
public class BookClient {

  private WebClient webClient;

  @PostConstruct
  public void setUpWebClient() {
    var httpClient = HttpClient.create()
      .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2_000)
      .doOnConnected(connection ->
        connection.addHandlerLast(new ReadTimeoutHandler(2))
          .addHandlerLast(new WriteTimeoutHandler(2)));

    this.webClient = WebClient.builder()
      .baseUrl("http://localhost:8080")
      .clientConnector(new ReactorClientHttpConnector(httpClient))
      .build();
  }

  public JsonNode getAllAvailableBooks() {

    JsonNode availableBooks = webClient.get()
      .uri("/books")
      .accept(MediaType.APPLICATION_JSON)
      .retrieve()
      .bodyToMono(JsonNode.class)
      .block();

    return availableBooks;
  }
}

@Component

public class BookClient {

private WebClient webClient;

@PostConstruct

public void setUpWebClient() {

var httpClient = HttpClient.create()

.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2_000)

.doOnConnected(connection ->

connection.addHandlerLast(new ReadTimeoutHandler(2))

.addHandlerLast(new WriteTimeoutHandler(2)));

this.webClient = WebClient.builder()

.baseUrl("http://localhost:8080")

.clientConnector(new ReactorClientHttpConnector(httpClient))

.build();

}

public JsonNode getAllAvailableBooks() {

JsonNode availableBooks = webClient.get()

.uri("/books")

.accept(MediaType.APPLICATION_JSON)

.retrieve()

.bodyToMono(JsonNode.class)

.block();

return availableBooks;

}

For the sake of simplicity, the method returns the data as JsonNode (Jackson's JSON representation).

What's left is to now write a test that uses the automatically generated stub of our producer to verify our client works with given the API contract:

@SpringBootTest
@AutoConfigureStubRunner(
  ids = {"de.rieckpil.blog:book-store-server:+:stubs:8080"},
  stubsMode = StubRunnerProperties.StubsMode.LOCAL
)
class BookClientTest {

  @Autowired
  private BookClient cut;

  @Test
  void testContractToBookStoreServer() {

    JsonNode result = cut.getAllAvailableBooks();

    assertTrue(result.isArray());

    JsonNode firstBook = result.get(0);

    assertTrue(firstBook.has("genre"));
    assertTrue(firstBook.has("title"));
    assertTrue(firstBook.has("isbn"));
    assertTrue(firstBook.get("isbn").isTextual());
    assertTrue(firstBook.get("genre").isTextual());
    assertTrue(firstBook.get("title").isTextual());
  }
}

@SpringBootTest

@AutoConfigureStubRunner(

ids = {"de.rieckpil.blog:book-store-server:+:stubs:8080"},

stubsMode = StubRunnerProperties.StubsMode.LOCAL

)

class BookClientTest {

@Autowired

private BookClient cut;

@Test

void testContractToBookStoreServer() {

JsonNode result = cut.getAllAvailableBooks();

assertTrue(result.isArray());

JsonNode firstBook = result.get(0);

assertTrue(firstBook.has("genre"));

assertTrue(firstBook.has("title"));

assertTrue(firstBook.has("isbn"));

assertTrue(firstBook.get("isbn").isTextual());

assertTrue(firstBook.get("genre").isTextual());

assertTrue(firstBook.get("title").isTextual());

}

The @AutoConfigureStubRunner annotation takes an array of strings for its ids attribute to reference the required XYZ-stubs.jar files with a port definition for the WireMock server.

The stubsMode attribute defines how these .jars are loaded: either from the classpath (requires to add them to the Maven project), local (local .m2/repository folder) or remote (using your configured Maven repositories). During test execution, the WireMock server will respond with the defined data in the contract on the server-side, and the test will pass.

For more detailed information about consumer-driven contracts with Spring Cloud Contract, have a look at the following resources:

For more in-depth content and tips about testing Spring Boot applications, consider enrolling in the Testing Spring Boot Applications Masterclass.

You can find the code for the book store server and client on GitHub and further Spring-related resources on my blog.

Have fun writing consumer-driven contracts,

Phil

Tweet 0

Share 0

[…] >> Consumer-Driven Contracts with Spring Cloud Contract [rieckpil.de] […]

[…] Consumer-Driven Contracts with Spring Cloud Contract helps you to write your first consumer-driven contracts with Spring Cloud contract. […]

[…] >> #HOWTO: Consumer-Driven Contracts with Spring Cloud Contract [rieckpil.de] […]

[…] Books Java Developers Should Read in 2019 Reactive Relational Database Transactions Consumer driven contracts with Spring Cloud Contract Corda: Looking Forward and Back, Blockchain on a JVM Stack How to create a code review process that […]