giuseppe-trisciuoglio/developer-kit

unit-test-exception-handler

Provides patterns for unit testing @ExceptionHandler and @ControllerAdvice in Spring Boot applications.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-exception-handler

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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

Tâches connexes

du même dépôt

Autres Skills

Tous les Skills
giuseppe-trisciuoglio
Communauté

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

Installations / 1h
3
GitHub Stars
372
Mis à jour
10 sept.
giuseppe-trisciuoglio
Communauté

tailwind-css-patterns

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

Installations / 1h
1
GitHub Stars
372
Mis à jour
10 sept.
giuseppe-trisciuoglio
Communauté

dynamodb-toolbox-patterns

Provides TypeScript patterns for DynamoDB-Toolbox v2 including schema/table/entity modeling, .build() command workflow, query/scan access patterns, batch and transaction operations, and single-table design with computed keys. Use when implementing type-safe DynamoDB access layers with DynamoDB-Toolbox v2 in TypeScript services or serverless applications.

Installations / 1h
1
GitHub Stars
371
Mis à jour
10 sept.
giuseppe-trisciuoglio
Communauté

spring-boot-dependency-injection

Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.

Installations / 1h
1
GitHub Stars
371
Mis à jour
10 sept.