Skip to content
Skills Library
Programming · Testing

unit-test-exception-handler

/unit-test-exception-handler

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.

Licence
MIT
Last repository change
10.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author description

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.

How it works

  1. Overview
  2. When to Use
  3. Instructions
  4. Examples
  5. Best Practices
  6. Common Pitfalls
  7. Constraints and Warnings
Original SKILL.md headings · 133 lines, 578 words
SKILL.md preview
---
name: unit-test-exception-handler
description: 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.
allowed-tools: Read, Write, Bash, Glob, Grep
---

# 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

1. **Create a test controller** that throws specific exceptions to trigger each `@ExceptionHandler`
2. **Register ControllerAdvice** via `setControllerAdvice()` on `MockMvcBuilders.standaloneSetup()`
3. **Assert HTTP status codes** with `.andExpect(status().isXxx())`
4. **Verify error response fields** using `jsonPath("$.field")` matchers
5. **Test validation errors** by sending invalid payloads and checking `MethodArgumentNotValidException` produces field-level details
6. **Debug failures** with `.andDo(print())` — if handler not invoked, verify `setControllerAdvice()` is called and exception type matches

## Examples

### Exception Handler and Error DTO

```java
@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

```java
@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
Files in this package (2)
  • SKILL.md 6 KB
  • references/examples.md 3 KB

Versions

The database has no other skills named unit-test-exception-handler.

Database snapshot: 13.11.2026 · package version 2d60fdbb8032 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100unit-test-controller-layer
    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…
  • 100spring-boot-testing
    Write unit, integration, and slice tests for Spring Boot 3 applications. Use when writing unit tests, integration tests, or slice tests for Spring Boot 3 applications.
  • 100unit-test-config-properties
    Provides patterns for unit testing `@ConfigurationProperties` classes with `@ConfigurationPropertiesTest`. Validates property binding, tests validation constraints, verifies default values, checks type conversions, and mocks property sources for Spring Boot configuration…
  • 100problem-details-rfc9457
    Use when generating error responses, exception listeners, or custom exceptions in a Symfony API. Defines RFC 9457 (problem+json) error format, mapping domain exceptions to HTTP status codes, and a single kernel exception listener. Use when the task mentions error handling,…
  • 95backend-spring-web
    Use when reviewing Spring MVC / WebFlux controllers — `@RestController` patterns, dependency injection style, `@Valid`, `@ExceptionHandler`/`@ControllerAdvice`, `ResponseEntity`, request mapping clarity. Triggers when controllers are in scope and Spring Boot web/webflux is detected.
  • 100spring-rest
    Spring REST Controller patterns. Covers ResponseEntity, exception handling, validation, HATEOAS, content negotiation, and async controllers. USE WHEN: user mentions "spring rest", "@RestController", "ResponseEntity", "REST API Spring", "exception handling Spring",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.