Writing Unit Tests for a Spring MVC REST API: Returning a Single Item

The previous part of my Spring MVC Test tutorial described how we can send HTTP requests to the system under test and write assertions for the response returned by the tested controller method. This blog post describes how we can use the information provided by the previous part of this tutorial when we are writing unit tests for a controller method which returns the information of a single item 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.

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/{id}'. The contract of this API endpoint is described in the following:

  • If the requested todo item is found, the system under test returns the HTTP status code 200. The system under test also creates a JSON document which contains the information of the found todo item and adds this document to the body of the returned HTTP response.
  • If the requested todo item isn't found, the system under test returns the HTTP status code 404. Because no todo item is found, the body of the returned HTTP response is empty.

The tested controller method is called findById() and it simply returns the information of the todo item that's 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.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

    @Autowired
    public TodoItemCrudController(TodoItemCrudService service) {
        this.service = service;
    }
    
    @GetMapping("{id}")
    public TodoItemDTO findById(@PathVariable("id") Long id) {
        return service.findById(id);
    }
}

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

public class TodoItemDTO {

    private Long id;
    private String description;
    private List<TagDTO> tags;
    private String title;
    private TodoItemStatus status;

    //Getters and setters are omitted
}

The TagDTO class is a a DTO that contains the information of a single tag. Its source code looks as follows:

public class TagDTO {

    private Long id;
    private String name;

    //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 the found todo item is in progress and has one tag, the following JSON document is returned back to the client:

{
	"id":1,
	"description":"Remember to use JUnit 5",
	"tags":[
		{
			"id":9,
			"name":"Code"
		}
	],
	"title":"Write example application",
	"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 the information of a single item 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.

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:

  1. Add a new method called findById() to our request builder class. Ensure that this method takes the id of the todo item as a method parameter and returns a ResultActions object.
  2. Send a GET request to the path: '/todo-item/{id}' 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 findById(Long id) throws Exception {
        return mockMvc.perform(get("/todo-item/{id}", id));
    }
}

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:

  1. Add an inner class called FindById to our test class. This inner class contains the test methods which ensure that the system under test is working as expected.
  2. Add an inner class called WhenRequestedTodoItemIsNotFound to the FindById class. This inner class contains the test methods which ensure that the system under test is working as expected when the requested todo item isn't found from the database.
  3. Add an inner class called WhenRequestedTodoItemIsFound to the FindById class. This inner class contains the test methods which ensure that the system under test is working as expected when the requested todo item is 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 todo item by using its id as search criteria")
    class FindById {

        @Nested
        @DisplayName("When the requested todo item isn't found")
        class WhenRequestedTodoItemIsNotFound {

        }

        @Nested
        @DisplayName("When the requested todo item is found")
        class WhenRequestedTodoItemIsFound {

        }
    }
}

Second, we have to ensure that the system under test is working as expected when the requested todo item isn't found from the database. We can write the required test methods by following these steps:

  1. Add a constant called TODO_ITEM_ID to the FindById class. This constant specifies the id of the requested todo item. We have to add this constant to the FindById class because its value is used by the test methods found from the WhenRequestedTodoItemIsNotFound and WhenRequestedTodoItemIsFound classes.
  2. Add a new setup method to the WhenRequestedTodoItemIsNotFound class and ensure that it's run before a test method is run. When we implement this setup method, we must ensure that the TodoItemCrudService object throws a TodoItemNotFoundException when its findById() method is invoked by using the argument: 1L.
  3. Ensure that the system under test returns the HTTP status code 404.
  4. Verify that the system under test returns an HTTP response which has an empty response body.

After we have written the required test methods, 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.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import static net.petrikainulainen.springmvctest.junit5.web.WebTestConfig.*;
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.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 todo item by using its id as search criteria")
    class FindById {

        private static final Long TODO_ITEM_ID = 1L;

        @Nested
        @DisplayName("When the requested todo item isn't found")
        class WhenRequestedTodoItemIsNotFound {

            @BeforeEach
            void throwException() {
                given(service.findById(TODO_ITEM_ID))
                        .willThrow(new TodoItemNotFoundException(""));
            }

            @Test
            @DisplayName("Should return the HTTP status code not found (404)")
            void shouldReturnHttpStatusCodeNotFound() throws Exception {
                requestBuilder.findById(TODO_ITEM_ID)
                        .andExpect(status().isNotFound());
            }

            @Test
            @DisplayName("Should return HTTP response which has an empty response body")
            void shouldReturnHttpResponseWhichHasEmptyResponseBody() throws Exception {
                requestBuilder.findById(TODO_ITEM_ID)
                        .andExpect(content().string(""));
            }
        }

        //The other inner class is omitted
    }
}

