Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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
@Mockfor all services,@InjectMocksfor 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 assertionExamples
Maven / Gradle Dependencies
xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>Basic Pattern: GET Endpoint
java
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
java
@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
java
@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
java
@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
java
@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
java
@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)
java
@Test
void shouldReturn400WhenRequestBodyInvalid() throws Exception {
mockMvc.perform(post("/api/users")
.contentType("application/json")
.content("{\"name\":\"\"}"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.errors").isArray());
}Response Headers
java
@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
java
@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
java
@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@Validatedwithout full context- JsonPath requires valid JSON in response body
@PreAuthorize/@Securedneed additional setup — consider separate security tests- File uploads require
MockMultipartFile
