Unit Testing ExceptionHandler and ControllerAdvice
Overview
This skill provides patterns for writing unit tests for Spring Boot exception handlers. It covers testing @ExceptionHandler methods in @ControllerAdvice classes using MockMvc, including HTTP status assertions, JSON response validation, field-level validation error testing, and mocking handler dependencies.
When to Use
- Writing unit tests for
@ExceptionHandler methods
- Testing
@ControllerAdvice global exception handling
- Validating REST API error response formatting
- Mocking exceptions in controller tests
- Testing field-level validation error responses
- Asserting custom error payloads and HTTP status codes
Instructions
- Create a test controller that throws specific exceptions to trigger each
@ExceptionHandler
- Register ControllerAdvice via
setControllerAdvice() on MockMvcBuilders.standaloneSetup()
- Assert HTTP status codes with
.andExpect(status().isXxx())
- Verify error response fields using
jsonPath("$.field") matchers
- Test validation errors by sending invalid payloads and checking
MethodArgumentNotValidException produces field-level details
- Debug failures with
.andDo(print()) — if handler not invoked, verify setControllerAdvice() is called and exception type matches
Examples
Exception Handler and Error DTO
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ResourceNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public ErrorResponse handleNotFound(ResourceNotFoundException ex) {
return new ErrorResponse(404, "Not Found", ex.getMessage());
}
@ExceptionHandler(ValidationException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public ErrorResponse handleValidation(ValidationException ex) {
return new ErrorResponse(400, "Bad Request", ex.getMessage());
}
@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public ValidationErrorResponse handleMethodArgumentNotValid(MethodArgumentNotValidException ex) {
Map<String, String> errors = new HashMap<>();
ex.getBindingResult().getFieldErrors().forEach(e -> errors.put(e.getField(), e.getDefaultMessage()));
return new ValidationErrorResponse(400, "Validation Failed", errors);
}
}
public record ErrorResponse(int status, String error, String message) {}
public record ValidationErrorResponse(int status, String error, Map<String, String> errors) {}
Unit Test
@ExtendWith(MockitoExtension.class)
class GlobalExceptionHandlerTest {
private MockMvc mockMvc;
@BeforeEach
void setUp() {
GlobalExceptionHandler handler = new GlobalExceptionHandler();
mockMvc = MockMvcBuilders.standaloneSetup(new TestController())
.setControllerAdvice(handler)
.build();
}
@Test
void shouldReturn404WhenResourceNotFound() throws Exception {
mockMvc.perform(get("/api/users/999"))
.andExpect(status().isNotFound())
.andExpect(jsonPath("$.status").value(404))
.andExpect(jsonPath("$.error").value("Not Found"))
.andExpect(jsonPath("$.message").value("User not found"));
}
@Test
void shouldReturn400WithFieldErrorsOnValidationFailure() throws Exception {
mockMvc.perform(post("/api/users")
.contentType("application/json")
.content("{\"name\":\"\",\"email\":\"invalid\"}"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.status").value(400))
.andExpect(jsonPath("$.errors.name").value("must not be blank"))
.andExpect(jsonPath("$.errors.email").value("must be a valid email"));
}
}
@RestController
@RequestMapping("/api")
class TestController {
@GetMapping("/users/{id}") public User getUser(@PathVariable Long id) {
throw new ResourceNotFoundException("User not found");
}
@PostMapping("/users") public User createUser(@RequestBody @Valid User user) {
throw new ValidationException("Validation failed");
}
}
Best Practices
- Test each
@ExceptionHandler method independently with a dedicated exception throw
- Register exactly one
@ControllerAdvice instance via setControllerAdvice() — never skip it
- Assert all fields in the error response body, not just the HTTP status
- For validation errors, verify both the field name key and the error message value
- Use
MockMvcBuilders.standaloneSetup() for isolated handler tests without full Spring context
- Log assertion failures: chain
.andDo(print()) to print request/response when a test fails
Common Pitfalls
- Handler not invoked: ensure
setControllerAdvice() is called on the builder
- JsonPath mismatch: use
.andDo(print()) to inspect actual response structure
- Status is 200: missing
@ResponseStatus on the handler method
- Duplicate handlers:
@Order controls precedence; more specific exception types take priority
- Testing handler logic instead of behavior: mock external dependencies, test only the response transformation
Constraints and Warnings
@ExceptionHandler specificity: more specific exception types are matched first; Exception.class catches all unmatched types
@ResponseStatus default: without @ResponseStatus or returning ResponseEntity, HTTP status defaults to 200
- Global vs local scope:
@ExceptionHandler in @ControllerAdvice is global; declared in a controller it is local only to that controller
- Logging side effects: handlers that log should be verified with
verify(mockLogger).logXxx(...)
- Localization: when using
MessageSource, test with different Locale values to confirm message resolution
- Security context:
AuthorizationException handlers can access SecurityContextHolder — test that context is correctly evaluated
1---
2name: unit-test-exception-handler
3description: Provides patterns for unit testing `@ExceptionHandler` and `@ControllerAdvice` in Spring Boot applications. Validates error response formatting, mocks exceptions, verifies HTTP status codes, tests field-level validation errors, and asserts custom error payloads. Use when writing Spring exception handler tests, REST API error tests, or mocking controller advice.
4allowed-tools: Read, Write, Bash, Glob, Grep
5metadata:
6 source: https://skillmd.com/skills/giuseppe-trisciuoglio/unit-test-exception-handler
7---
8
9# Unit Testing ExceptionHandler and ControllerAdvice
10
11## Overview
12
13This skill provides patterns for writing unit tests for Spring Boot exception handlers. It covers testing `@ExceptionHandler` methods in `@ControllerAdvice` classes using MockMvc, including HTTP status assertions, JSON response validation, field-level validation error testing, and mocking handler dependencies.
14
15## When to Use
16
17- Writing unit tests for `@ExceptionHandler` methods
18- Testing `@ControllerAdvice` global exception handling
19- Validating REST API error response formatting
20- Mocking exceptions in controller tests
21- Testing field-level validation error responses
22- Asserting custom error payloads and HTTP status codes
23
24## Instructions
25
261. **Create a test controller** that throws specific exceptions to trigger each `@ExceptionHandler`
272. **Register ControllerAdvice** via `setControllerAdvice()` on `MockMvcBuilders.standaloneSetup()`
283. **Assert HTTP status codes** with `.andExpect(status().isXxx())`
294. **Verify error response fields** using `jsonPath("$.field")` matchers
305. **Test validation errors** by sending invalid payloads and checking `MethodArgumentNotValidException` produces field-level details
316. **Debug failures** with `.andDo(print())` — if handler not invoked, verify `setControllerAdvice()` is called and exception type matches
32
33## Examples
34
35### Exception Handler and Error DTO
36
37```java
38@ControllerAdvice
39public class GlobalExceptionHandler {
40
41 @ExceptionHandler(ResourceNotFoundException.class)
42 @ResponseStatus(HttpStatus.NOT_FOUND)
43 public ErrorResponse handleNotFound(ResourceNotFoundException ex) {
44 return new ErrorResponse(404, "Not Found", ex.getMessage());
45 }
46
47 @ExceptionHandler(ValidationException.class)
48 @ResponseStatus(HttpStatus.BAD_REQUEST)
49 public ErrorResponse handleValidation(ValidationException ex) {
50 return new ErrorResponse(400, "Bad Request", ex.getMessage());
51 }
52
53 @ExceptionHandler(MethodArgumentNotValidException.class)
54 @ResponseStatus(HttpStatus.BAD_REQUEST)
55 public ValidationErrorResponse handleMethodArgumentNotValid(MethodArgumentNotValidException ex) {
56 Map<String, String> errors = new HashMap<>();
57 ex.getBindingResult().getFieldErrors().forEach(e -> errors.put(e.getField(), e.getDefaultMessage()));
58 return new ValidationErrorResponse(400, "Validation Failed", errors);
59 }
60}
61
62public record ErrorResponse(int status, String error, String message) {}
63public record ValidationErrorResponse(int status, String error, Map<String, String> errors) {}
64```
65
66### Unit Test
67
68```java
69@ExtendWith(MockitoExtension.class)
70class GlobalExceptionHandlerTest {
71
72 private MockMvc mockMvc;
73
74 @BeforeEach
75 void setUp() {
76 GlobalExceptionHandler handler = new GlobalExceptionHandler();
77 mockMvc = MockMvcBuilders.standaloneSetup(new TestController())
78 .setControllerAdvice(handler)
79 .build();
80 }
81
82 @Test
83 void shouldReturn404WhenResourceNotFound() throws Exception {
84 mockMvc.perform(get("/api/users/999"))
85 .andExpect(status().isNotFound())
86 .andExpect(jsonPath("$.status").value(404))
87 .andExpect(jsonPath("$.error").value("Not Found"))
88 .andExpect(jsonPath("$.message").value("User not found"));
89 }
90
91 @Test
92 void shouldReturn400WithFieldErrorsOnValidationFailure() throws Exception {
93 mockMvc.perform(post("/api/users")
94 .contentType("application/json")
95 .content("{\"name\":\"\",\"email\":\"invalid\"}"))
96 .andExpect(status().isBadRequest())
97 .andExpect(jsonPath("$.status").value(400))
98 .andExpect(jsonPath("$.errors.name").value("must not be blank"))
99 .andExpect(jsonPath("$.errors.email").value("must be a valid email"));
100 }
101}
102
103@RestController
104@RequestMapping("/api")
105class TestController {
106 @GetMapping("/users/{id}") public User getUser(@PathVariable Long id) {
107 throw new ResourceNotFoundException("User not found");
108 }
109 @PostMapping("/users") public User createUser(@RequestBody @Valid User user) {
110 throw new ValidationException("Validation failed");
111 }
112}
113```
114
115## Best Practices
116
117- Test each `@ExceptionHandler` method independently with a dedicated exception throw
118- Register exactly one `@ControllerAdvice` instance via `setControllerAdvice()` — never skip it
119- Assert all fields in the error response body, not just the HTTP status
120- For validation errors, verify both the field name key and the error message value
121- Use `MockMvcBuilders.standaloneSetup()` for isolated handler tests without full Spring context
122- Log assertion failures: chain `.andDo(print())` to print request/response when a test fails
123
124## Common Pitfalls
125
126- Handler not invoked: ensure `setControllerAdvice()` is called on the builder
127- JsonPath mismatch: use `.andDo(print())` to inspect actual response structure
128- Status is 200: missing `@ResponseStatus` on the handler method
129- Duplicate handlers: `@Order` controls precedence; more specific exception types take priority
130- Testing handler logic instead of behavior: mock external dependencies, test only the response transformation
131
132## Constraints and Warnings
133
134- **`@ExceptionHandler` specificity**: more specific exception types are matched first; `Exception.class` catches all unmatched types
135- **`@ResponseStatus` default**: without `@ResponseStatus` or returning `ResponseEntity`, HTTP status defaults to 200
136- **Global vs local scope**: `@ExceptionHandler` in `@ControllerAdvice` is global; declared in a controller it is local only to that controller
137- **Logging side effects**: handlers that log should be verified with `verify(mockLogger).logXxx(...)`
138- **Localization**: when using `MessageSource`, test with different `Locale` values to confirm message resolution
139- **Security context**: `AuthorizationException` handlers can access `SecurityContextHolder` — test that context is correctly evaluated