Writing Unit Tests for a Spring MVC REST API: Returning a List

Author: Petri Kainulainen Published: May 8, 2022 0 comments

Tags: JUnit 5, Spring MVC Test

The previous part of my Spring MVC Test tutorial described how we can write unit tests for Spring MVC controllers which return the information of a single item as JSON. This blog post provides more information about writing unit tests for a Spring MVC REST API. To be more specific, this blog post describes how we can write unit tests for a Spring MVC controller that returns a list as JSON.

After we have finished this blog post, we:

Know how we can ensure that the system under test returns the correct HTTP status code.
Can verify that the system under test returns the correct information.

Let's begin.

This blog post assumes that:

Introduction to the System Under Test

We have to write unit tests for a controller method that processes GET requests send to the path: '/todo-item'. The contract of this API endpoint is described in the following:

The system under test always returns the HTTP status code 200.
If todo items are found, the system under test creates a JSON document which contains a list of found todo items and adds this document to the body of the returned HTTP response.
If no todo items are found, the system under test creates a JSON document which contains an empty list and adds this document to the body of the returned HTTP response.

The tested controller method is called findAll() and it simply returns the todo items which are found from the database. The source code of the tested controller method looks as follows:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/todo-item")
public class TodoItemCrudController {
    private final TodoItemCrudService service;

    @Autowired
    public TodoItemCrudController(TodoItemCrudService service) {
        this.service = service;
    }

    @GetMapping
    public List<TodoListItemDTO> findAll() {
        return service.findAll();
    }
}

The TodoListItemDTO class is a DTO that contains the information of a single todo item. Its source code looks as follows:

public class TodoListItemDTO {

    private Long id;
    private String title;
    private TodoItemStatus status;
    
    //Getters and setters are omitted
}

The TodoItemStatus enum specifies the possible statuses of a todo item. Its source code looks as follows:

public enum TodoItemStatus {
    OPEN,
    IN_PROGRESS,
    DONE
}

For example, if two todo items are found from the database, the system under test returns the following JSON document back to the client:

[
	{
		"id":1,
		"title":"Write example application",
		"status":"DONE"
	},
	{
		"id":2,
		"title":"Write blog post",
		"status":"IN_PROGRESS"
	}
]

Next, we will learn how we can write assertions for the response returned by the system under test.

Writing Assertions for the Response Returned by the System Under Test

Before we can write unit tests for a Spring MVC controller which returns a list as JSON, we have to learn how we can write assertions for the HTTP response returned by the system under test. When we want to write assertions for the HTTP response returned by the tested Spring MVC controller, we have to use these static methods of the MockMvcResultMatchers class:

The status() method returns a StatusResultMatchers object which allows us to write assertions for the returned HTTP status.
The content() method returns a ContentResultMatchers object which allows us to write assertions for the content of the returned HTTP response.
The jsonPath() method returns a JsonPathResultMatchers object which allows us to write assertions for the body of the returned HTTP response by using JsonPath expressions and Hamcrest matchers.

Additional Reading:

Because we are writing assertions by using JsonPath expressions and Hamcrest matchers, we must ensure that the json-path and hamcrest-library dependencies are found from the classpath. If we are using Maven and Spring Boot dependency management, we can declare these dependencies by adding the following XML snippet to the dependencies section of our POM file:

<dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>hamcrest-library</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>com.jayway.jsonpath</groupId>
    <artifactId>json-path</artifactId>
    <scope>test</scope>
</dependency>

Let's move on and find out how we can write a request builder method which sends GET requests to the system under test.

Writing a New Request Builder Method

Because we want to remove duplicate code from our test class, we have to create and send HTTP requests to the system under test by using a so called request builder class. In other words, before we can write unit tests for the system under test, we have write to a request builder method which creates and sends HTTP requests to the system under test. We can write this request builder method by following these steps:

Add a new method called findAll() to our request builder class. Ensure that this method returns a ResultActions object.
Send a GET request to the path: '/todo-item' by invoking the perform() method of the MockMvc class. Remember to return the ResultActions object that's returned by the perform() method.

