Jakarta Bean Validation のユニットテスト

概要

このスキルは、JUnit 5 を使用した Jakarta Bean Validation アノテーションとカスタムバリデータのユニットテスト用の実行可能なパターンを提供します。組み込み制約（@NotNull、@Email、@Min、@Max、@Size）、カスタム @Constraint 実装、クロスフィールドバリデーション、バリデーショングループに対応。テストは Spring コンテキストなしで独立して実行されます。

使用場面

• Jakarta Bean Validation または JSR-380 制約のユニットテストを作成する場合
• カスタム @Constraint バリデータと制約違反メッセージをテストする場合
• DTO およびリクエストオブジェクト内のBean バリデーションロジックをテストする場合
• クロスフィールドバリデーション（例：パスワードの一致確認）を検証する場合
• バリデーショングループを使用した条件付きバリデーションをテストする場合
• Spring Boot コンテキストなしで高速なバリデーションテストを実行する場合

手順

1. 依存関係を追加: テストスコープで jakarta.validation-api と hibernate-validator を含める
2. 基本テストクラスを作成: @BeforeEach で Validation.buildDefaultValidatorFactory() を使用して Validator を一度だけビルド
3. 有効なケースをテストする: 制約違反なしでオブジェクトがパスすることを確認
4. 無効なケースをテストする: 制約違反に正しいプロパティパスとメッセージが含まれていることをアサート
5. 違反詳細を抽出: getPropertyPath()、getMessage()、getInvalidValue() を使用
6. カスタムバリデータをテスト: パターンについては references/custom-validators.md を参照
7. パラメータ化テストを使用: @ParameterizedTest で複数の入力を効率的にテスト
8. バリデーションテストをグループ化: 条件付きルール用にバリデーショングループを使用（references/advanced-patterns.md を参照）

例

Maven セットアップ

<dependency>
  <groupId>jakarta.validation</groupId>
  <artifactId>jakarta.validation-api</artifactId>
</dependency>
<dependency>
  <groupId>org.hibernate.validator</groupId>
  <artifactId>hibernate-validator</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <scope>test</scope>
</dependency>

共通テストセットアップ

import jakarta.validation.*;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.path.Path;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.*;

class BaseValidationTest {
  protected Validator validator;

  @BeforeEach
  void setUpValidator() {
    validator = Validation.buildDefaultValidatorFactory().getValidator();
  }
}

基本的な制約のテスト

class UserDtoTest extends BaseValidationTest {

  @Test
  void shouldPassValidationWithValidUser() {
    UserDto user = new UserDto("Alice", "alice@example.com", 25);
    assertThat(validator.validate(user)).isEmpty();
  }

  @Test
  void shouldFailWhenNameIsNull() {
    UserDto user = new UserDto(null, "alice@example.com", 25);
    assertThat(validator.validate(user))
      .extracting(ConstraintViolation::getMessage)
      .contains("must not be blank");
  }

  @Test
  void shouldFailWhenEmailIsInvalid() {
    UserDto user = new UserDto("Alice", "invalid-email", 25);
    Set<ConstraintViolation<UserDto>> violations = validator.validate(user);
    assertThat(violations)
      .extracting(ConstraintViolation::getPropertyPath)
      .extracting(Path::toString)
      .contains("email");
  }

  @Test
  void shouldFailWhenAgeIsBelowMinimum() {
    UserDto user = new UserDto("Alice", "alice@example.com", -1);
    assertThat(validator.validate(user))
      .extracting(ConstraintViolation::getMessage)
      .contains("must be greater than or equal to 0");
  }

  @Test
  void shouldFailWhenMultipleConstraintsViolated() {
    UserDto user = new UserDto(null, "invalid", -5);
    assertThat(validator.validate(user)).hasSize(3);
  }
}

カスタムバリデータのテスト

カスタム制約パターンについては、references/custom-validators.md を参照してください：

• @Constraint アノテーションの作成
• ConstraintValidator の実装
• クロスフィールドバリデーション（パスワードの一致確認）
• ステートレスバリデータのベストプラクティス

バリデーショングループのテスト

バリデーショングループとパラメータ化テストについては、references/advanced-patterns.md を参照してください：

• バリデーショングループインターフェースの定義
• groups パラメータによる条件付きバリデーション
• @ParameterizedTest と @ValueSource および @CsvSource の使用
• 失敗したバリデーションテストのデバッグ

ベストプラクティス

• 有効と無効の両方をテスト: 各制約は成功ケースと失敗ケースの両方をテストが必要
• 違反詳細をアサート: プロパティパス、メッセージ、制約タイプを検証
• エッジケースをテスト: null、空文字列、ホワイトスペースのみ、境界値
• バリデータをステートレスに保つ: カスタムバリデータは状態を保持してはいけません
• 明確なメッセージを使用: 制約メッセージはユーザーフレンドリーである必要があります
• 関連テストをグループ化: BaseValidationTest を拡張してバリデータセットアップを共有
• エラーメッセージをテスト: メッセージが要件と一致することを確認

よくある落とし穴

• null 値のテストを忘れる（ほとんどの制約はデフォルトで null を無視）
• 制約違反でプロパティパスを検証しない
• ユニットレベルではなくサービス/コントローラレベルでバリデーションをテストする
• 過度に複雑なカスタムバリデータを作成する
• 必須フィールドに対して @NotNull と他の制約の組み合わせを見逃す

制約と警告

• Null 処理: ほとんどの制約はデフォルトで null を無視します — 必須フィールドの場合は @NotNull と他の制約を組み合わせてください
• スレッドセーフ: Validator インスタンスはスレッドセーフで、共有できます
• メッセージローカライズ: i18n が必要な場合は、異なるロケールでテストしてください
• カスケードバリデーション: ネストされたオブジェクトで再帰的バリデーションを行うには @Valid を使用
• カスタムバリデータ: ステートレスである必要があり、null 値に対して true を返す必要があります
• テスト分離: バリデーションユニットテストは Spring コンテキストやデータベースに依存してはいけません

トラブルシューティング

ValidatorFactory が見つからない: jakarta.validation-api と hibernate-validator がテストクラスパス上にあることを確認してください。

カスタムバリデータが呼び出されない: @Constraint(validatedBy = YourValidator.class) アノテーションが正しいことを確認してください。

Null 値がバリデーション をパスする: これは期待される動作です — @NotNull が存在しない限り、制約は null を無視します。

違反数が間違っている: hasSize() で正確な数を検証し、オブジェクト内のすべてのフィールドをチェックしてください。

プロパティパスが正しくない: ゲッター（メソッド）ではなく、フィールドに制約アノテーションが付いていることを確認してください。

参考資料

• Jakarta Bean Validation 仕様
• Hibernate Validator
• カスタムバリデータとクロスフィールドバリデーション: references/custom-validators.md
• バリデーショングループとパラメータ化テスト: references/advanced-patterns.md