Unit Testing REST Controllers with MockMvc

Overview

Provides patterns for unit testing @RestController and @Controller classes using MockMvc. Covers request/response handling, HTTP status codes, request parameter binding, validation, content negotiation, response headers, and exception handling with mocked service dependencies.

When to Use

Use for: controller tests, API endpoint testing, Spring MVC tests, mock HTTP requests, unit testing web layer endpoints, verifying REST controllers in isolation.

Instructions

• Setup standalone MockMvc: MockMvcBuilders.standaloneSetup(controller) for isolated testing

• Mock service dependencies: Use @Mock for all services, @InjectMocks for the controller

• Test HTTP methods: GET, POST, PUT, PATCH, DELETE with correct status codes

• Validate responses: JsonPath assertions for JSON, content matchers for body

• Test validation: Send invalid input, verify 400 status with error details

• Test errors: Verify 404, 400, 401, 403, 500 for appropriate conditions

• Validate headers: Both request (Authorization) and response headers

• Test content negotiation: Different Accept and Content-Type headers

Validation Workflow

Run test → If fails: add .andDo(print()) → Check actual vs expected → Fix assertion

Examples

Maven / Gradle Dependencies

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency>

Basic Pattern: GET Endpoint

import static org.mockito.Mockito.; import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@ExtendWith(MockitoExtension.class) class UserControllerTest {

@Mock private UserService userService;

@InjectMocks private UserController userController;

private MockMvc mockMvc;

@BeforeEach void setUp() { mockMvc = MockMvcBuilders.standaloneSetup(userController).build(); }

@Test void shouldReturnAllUsers() throws Exception { List<UserDto> users = List.of(new UserDto(1L, "Alice"), new UserDto(2L, "Bob")); when(userService.getAllUsers()).thenReturn(users);

mockMvc.perform(get("/api/users"))
  .andExpect(status().isOk())
  .andExpect(jsonPath("$[0].id").value(1))
  .andExpect(jsonPath("$[0].name").value("Alice"));

verify(userService, times(1)).getAllUsers();

}

@Test void shouldReturn404WhenUserNotFound() throws Exception { when(userService.getUserById(999L)) .thenThrow(new UserNotFoundException("User not found"));

mockMvc.perform(get("/api/users/999"))
  .andExpect(status().isNotFound());

verify(userService).getUserById(999L);

} }

POST: Create Resource

@Test void shouldCreateUserAndReturn201() throws Exception { UserDto createdUser = new UserDto(1L, "Alice", "alice@example.com"); when(userService.createUser(any())).thenReturn(createdUser);

mockMvc.perform(post("/api/users") .contentType("application/json") .content("{"name":"Alice","email":"alice@example.com"}")) .andExpect(status().isCreated()) .andExpect(jsonPath("$.id").value(1)) .andExpect(jsonPath("$.name").value("Alice"));

verify(userService).createUser(any(UserCreateRequest.class)); }

PUT: Update Resource

@Test void shouldUpdateUserAndReturn200() throws Exception { UserDto updatedUser = new UserDto(1L, "Updated"); when(userService.updateUser(eq(1L), any())).thenReturn(updatedUser);

mockMvc.perform(put("/api/users/1") .contentType("application/json") .content("{"name":"Updated"}")) .andExpect(status().isOk()) .andExpect(jsonPath("$.name").value("Updated"));

verify(userService).updateUser(eq(1L), any()); }

DELETE: Remove Resource

@Test void shouldDeleteUserAndReturn204() throws Exception { doNothing().when(userService).deleteUser(1L);

mockMvc.perform(delete("/api/users/1")) .andExpect(status().isNoContent());

verify(userService).deleteUser(1L); }

Query Parameters

@Test void shouldFilterUsersByName() throws Exception { when(userService.searchUsers("Alice")).thenReturn(List.of(new UserDto(1L, "Alice")));

mockMvc.perform(get("/api/users/search").param("name", "Alice")) .andExpect(status().isOk()) .andExpect(jsonPath("$[0].name").value("Alice"));

verify(userService).searchUsers("Alice"); }

Path Variables

@Test void shouldGetUserByIdFromPath() throws Exception { when(userService.getUserById(123L)).thenReturn(new UserDto(123L, "Alice"));

mockMvc.perform(get("/api/users/{id}", 123L)) .andExpect(status().isOk()) .andExpect(jsonPath("$.id").value(123)); }

Validation Errors (400)

@Test void shouldReturn400WhenRequestBodyInvalid() throws Exception { mockMvc.perform(post("/api/users") .contentType("application/json") .content("{"name":""}")) .andExpect(status().isBadRequest()) .andExpect(jsonPath("$.errors").isArray()); }

Response Headers

@Test void shouldReturnCustomHeaders() throws Exception { when(userService.getAllUsers()).thenReturn(List.of());

mockMvc.perform(get("/api/users")) .andExpect(status().isOk()) .andExpect(header().exists("X-Total-Count")) .andExpect(header().string("X-Total-Count", "0")); }

Authorization Header

@Test void shouldRequireAuthorizationHeader() throws Exception { mockMvc.perform(get("/api/users")) .andExpect(status().isUnauthorized());

mockMvc.perform(get("/api/users").header("Authorization", "Bearer token")) .andExpect(status().isOk()); }

Content Negotiation

@Test void shouldReturnJsonWhenAcceptHeaderIsJson() throws Exception { when(userService.getUserById(1L)).thenReturn(new UserDto(1L, "Alice"));

mockMvc.perform(get("/api/users/1").accept("application/json")) .andExpect(status().isOk()) .andExpect(content().contentType("application/json")); }

Best Practices

• Use standaloneSetup() for isolated controller testing

• Mock service layer — controllers handle HTTP, services handle business logic

• Verify mock interactions: verify(service).method(args)

• Test happy path AND error scenarios (404, 400, 500)

• Use jsonPath() for fluent JSON assertions

• One focused assertion per test method

Constraints and Warnings

• Controller tests verify HTTP handling only — not full request flow

• standaloneSetup() may not support @Validated without full context

• JsonPath requires valid JSON in response body

• @PreAuthorize /@Secured need additional setup — consider separate security tests

• File uploads require MockMultipartFile

References

• Spring MockMvc Documentation

• Spring Testing Best Practices