Consumer-driven contracts – Interface tests for microservices

7. September 2018

When a software engineer needs to integrate two systems via a single interface, the following process is generally used:

  • The respective department creates an interface specification and gives it to the team of the system that renders the interface available (interface provider).

  • The interface provider implements the interface in the form of something like a web service.

  • As soon as the interface provider has completed implementation, the team for the system using the interface commences with implementation (interface consumer).

  • In several stages – often manually – integration of both systems is tested.

  • It requires a lot of discipline from all parties involved to maintain the original interface specification and code consistent when interface changes become necessary during testing.

It is obvious that this approach is not sustainable when using a microservice architecture model. If the system is divided into small services, a large number of interfaces are created and integration is no longer workable under the aforenamed method. Added to this comes the circumstance that a high level of test automation is a decisive criterion for continual software deployment. This can only be attained by executing the interface tests in an automated manner as a component of the build pipeline (continuous integration CI / continuous delivery CD). There are two methods for the integration of interface tests:

Consumer-driven contract tests (CDC tests)

The core idea behind CDC is that the service consumer defines the requirements for the service provider’s API. Each API user concludes a contract with the service provider laying out the requirements on the API.

In the case illustrated in the figure, Service Consumer A needs resource attributes x and y; Service Consumer B requires attributes x and z. Thus, the service provider renders an API with attributes x, y, and z.

For CDC, technical frameworks exist that can be used to create the contracts and ensure service providers and service consumers comply with the agreements. These tests are automated and can be integrated in CI / CD. That makes it possible to reconcile the two methods laid out above. With low infrastructure demands, the pipeline provides swift feedback (fail fast), and yet production is still simulated and the communication between the services is tested. Two prominent representatives for CDC frameworks are Spring Cloud Contract and Pact. The following Groovy file shows a sample contract based on the Spring Cloud Contract:

For implementation, the simplest Spring Cloud Contract variant is managed in a provider source code repository (like git). The procedure for extending a contract between service consumer and service provider is then broken down as follows:

  1. Service consumer
    The consumer clones the service provider’s repository and can generate a local stub server using a build (e.g. in Maven). It can now switch to offline mode and develop and test changes locally. It subsequently creates a merge request.
  1. Producer phaseIf the service provider accepts the changes, it will write the missing implementation and merge into the master. The CI / CD pipeline loads the stubs into an artifact repository (e.g. Nexus).
  1. Service consumer
    It can now switch back to online mode, load the stubs out of the artifact repository, and test using the CI / CD pipeline.

Consumer-driven contracts in practice

When CDC tests are being used for testing microservice interfaces in an agile development project, both advantages and disadvantages crystallize.

Positive points:

  • Communication takes place among the teams. Since the service consumer creates the requirements on the API, they are always transparent. As such, the requirements per service consumer become transparent for the service provider.

  • Business and IT use the same contract. There is technical assurance that the specification (the contract) and the code do not diverge.

  • This supports agile development. When CDCs are used in a consistent manner, implementation is only performed for what is requested.

  • Fail fast: When CDCs are violated, it can be checked at an early stage in the CI / CD pipeline.

Negative points:

  • CDC tests are still relatively unchartered territory, which has the consequence that there is a lack of established best practices. That can lead to more time being consumed in discussion and refactoring.

  • CDCs are not intended for testing business logic. That is why they are unable to replace automated integration tests and acceptance tests prior to a project’s production deployment.

  • When using Spring Cloud Contract, it should be noted that this framework is restricted to the Spring Framework. When microservices use another technology stack, they don’t provide any added value. In this case, it is recommended to use Pact.

  • Fail Fast: Sind die CDCs verletzt, kann dies zu einem frühen Zeitpunkt in der CI/ CD-Pipeline geprüft werden.


CDC tests supply additional value when deployment is restricted to service consumers and service providers obtaining a mutual understanding of queries and responses for an API (endpoint, attributes). CDC tests should not be used for business logic.

Read now!

Blog - Technology & Innovation

Meet Q_ROOMS - The app for swift and straightforward booking of meeting rooms
Read now!

Read more


With Q_PERIOR, you have a strong partner at your side.
We look forward to your challenge!