After we have written our request builder method, the source code of our request builder class looks as follows:

import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.ResultActions;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;

class TodoItemRequestBuilder {

    private final MockMvc mockMvc;

    TodoItemRequestBuilder(MockMvc mockMvc) {
        this.mockMvc = mockMvc;
    }
    
    ResultActions findAll() throws Exception {
        return mockMvc.perform(get("/todo-item"));
    }
}

Additional Reading:

Next, we will learn to write unit tests for the system under test.

Writing Unit Tests for the System Under Test

When we want to write unit tests for the system under test, we have to follow these steps:

First, we have to add the required class hierarchy to our test class. Because we are writing unit tests, we can create this class hierarchy by following these steps:

Add an inner class called FindAll to our test class. This inner class contains the test methods which ensure that the system under test is working as expected.
Add an inner class called WhenNoTodoItemsAreFound to the FindAll class. This inner class contains the test methods which ensure that the system under test is working as expected when no todo items are found from the database.
Add an inner class called WhenTwoTodoItemsAreFound to the FindAll class. This inner class contains the test methods which ensure that the system under test is working as expected when two todo items are found from the database.

After we have created the required class hierarchy, the source code of our test class looks as follows:

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Nested;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import static net.petrikainulainen.springmvctest.junit5.web.WebTestConfig.*;
import static org.mockito.Mockito.mock;

class TodoItemCrudControllerTest {

    private TodoItemRequestBuilder requestBuilder;
    private TodoItemCrudService service;

    @BeforeEach
    void configureSystemUnderTest() {
        service = mock(TodoItemCrudService.class);

        TodoItemCrudController testedController = new TodoItemCrudController(service);
        MockMvc mockMvc = MockMvcBuilders.standaloneSetup(testedController)
                .setControllerAdvice(new TodoItemErrorHandler())
                .setMessageConverters(objectMapperHttpMessageConverter())
                .build();
        requestBuilder = new TodoItemRequestBuilder(mockMvc);
    }

    @Nested
    @DisplayName("Find all todo items")
    class FindAll {
        
        @Nested
        @DisplayName("When no todo items are found")
        class WhenNoTodoItemsAreFound {
            
        }

        @Nested
        @DisplayName("When two todo items are found")
        class WhenTwoTodoItemsAreFound {
            
        }
    }
}

Second, because we don't want to add duplicate code to our test class, we will add some test methods to the FindAll class. These unit tests specify the behavior of the system under test in all possible scenarios. We can write these unit tests by following these steps:

Ensure that the system under test returns the HTTP status code 200.
Verify that the system under test returns the information of the found todo items as JSON.

After we have written these unit tests, the source code of our test class looks as follows:

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import static net.petrikainulainen.springmvctest.junit5.web.WebTestConfig.*;
import static org.mockito.Mockito.mock;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class TodoItemCrudControllerTest {

    private TodoItemRequestBuilder requestBuilder;
    private TodoItemCrudService service;

    @BeforeEach
    void configureSystemUnderTest() {
        service = mock(TodoItemCrudService.class);

        TodoItemCrudController testedController = new TodoItemCrudController(service);
        MockMvc mockMvc = MockMvcBuilders.standaloneSetup(testedController)
                .setControllerAdvice(new TodoItemErrorHandler())
                .setMessageConverters(objectMapperHttpMessageConverter())
                .build();
        requestBuilder = new TodoItemRequestBuilder(mockMvc);
    }

    @Nested
    @DisplayName("Find all todo items")
    class FindAll {

        @Test
        @DisplayName("Should return the HTTP status code OK (200)")
        void shouldReturnHttpStatusCodeOk() throws Exception {
            requestBuilder.findAll()
                    .andExpect(status().isOk());
        }

        @Test
        @DisplayName("Should return the found todo items as JSON")
        void shouldReturnFoundTodoItemAsJSON() throws Exception {
            requestBuilder.findAll()
                    .andExpect(content().contentType(MediaType.APPLICATION_JSON));
        }

        //The other inner classes are omitted
    }
}

