In the last article we described component tests: tests which are half unit and half integration test, that allow us to validate both integration within our application (via dependency injection) and also with peripheral components. All of which while remaining sufficiently isolated, to limit friction during execution. Because this isolation works perfectly, our API client tests suffer from a major flaw: if and when the supplier changes the service signature we learn about it much too late. This is what contract tests attempt to avoid, and which we will address in this article.
This article originally appeared on our French Language Blog on 28/06/2018.
What to test?
In a microservice architecture, it’s likely that the services will communicate amongst themselves, and we’ll run into disaster if we don’t adopt certain practices, in particular autonomy:
- A shared nothing architecture in the technical implementation
- Team autonomy in the organisation
- Deployment autonomy as part of the process.
It’s on this last point that contract tests help us. They’re an excellent complement to component tests when testing microservices. Indeed, contract tests make it possible to verify that the contract between producer and consumer is always the one defined between the two parties:
- On the producer side, we verify that we’re providing the service that consumers expect to receive (the implementation of the contract). If this isn’t the case it’s because our interface has changed, intentional or not. If it is unintentional, the test will fail and we avoid deploying a service that might cause our consumers to crash. If it’s intentional, then it’s necessary to communicate the change to our consumers and increase the service’s version.
- On the consumer side, we check that the contract hasn’t changed. If it has changed, we check with the producer to identify the change and adapt our code and the associated Component tests.
We frequently hear about Consumer-Driven Contracts tests, a pattern that aims to construct contracts based on consumers’ needs rather than imposing one defined by the producer. The intention is to limit friction as the service evolves (i.e. upstream and downstream compatibility management, versions, etc. generally imposed by the producer), and to better understand how the service is used in reality (i.e. which endpoints and which values are useful).
In our example, this is how contract tests will look:
To implement our contract tests, we stay within the Spring ecosystem by using Spring Cloud Contract, there are other frameworks out there, Pact being one of the more popular.
Let’s zoom in on these tests:
On the producer side we’ll need two things:
- A library to check that our controller is implementing the contract:
- A plugin which will generate tests from the contract and generate stubs to be used on the consumer side:
baseClassForTests is a parent class that will be used by all our generated tests, we’ll come back to it later.
Our first step is to create a contract describing the request and response (in yaml format or with a DSL such as groovy). The following example is simplistic, and it’s possible to do much more advanced things (including with regular expressions and other features, we encourage you to read the docs). We’ll store this contract on the producer side in the directory src/test/resources/contracts, with the response body also stored in a file:
At this point, if you run Maven the mechanism will come into place, at least in part. The test class will be generated (in target/generated-test-sources/contracts):
But the test will fail.
Contract tests’ base class
To make the test pass, we need the basic class we referred to above to initialize a context:
There’s a lot going on at this level:
- The primary objective is to provide what the Controller needs in order to answer the test, so we provide a MockMvc environment with RestAssuredMockMvc.
- We could settle on the last line, but in this case the Controller would use a real implementation of the Service which in turn uses a real client which would then call the real transport API. To avoid this and provide more isolation, we’ll do what we did earlier, and provide a MockBean that simulates the Service’s response by deserializing a json file, which is the same file used in the contract.
- It’s generally be necessary to create as many base classes as you have Controllers to simulate their behaviour. The maven configuration is somewhat different in this case.
At this point the producer-side tests should pass, and if you’ve run mvn install or deploy, the jar containing the stubs should be published in the Maven repo, be it local or remote:
Installing connection-lookup/target/connection-lookup-0.0.1-SNAPSHOT-stubs.jar to ~/.m2/repository/ch/octo/blog/connection-lookup/0.0.1-SNAPSHOT/connection-lookup-0.0.1-SNAPSHOT-stubs.jar
Now let’s look at the consumer side: our journey-booking module.
Here, we need to depend on the stub generated on the producer side:
Moreover, we have to replace the wiremock dependency with the Spring Cloud dependency or we’ll have an exception. If you remember our client test, we used wiremock to simulate a server. Spring Cloud does the same but is based on the self-generated stub, which allows it to be aligned with the producer contract.
The code is as follows (gitlab link) :
The test is similar to our component tests (ConnectionLookupClientCompTest), except that we no longer use wiremock directly. The
@AutoConfigureStubRunner annotation configures the stub by fetching the Maven dependency specified by the ids attribute (in
groupId:artifactId:version:classifier format) and exposing it on port 8090.
By using “
+” as the version number, we’ll always take the most recent version which makes it possible to verify that our test always passes despite the evolving producer. On the day the test fails, we’ll know the contract has changed, logically before the producer has put the new version into production.
Contract test or component test?
As we’ve just seen, the contract test is nothing other than a component test, but it also has the advantage of validating that the producer and consumer are aligned. Our recommendation is to always use contract testing, at least in a controlled environment (typically microservices within your company), but this doesn’t make sense when we’re using an open API (in our case the transport API), in this case we prefer component tests.
In both cases, I consider these tests sufficiently important, and fast enough, to run to be integrated into a continuous integration pipeline, being run again and again with the objective of getting rapid feedback.
Contract tests are often associated with the Consumer-Driven Contracts pattern, and are an excellent way to verify that service consumers and providers (whether via REST or via messaging) are aligned on a common, shared contract. They also have the advantage of running fairly quickly (because of the insulation provided by wiremock) and can therefore be integrated into the continuous integration pipeline. In the next article, we’ll discuss much less straightforward tests to run: integration and end-to-end tests.