REST Controller Contract testing

One of the first things that comes to mind when thinking about an application is it’s API. Today most of the APIs are built on the foundations of RESTful architecture which sets our applications REST controllers as the entries to our applications functionalities. Having that in mind, it’s critical to thoroughly test our REST controllers to make sure they are doing their job right.

A web controller has several important responsibilities:

1. Listening to HTTP requests

2. Deserialising input

3. Validating input

4. Calling the business logic

5. Serialising output

6. Handling exceptions

Contract testing

Since we don’t want over complicated tests, it’s a good practice to make a distinction between the tests responsibilities. Here, we are focusing on contract testing, which means that we are not testing the business logic related functionalities of the controller, but rather focusing on the request mapping and serialisation/deserialisation part.

For simplicity of testing, Spring Boot gives us the @WebMvcTest annotation for loading the application context with only the necessary beans for testing the web layer - that includes only specified Controllers and its dependencies. It’s a good practice to explicitly define the Controller you are testing for the @WebMvcTest annotation since we don’t need the other controllers in this test which simplifies the testing setup.

We use @MockBean to mock the business logic since we don’t want to test that part of the functionality.

Listening to HTTP requests

The controller methods should respond to certain URLs, content types and request headers, parameters and bodies. For the easiest setup MockMvc library is used which performs full Spring MVC request handling via mock request and response objects instead of a running server.

Testing outcome

• check if request headers, params and body are correct

• check if endpoint mapping is correct

Deserialising input

The controller methods should properly parse incoming HTTP requests and map them to corresponding Java objects

Testing outcome

• check if ObjectMapper is configured properly

• check if Java objects are missing any fields

• check that some fields are not empty or null

Serialising output

The controller methods serialises the dedicated Java response object and returns it to the caller - we can compare the returned

Testing outcome

• check if ObjectMapper parses response to JSON properly by comparing with exactly templated JSON string