Third, we have to ensure that the system under test is working as expected when the requested todo item is found from the database. We can write the required test methods by following these steps:

  1. Add the required constants to the WhenRequestedTodoItemIsFound class. These constants specify the property values of the found todo item.
  2. Add a new setup method to the WhenRequestedTodoItemIsFound class and ensure that it's run before a test method is run. When we implement this setup method, we must ensure that the TodoItemCrudService object returns the information of the found todo item when its findById() method is invoked by using the argument: 1L.
  3. Ensure that the system under test returns the HTTP status code 200.
  4. Verify that the system under test returns the information of the found todo item as JSON.
  5. Ensure that the system under test returns the information of the found todo item.
  6. Verify that the system under test returns the information of a todo item that has one tag.
  7. Ensure that the system under test returns the information of the found tag.

After we have written the required test methods, 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 todo item by using its id as search criteria")
    class FindById {

        private static final Long TODO_ITEM_ID = 1L;

        //The other inner class is omitted

        @Nested
        @DisplayName("When the requested todo item is found")
        class WhenRequestedTodoItemIsFound {

            private static final String DESCRIPTION = "Remember to use JUnit 5";
            private static final Long TAG_ID = 9L;
            private static final String TAG_NAME  = "Code";
            private static final String TITLE = "Write example application";
            private static final TodoItemStatus STATUS = TodoItemStatus.IN_PROGRESS;

            @BeforeEach
            void returnFoundTodoItem() {
                TodoItemDTO found = new TodoItemDTO();
                found.setId(TODO_ITEM_ID);
                found.setDescription(DESCRIPTION);
                found.setStatus(STATUS);
                found.setTitle(TITLE);

                TagDTO tag = new TagDTO();
                tag.setId(TAG_ID);
                tag.setName(TAG_NAME);
                found.setTags(Arrays.asList(tag));

                given(service.findById(TODO_ITEM_ID)).willReturn(found);
            }

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

            @Test
            @DisplayName("Should return the information of the found todo item as JSON")
            void shouldReturnInformationOfFoundTodoItemAsJSON() throws Exception {
                requestBuilder.findById(TODO_ITEM_ID)
                        .andExpect(content().contentType(MediaType.APPLICATION_JSON));
            }

            @Test
            @DisplayName("Should return the information of the found todo item")
            void shouldReturnInformationOfFoundTodoItem() throws Exception {
                requestBuilder.findById(TODO_ITEM_ID)
                        .andExpect(jsonPath("$.id", 
                                equalTo(TODO_ITEM_ID.intValue()))
                        )
                        .andExpect(jsonPath("$.description", 
                                equalTo(DESCRIPTION))
                        )
                        .andExpect(jsonPath("$.status", 
                                equalTo(STATUS.name()))
                        )
                        .andExpect(jsonPath("$.title",
                                equalTo(TITLE))
                        );
            }

            @Test
            @DisplayName("Should return a todo item that has one tag")
            void shouldReturnTodoItemThatHasOneTag() throws Exception {
                requestBuilder.findById(TODO_ITEM_ID)
                        .andExpect(jsonPath("$.tags", hasSize(1)));
            }

            @Test
            @DisplayName("Should return the information of the found tag")
            void shouldReturnInformationOfFoundTag() throws Exception {
                requestBuilder.findById(TODO_ITEM_ID)
                        .andExpect(jsonPath("$.tags[0].id", 
                                equalTo(TAG_ID.intValue()))
                        )
                        .andExpect(jsonPath("$.tags[0].name", 
                                equalTo(TAG_NAME))
                        );
            }
        }
    }
}

We can now write unit tests for a controller method which returns the information of a single item 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.

0 comments… add one

Leave a Reply