unit-test-controller-layer

OverviewHistoryStatsSecurity

npx skills add giuseppe-trisciuoglio/developer-kit --skill unit-test-controller-layer

Documentation

SKILL.md

npx skills add ...

Documentation

SKILL.md

Provides patterns for unit testing REST controllers using MockMvc and @WebMvcTest. Generates controller tests that validates request/response mapping, validation, exception handling, and HTTP status codes. Use when testing web layer endpoints in isolation for API endpoint testing, Spring MVC tests, mock HTTP requests, or controller layer unit tests.

npx skills add giuseppe-trisciuoglio/developer-kit --skill unit-test-controller-layer

Documentation

SKILL.mdView source

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

npx skills add giuseppe-trisciuoglio/developer-kit --skill unit-test-controller-layer

Documentation

SKILL.md

npx skills add giuseppe-trisciuoglio/developer-kit --skill unit-test-controller-layer

Documentation

SKILL.mdView source

Unit Testing REST Controllers with MockMvc

Overview

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