Third, we have to write the unit tests which ensure that the system under test is working as expected when no todo items are found from the database. We can write the required test methods by following these steps:

Add a new setup method to the WhenNoTodoItemsAreFound class and ensure that it's run before a test method is run. When we implement this method, we must ensure that the TodoItemCrudService object returns an empty list when its findAll() method is invoked.
Ensure that the system under test returns a JSON document that contains an empty list.

After we have written the required unit tests, the source code of our test class looks as follows:

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import java.util.ArrayList;

import static net.petrikainulainen.springmvctest.junit5.web.WebTestConfig.*;
import static org.hamcrest.Matchers.hasSize;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.mock;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class TodoItemCrudControllerTest {

    private TodoItemRequestBuilder requestBuilder;
    private TodoItemCrudService service;

    @BeforeEach
    void configureSystemUnderTest() {
        service = mock(TodoItemCrudService.class);

        TodoItemCrudController testedController = new TodoItemCrudController(service);
        MockMvc mockMvc = MockMvcBuilders.standaloneSetup(testedController)
                .setControllerAdvice(new TodoItemErrorHandler())
                .setMessageConverters(objectMapperHttpMessageConverter())
                .build();
        requestBuilder = new TodoItemRequestBuilder(mockMvc);
    }

    @Nested
    @DisplayName("Find all todo items")
    class FindAll {

        @Test
        @DisplayName("Should return the HTTP status code OK (200)")
        void shouldReturnHttpStatusCodeOk() throws Exception {
            requestBuilder.findAll()
                    .andExpect(status().isOk());
        }

        @Test
        @DisplayName("Should return the found todo items as JSON")
        void shouldReturnFoundTodoItemAsJSON() throws Exception {
            requestBuilder.findAll()
                    .andExpect(content().contentType(MediaType.APPLICATION_JSON));
        }

        @Nested
        @DisplayName("When no todo items are found")
        class WhenNoTodoItemsAreFound {

            @BeforeEach
            void returnEmptyList() {
                given(service.findAll()).willReturn(new ArrayList<>());
            }

            @Test
            @DisplayName("Should return zero todo items")
            void shouldReturnZeroTodoItems() throws Exception {
                requestBuilder.findAll()
                        .andExpect(jsonPath("$", hasSize(0)));
            }
        }

        //The other inner class is omitted
    }
}

Fourth, we have to write the unit tests which ensure that the system under test is working as expected when two todo items are found from the database. We can write the required test methods by following these steps:

Add the required constants to the WhenTwoTodoItemsAreFound class. These constants specify the information of the found todo items.
Add a new setup method to the WhenTwoTodoItemsAreFound class and ensure that it's run before a test method is run. When we implement this method, we must ensure that the TodoItemCrudService object returns a list that contains two todo items when its findAll() method is invoked.
Ensure that the system under test returns a JSON document that contains two todo items.
Verify that the system under test returns the correct information of the first todo item.
Ensure that the system under test returns the correct information of the second todo item.

After we have written the required unit tests, the source code of our test class looks as follows:

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import java.util.Arrays;

