ExceptionHandler と ControllerAdvice のユニットテスト

概要

このスキルは Spring Boot 例外ハンドラのユニットテストを書くためのパターンを提供します。MockMvc を使用した @ControllerAdvice クラス内の @ExceptionHandler メソッドのテスト、HTTP ステータスのアサーション、JSON レスポンス検証、フィールドレベルの検証エラーテスト、およびハンドラ依存関係のモック化に対応します。

使用する場合

• @ExceptionHandler メソッドのユニットテストを書く場合
• @ControllerAdvice グローバル例外処理をテストする場合
• REST API エラーレスポンスのフォーマットを検証する場合
• コントローラテストで例外をモック化する場合
• フィールドレベルの検証エラーレスポンスをテストする場合
• カスタムエラーペイロードと HTTP ステータスコードをアサートする場合

手順

1. テストコントローラを作成 して各 @ExceptionHandler をトリガーする特定の例外をスロー
2. ControllerAdvice を登録 - MockMvcBuilders.standaloneSetup() 上で setControllerAdvice() を使用
3. HTTP ステータスコードをアサート - .andExpect(status().isXxx()) で確認
4. エラーレスポンスフィールドを検証 - jsonPath("$.field") マッチャーを使用
5. 検証エラーをテスト - 無効なペイロードを送信して MethodArgumentNotValidException がフィールドレベルの詳細を生成することを確認
6. 失敗をデバッグ - .andDo(print()) を使用 — ハンドラが呼び出されない場合は setControllerAdvice() が呼ばれていること、例外タイプがマッチしていることを確認

例

例外ハンドラとエラー 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) {}

ユニットテスト

@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");
  }
}

ベストプラクティス

• 各 @ExceptionHandler メソッドを独立してテスト - 特定の例外をスロー
• setControllerAdvice() を使用して正確に 1 つの @ControllerAdvice インスタンスを登録 — スキップしないこと
• HTTP ステータスだけでなく、エラーレスポンス本体のすべてのフィールドをアサート
• 検証エラーについては、フィールド名キーとエラーメッセージの値の両方を検証
• MockMvcBuilders.standaloneSetup() を使用 - 完全な Spring コンテキストなしで、隔離されたハンドラテストの場合
• アサーション失敗をログに記録 - .andDo(print()) をチェーンして、テスト失敗時に要求/レスポンスを出力

よくある落とし穴

• ハンドラが呼び出されない: ビルダー上で setControllerAdvice() が呼ばれていることを確認
• JsonPath 不一致: .andDo(print()) を使用して、実際のレスポンス構造を検査
• ステータスが 200: ハンドラメソッドに @ResponseStatus がないか、ResponseEntity を返していない
• ハンドラの重複: @Order が優先度を制御します；より具体的な例外タイプが優先される
• ハンドラロジックをテスト: 外部依存関係をモック化し、レスポンス変換のみをテスト

制約と警告

• @ExceptionHandler の具体性: より具体的な例外タイプがまず最初にマッチされます；Exception.class はマッチしないすべてのタイプをキャッチ
• @ResponseStatus のデフォルト: @ResponseStatus または ResponseEntity を返さない場合、HTTP ステータスはデフォルトで 200
• グローバル vs ローカルスコープ: @ControllerAdvice 内の @ExceptionHandler はグローバル；コントローラで宣言された場合、そのコントローラのみにローカル
• ロギング副作用: ハンドラがログを記録する場合、verify(mockLogger).logXxx(...) で検証する必要があります
• ローカライゼーション: MessageSource を使用する場合、異なる Locale 値でテストしてメッセージ解決を確認
• セキュリティコンテキスト: AuthorizationException ハンドラは SecurityContextHolder にアクセス可能 — コンテキストが正しく評価されることをテスト