> For the complete documentation index, see [llms.txt](https://docs.leapwise.co/backend-handbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.leapwise.co/backend-handbook/development-practices/testing-guidelines/contract-tests/rest-controller-contract-testing.md).

# 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** <a href="#deserialising-input" id="deserialising-input"></a>

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** <a href="#serialising-output" id="serialising-output"></a>

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