A Practical Guide to Testing Spring Controllers With MockMvcTester

Spring Framework 6.2 introduced MockMvcTester to support writing AssertJ style assertions using AssertJ under the hood. If you’re using Spring Boot, the spring-boot-starter-test dependency transitively adds the most commonly used testing libraries such as mockito, assertj, json-path, jsonassert, etc. So, if you’re using Spring Boot 3.4.0 (which uses Spring framework 6.2) or any later version, […]

Apr 22, 2025 - 16:46

A Practical Guide to Testing Spring Controllers With MockMvcTester

Spring Framework 6.2 introduced MockMvcTester to support writing AssertJ style assertions using AssertJ under the hood.

If you’re using Spring Boot, the spring-boot-starter-test dependency transitively adds the most commonly used testing libraries such as mockito, assertj, json-path, jsonassert, etc. So, if you’re using Spring Boot 3.4.0 (which uses Spring framework 6.2) or any later version, you don’t need to add any extra dependencies to use MockMvcTester.

In this article, we’ll explore how you can use MockMvcTester for different testing scenarios.

Getting started with MockMvcTester

MockMvcTester is built on top of MockMvc and provides AssertJ support for writing tests and asserting the result.

You can find the sample application code here.

Here is an example test written using MockMvc:

import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class UserRestControllerTests {
   @Autowired
   MockMvc mockMvc;

   @Test
   void getUserByIdSuccessful() throws Exception {
       mockMvc.perform(get("/api/users/1")).andExpect(status().isOk());
   }
}

The same test written using the MockMvcTester fluent API:

import org.springframework.test.web.servlet.assertj.MockMvcTester;
import static org.assertj.core.api.Assertions.assertThat;

class UserRestControllerTests {
   @Autowired
   MockMvcTester mockMvcTester;

   @Test
   void getUserByIdSuccessful() {
      assertThat(mockMvcTester.get().uri("/api/users/1")).hasStatusOk();
   }
}

It is much easier to use the MockMvcTester fluent API rather than using the IDE feature to find the static imports for get(), post(), status(), etc.

How to configure MockMvcTester?

If you’re writing a slice test for a controller using @WebMvcTest, you can simply inject MockMvcTester.

The @WebMvcTest annotation is meta-annotated with @AutoConfigureMockMvc, so a MockMvc instance is auto-configured. If AssertJ is available, then a MockMvcTester instance will also be auto-configured.

@WebMvcTest(controllers = UserRestController.class)
class UserRestControllerTests {
   @Autowired
   MockMvcTester mockMvcTester;

   //...
}

If you’re writing an integration test using @SpringBootTest, then you need to add the @AutoConfigureMockMvc annotation to the test class, and you can also inject MockMvcTester.

@SpringBootTest
@AutoConfigureMockMvc
class UserRestControllerTests {
   @Autowired
   MockMvcTester mockMvcTester;

   //...
}

If you’re already using MockMvc, then you can gradually adopt MockMvcTester by creating a MockMvcTester instance from MockMvc:

class UserRestControllerTests {
   @Autowired
   MockMvc mockMvc;

   MockMvcTester mockMvcTester;

   @PostConstruct
   void setUp() {
       mockMvcTester = MockMvcTester.create(mockMvc);
   }

   //...
}

Writing tests using MockMvcTester

Let’s explore how we can write tests using MockMvcTester in various scenarios.

Testing REST API JSON response

Assume we have a REST API endpoint for user registration that returns HTTP code 201 when successful, along with the response JSON payload with name, email, and role properties.

We can write a test using MockMvcTester:

import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.assertj.MockMvcTester;
import org.springframework.test.web.servlet.assertj.MvcTestResult;

import static org.assertj.core.api.Assertions.assertThat;

@Test
void userRegistrationSuccessful() {
   String requestBody = """
           {
               "email": "siva@gmail.com",
               "password": "secret",
               "name": "Siva"
           }
           """;

   assertThat(mockMvcTester
       	.post()
       	.uri("/api/users")
       	.contentType(MediaType.APPLICATION_JSON)
       	.content(requestBody))
        .hasStatus(HttpStatus.CREATED)
        .bodyJson()
        .isLenientlyEqualTo("""
             {
               "name": "Siva",
               "email": "siva@gmail.com",
               "role": "ROLE_USER"
             }
          """);
}

We have compared the HTTP status code, converted the response body to JSON, and compared it with our expected JSON structure.

We can split the code into two parts to execute the request and assert the result:

MvcTestResult testResult = mockMvcTester
       .post()
       .uri("/api/users")
       .contentType(MediaType.APPLICATION_JSON)
       .content(requestBody)
       .exchange();

assertThat(testResult)
       .hasStatus(HttpStatus.CREATED)
       .bodyJson()
       .isLenientlyEqualTo("""
           {
              "name": "Siva",
              "email": "siva@gmail.com",
              "role": "ROLE_USER"
           }
         """);

So far, we have compared the response JSON with our expected JSON structure using a multiline string. Instead, we can also store the JSON as a classpath resource and compare them:

var expected = new ClassPathResource("/user-registration-response.json", UserRestControllerTests.class);

assertThat(testResult)
       .hasStatus(HttpStatus.CREATED)
       .bodyJson()
       .isLenientlyEqualTo(expected);

If you need more control over the response body assertions, you can map the response into a Java object and assert it:

public record RegistrationResponse(String name, String email, String role) {}

assertThat(testResult)
       .hasStatus(HttpStatus.CREATED)
       .bodyJson()
       .convertTo(RegistrationResponse.class)
       .satisfies(response -> {
           assertThat(response.name()).isEqualTo("Siva");
           assertThat(response.email()).isEqualTo("siva@gmail.com");
           assertThat(response.role()).isEqualTo("ROLE_USER");
       });

Testing REST API exception handling scenarios

It is common practice to use @RestControllerAdvice to handle exceptions centrally:

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

   @ExceptionHandler(UserAlreadyExistsException.class)
   public ResponseEntity