unit-test-exception-handler

name	unit-test-exception-handler
description	Unit tests for @ExceptionHandler and @ControllerAdvice for global exception handling. Use when validating error response formatting and HTTP status codes.
category	testing
tags	["junit-5","exception-handler","controller-advice","error-handling","mockmvc"]
version	1.0.1

Unit Testing ExceptionHandler and ControllerAdvice

Test exception handlers and global exception handling logic using MockMvc. Verify error response formatting, HTTP status codes, and exception-to-response mapping.

When to Use This Skill

Use this skill when:

• Testing @ExceptionHandler methods in @ControllerAdvice
• Testing exception-to-error-response transformations
• Verifying HTTP status codes for different exception types
• Testing error message formatting and localization
• Want fast exception handler tests without full integration tests

Setup: Exception Handler Testing

Maven

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <scope>test</scope>
</dependency>

Gradle

dependencies {
  implementation("org.springframework.boot:spring-boot-starter-web")
  testImplementation("org.springframework.boot:spring-boot-starter-test")
  testImplementation("org.assertj:assertj-core")
}

Basic Pattern: Global Exception Handler

Create Exception Handler

// Global exception handler
@ControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(ResourceNotFoundException.class)
  @ResponseStatus(HttpStatus.NOT_FOUND)
  public ErrorResponse handleResourceNotFound(ResourceNotFoundException ex) {
    return new ErrorResponse(
      HttpStatus.NOT_FOUND.value(),
      "Resource not found",
      ex.getMessage()
    );
  }

  @ExceptionHandler(ValidationException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  public ErrorResponse handleValidationException(ValidationException ex) {
    return new ErrorResponse(
      HttpStatus.BAD_REQUEST.value(),
      "Validation failed",
      ex.getMessage()
    );
  }
}

// Error response DTO
public record ErrorResponse(
  int status,
  String error,
  String message
) {}

Unit Test Exception Handler

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@ExtendWith(MockitoExtension.class)
class GlobalExceptionHandlerTest {

  @InjectMocks
  private GlobalExceptionHandler exceptionHandler;

  private MockMvc mockMvc;

  @BeforeEach
  void setUp() {
    mockMvc = MockMvcBuilders
      .standaloneSetup(new TestController())
      .setControllerAdvice(exceptionHandler)
      .build();
  }

  @Test
  void shouldReturnNotFoundWhenResourceNotFoundException() throws Exception {
    mockMvc.perform(get("/api/users/999"))
      .andExpect(status().isNotFound())
      .andExpect(jsonPath("$.status").value(404))
      .andExpect(jsonPath("$.error").value("Resource not found"))
      .andExpect(jsonPath("$.message").value("User not found"));
  }

  @Test
  void shouldReturnBadRequestWhenValidationException() throws Exception {
    mockMvc.perform(post("/api/users")
        .contentType()
        .content())
      .andExpect(status().isBadRequest())
      .andExpect(jsonPath().value())
      .andExpect(jsonPath().value());
  }
}




  {

  
   User  {
      ();
  }
}

Testing Multiple Exception Types

Handle Various Exception Types

@ControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(ResourceNotFoundException.class)
  @ResponseStatus(HttpStatus.NOT_FOUND)
  public ErrorResponse handleResourceNotFound(ResourceNotFoundException ex) {
    return new ErrorResponse(404, "Not found", ex.getMessage());
  }

  @ExceptionHandler(DuplicateResourceException.class)
  @ResponseStatus(HttpStatus.CONFLICT)
  public ErrorResponse handleDuplicateResource(DuplicateResourceException ex) {
    return new ErrorResponse(409, "Conflict", ex.getMessage());
  }

  @ExceptionHandler(UnauthorizedException.class)
  @ResponseStatus(HttpStatus.UNAUTHORIZED)
  public ErrorResponse handleUnauthorized(UnauthorizedException ex) {
    return new ErrorResponse(401, "Unauthorized", ex.getMessage());
  }

  @ExceptionHandler(AccessDeniedException.class)
  @ResponseStatus(HttpStatus.FORBIDDEN)
  public ErrorResponse handleAccessDenied(AccessDeniedException ex) {
    return new ErrorResponse(403, "Forbidden", ex.getMessage());
  }

  @ExceptionHandler(Exception.class)
  
   ErrorResponse  {
      (, , );
  }
}

  {

   MockMvc mockMvc;
   GlobalExceptionHandler handler;

  
    {
    handler =  ();
    mockMvc = MockMvcBuilders
      .standaloneSetup( ())
      .setControllerAdvice(handler)
      .build();
  }

  
     Exception {
    mockMvc.perform(get())
      .andExpect(status().isNotFound())
      .andExpect(jsonPath().value());
  }

  
     Exception {
    mockMvc.perform(post()
        .contentType()
        .content())
      .andExpect(status().isConflict())
      .andExpect(jsonPath().value());
  }

  
     Exception {
    mockMvc.perform(get())
      .andExpect(status().isUnauthorized())
      .andExpect(jsonPath().value());
  }

  
     Exception {
    mockMvc.perform(get())
      .andExpect(status().isForbidden())
      .andExpect(jsonPath().value());
  }

  
     Exception {
    mockMvc.perform(get())
      .andExpect(status().isInternalServerError())
      .andExpect(jsonPath().value());
  }
}

Testing Error Response Structure

Verify Error Response Format

@ControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(BadRequestException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  public ResponseEntity<ErrorDetails> handleBadRequest(BadRequestException ex) {
    ErrorDetails details = new ErrorDetails(
      System.currentTimeMillis(),
      HttpStatus.BAD_REQUEST.value(),
      "Bad Request",
      ex.getMessage(),
      new Date()
    );
    return new ResponseEntity<>(details, HttpStatus.BAD_REQUEST);
  }
}

class ErrorResponseStructureTest {

  private MockMvc mockMvc;

  @BeforeEach
  void setUp() {
    mockMvc = MockMvcBuilders
      .standaloneSetup(new TestController())
      .setControllerAdvice(new GlobalExceptionHandler())
      .build();
  }

  @Test
  void shouldIncludeTimestampInErrorResponse() throws Exception {
    mockMvc.perform(post("/api/data")
        .contentType("application/json")
        .content("{}"))
      .andExpect(status().isBadRequest())
      .andExpect(jsonPath("$.timestamp").exists())
      .andExpect(jsonPath("$.status").value(400))
      .andExpect(jsonPath("$.error").value())
      .andExpect(jsonPath().exists())
      .andExpect(jsonPath().exists());
  }

  
     Exception {
       mockMvc.perform(get())
      .andExpect(status().isBadRequest())
      .andReturn();

       result.getResponse().getContentAsString();
    
    assertThat(response).contains();
    assertThat(response).contains();
    assertThat(response).contains();
    assertThat(response).contains();
  }
}

Testing Validation Error Handling

Handle MethodArgumentNotValidException

@ControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(MethodArgumentNotValidException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  public ValidationErrorResponse handleValidationException(
    MethodArgumentNotValidException ex) {
    
    Map<String, String> errors = new HashMap<>();
    ex.getBindingResult().getFieldErrors().forEach(error ->
      errors.put(error.getField(), error.getDefaultMessage())
    );

    return new ValidationErrorResponse(
      HttpStatus.BAD_REQUEST.value(),
      "Validation failed",
      errors
    );
  }
}

class ValidationExceptionHandlerTest {

  private MockMvc mockMvc;

  @BeforeEach
  void setUp() {
    mockMvc = MockMvcBuilders
      .standaloneSetup(new UserController())
      .setControllerAdvice(new GlobalExceptionHandler())
      .build();
  }

  @Test
  void shouldReturnValidationErrorsForInvalidInput() throws Exception {
    mockMvc.perform(post("/api/users")
        .contentType("application/json")
        .content("{\"name\":\"\",\"age\":-5}"))
      .andExpect(status().isBadRequest())
      .andExpect(jsonPath("$.status").value(400))
      .andExpect(jsonPath("$.errors.name").exists())
      .andExpect(jsonPath("$.errors.age").exists());
  }

  @Test
  void   Exception {
    mockMvc.perform(post()
        .contentType()
        .content())
      .andExpect(status().isBadRequest())
      .andExpect(jsonPath().value())
      .andExpect(jsonPath().value());
  }
}

Testing Exception Handler with Custom Logic

Exception Handler with Context

@ControllerAdvice
public class GlobalExceptionHandler {

  private final MessageService messageService;
  private final LoggingService loggingService;

  public GlobalExceptionHandler(MessageService messageService, LoggingService loggingService) {
    this.messageService = messageService;
    this.loggingService = loggingService;
  }

  @ExceptionHandler(BusinessException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  public ErrorResponse handleBusinessException(BusinessException ex, HttpServletRequest request) {
    loggingService.logException(ex, request.getRequestURI());
    
    String localizedMessage = messageService.getMessage(ex.getErrorCode());
    return new ErrorResponse(
      HttpStatus.BAD_REQUEST.value(),
      "Business error",
      localizedMessage
    );
  }
}

class ExceptionHandlerWithContextTest {

  private MockMvc mockMvc;
  private GlobalExceptionHandler handler;
  private MessageService messageService;
  private LoggingService loggingService;

  @BeforeEach
  void setUp() {
    messageService = mock(MessageService.class);
    loggingService = mock(LoggingService.class);
    handler = new GlobalExceptionHandler(messageService, loggingService);
    
    mockMvc = MockMvcBuilders
      .standaloneSetup(new TestController())
      .setControllerAdvice(handler)
      .build();
  }

  
     Exception {
    (messageService.getMessage())
      .thenReturn();

    mockMvc.perform(get())
      .andExpect(status().isBadRequest())
      .andExpect(jsonPath().value());

    verify(messageService).getMessage();
  }

  
     Exception {
    mockMvc.perform(get())
      .andExpect(status().isBadRequest());

    verify(loggingService).logException(any(BusinessException.class), anyString());
  }
}

Best Practices

• Test all exception handlers with real exception throws
• Verify HTTP status codes for each exception type
• Test error response structure to ensure consistency
• Verify logging is triggered appropriately
• Use mock controllers to throw exceptions in tests
• Test both happy and error paths
• Keep error messages user-friendly and consistent

Common Pitfalls

• Not testing the full request path (use MockMvc with controller)
• Forgetting to include @ControllerAdvice in MockMvc setup
• Not verifying all required fields in error response
• Testing handler logic instead of exception handling behavior
• Not testing edge cases (null exceptions, unusual messages)

Troubleshooting

Exception handler not invoked: Ensure controller is registered with MockMvc and actually throws the exception.

JsonPath matchers not matching: Use .andDo(print()) to see actual response structure.

Status code mismatch: Verify @ResponseStatus annotation on handler method.

References

• Spring ControllerAdvice Documentation
• Spring ExceptionHandler
• MockMvc Testing