# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.leapwise.co/backend-handbook/development-practices/testing-guidelines/contract-tests/rest-controller-contract-testing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.