import static net.petrikainulainen.springmvctest.junit5.web.WebTestConfig.*;
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.hasSize;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.mock;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class TodoItemCrudControllerTest {

    private TodoItemRequestBuilder requestBuilder;
    private TodoItemCrudService service;

    @BeforeEach
    void configureSystemUnderTest() {
        service = mock(TodoItemCrudService.class);

        TodoItemCrudController testedController = new TodoItemCrudController(service);
        MockMvc mockMvc = MockMvcBuilders.standaloneSetup(testedController)
                .setControllerAdvice(new TodoItemErrorHandler())
                .setMessageConverters(objectMapperHttpMessageConverter())
                .build();
        requestBuilder = new TodoItemRequestBuilder(mockMvc);
    }

    @Nested
    @DisplayName("Find all todo items")
    class FindAll {

        @Test
        @DisplayName("Should return the HTTP status code OK (200)")
        void shouldReturnHttpStatusCodeOk() throws Exception {
            requestBuilder.findAll()
                    .andExpect(status().isOk());
        }

        @Test
        @DisplayName("Should return the found todo items as JSON")
        void shouldReturnFoundTodoItemAsJSON() throws Exception {
            requestBuilder.findAll()
                    .andExpect(content().contentType(MediaType.APPLICATION_JSON));
        }

        //The other inner class is omitted

        @Nested
        @DisplayName("When two todo items are found")
        class WhenTwoTodoItemsAreFound {

            private static final Long FIRST_TODO_ITEM_ID = 1L;
            private static final TodoItemStatus FIRST_TODO_ITEM_STATUS = TodoItemStatus.DONE;
            private static final String FIRST_TODO_ITEM_TITLE = "Write example application";

            private static final Long SECOND_TODO_ITEM_ID = 2L;
            private static final TodoItemStatus SECOND_TODO_ITEM_STATUS = TodoItemStatus.IN_PROGRESS;
            private static final String SECOND_TODO_ITEM_TITLE = "Write blog post";

            @BeforeEach
            void returnTwoTodoItems() {
                TodoListItemDTO first = new TodoListItemDTO();
                first.setId(FIRST_TODO_ITEM_ID);
                first.setStatus(FIRST_TODO_ITEM_STATUS);
                first.setTitle(FIRST_TODO_ITEM_TITLE);

                TodoListItemDTO second = new TodoListItemDTO();
                second.setId(SECOND_TODO_ITEM_ID);
                second.setStatus(SECOND_TODO_ITEM_STATUS);
                second.setTitle(SECOND_TODO_ITEM_TITLE);

                given(service.findAll()).willReturn(Arrays.asList(first, second));
            }

            @Test
            @DisplayName("Should return two todo items")
            void shouldReturnTwoTodoItems() throws Exception {
                requestBuilder.findAll()
                        .andExpect(jsonPath("$", hasSize(2)));
            }

            @Test
            @DisplayName("Should return the information of the first todo item")
            void shouldReturnInformationOfFirstTodoItem() throws Exception {
                requestBuilder.findAll()
                        .andExpect(jsonPath("$[0].id",
                                equalTo(FIRST_TODO_ITEM_ID.intValue()))
                        )
                        .andExpect(jsonPath("$[0].status",
                                equalTo(FIRST_TODO_ITEM_STATUS.name()))
                        )
                        .andExpect(jsonPath("$[0].title",
                                equalTo(FIRST_TODO_ITEM_TITLE))
                        );
            }

            @Test
            @DisplayName("Should return the information of the second todo item")
            void shouldReturnInformationOfSecondTodoItem() throws Exception {
                requestBuilder.findAll()
                        .andExpect(jsonPath("$[1].id",
                                equalTo(SECOND_TODO_ITEM_ID.intValue()))
                        )
                        .andExpect(jsonPath("$[1].status",
                                equalTo(SECOND_TODO_ITEM_STATUS.name()))
                        )
                        .andExpect(jsonPath("$[1].title",
                                equalTo(SECOND_TODO_ITEM_TITLE))
                        );
            }
        }
    }
}

Additional Reading:

We can now write unit tests for a controller method which returns a list as JSON. Let's summarize what we learned from this blog post.

Summary

This blog post has taught us four things:

When we want to write assertions for the returned HTTP status, we have to invoke the status() method of the MockMvcResultMatchers class.
When we want to write assertions for the content of the returned HTTP response, we have to invoke the content() method of the MockMvcResultMatchers class.
When we want to write assertions for the body of the returned HTTP response by using JsonPath expressions and Hamcrest matchers, we have to invoke the jsonPath() method of the MockMvcResultMatchers class.
If we want to write assertions for the body of the returned HTTP response by using JsonPath expressions and Hamcrest matchers, we must ensure that the json-path and hamcrest-library dependencies are found from the classpath

P.S. You can get the example application of this blog post from Github.