In this tutorial, you will learn to implement unit test of the REST API and Controller layer in Spring Boot by using @WebMvcTest and MockMvc

@WebMvcTest is used in combination with @RunWith(SpringRunner.class) when a test focuses only on Spring MVC components. It provides the following features

  • Disable full auto-configuration (not @Component, @Service or @Repository beans) and instead apply only configuration relevant to MVC tests such as @Controller and @ControllerAdvice

  • Auto-configure Spring Security and MockMvc

Project dependencies

Include spring-boot-starter-test into your pom.xml file


spring-boot-starter-test contains some testing support libraries such as JUnit, Spring Test + Spring Boot Test, Mockito, AssertJ, Hamcrest and JsonPath

Define the test class

Run the tests with SpringRunner and @WebMvcTest

  • Use the @RunWith(SpringRunner.class) class annotation to tell JUnit to run the unit tests in Spring's testing supports
  • Use the @WebMvcTest class annotation to test only Spring MVC components

Inject MockMVC with @Autowired

  • Inject the MockMVC field into your test class, for example
private MockMvc mockMvc;  

Mock dependencies with @MockBean

  • Use @MockBean to mock API and Controller dependencies to the Spring ApplicationContext, for example
private ProductService productService;

private ProductMapper productMapper;  

Stub methods with Mockito's doReturn...when

  • Use Mockito.doReturn(...).when(aMock).doSomething(...) to give the test input, for example
// given
ProductDTO productDTO = ProductDTO.builder()  
    .description("P1 desc")
    .price(new BigDecimal("1"))

List<ProductDTO> productDTOs = Arrays.asList(productDTO);

doReturn(new ArrayList<>()).when(productService).findAll();     


Perform the test with MockMVC's perform(...) and Verify the test result with JsonPath and Hamcrest

  • Use MockMVC's perform(...) to perform a mock HTTP test request with MockMvcRequestBuilders
  • Use JsonPath and Hamcrest to verify the JSON response data
// when + then
    .andExpect(jsonPath("$[0].name", is(productDTO.getName())));

Implementation example

Source code