マッパーとコンバーターのユニットテスト

概要

MapStruct マッパーとカスタムコンバータークラスのユニットテストパターンを提供します。フィールドマッピングの正確性、null ハンドリング、型変換、ネストされたオブジェクト変換、双方向マッピング、enum マッピング、部分更新に対応しています。

使用時期

• MapStruct マッパー実装のマッピングテストを作成する場合
• カスタムエンティティから DTO へのコンバーターと Bean マッピングをテストする場合
• ネストされたオブジェクトマッピングとコレクション変換を検証する場合

手順

1. 生成されたマッパークラスを検証する

テストの前に、生成されたマッパークラスが存在することを確認してください：

# Maven
ls target/generated-sources/

# Gradle
ls build/generated/sources/

生成されたクラスが見つからない場合：

1. mvn compile（Maven）または ./gradlew compileJava（Gradle）を実行する
2. MapStruct アノテーションプロセッサが設定されていることを確認する
3. @Mapper インターフェースがコンパイル済みソースセットにあることを確認する

2. Null ハンドリングをテストする

assertThat(mapper.toDto(null)).isNull();

null が空またはデフォルト値を返す場合は、マッパーで nullValueMappingStrategy を設定してください。

null テストが失敗する場合：

1. @Mapper に nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL を追加する
2. またはネストされたプロパティハンドリングに nullValuePropertyMappingStrategy を使用する

3. 双方向マッピングをテストする

User restored = mapper.toEntity(mapper.toDto(original));
assertThat(restored).usingRecursiveComparison().isEqualTo(original);

双方向マッピングテストが失敗する場合：

1. @Mapping アノテーションのフィールド名の不一致を確認する
2. 自動マッピングが失敗する場合は両方向を明示的にマッピングされていることを確認する
3. unmappedTargetPolicy = ReportingPolicy.ERROR を使用して不足しているマッピングを検出する

4. ネストされたオブジェクトマッピングをテストする

assertThat(dto.getNested()).usingRecursiveComparison().isEqualTo(expected);

ネストされたテストが失敗する場合：

1. ネストされたマッパーが存在すること、または uses = NestedMapper.class で参照されていることを確認する
2. elementMappingStrategy でコレクション要素マッピングを確認する

5. カスタム式をテストする

@Mapping(target = "field", expression = "java(...)") のカスタム式はコンパイル時に検証されません。

式テストが失敗する場合：

1. 式の構文とメソッドシグネチャを確認する
2. インポートされたクラスが式コンテキストからアクセス可能なことを確認する

6. Enum マッピングをテストする

enum から enum への変換には @ValueMapping を使用します。すべての enum 値を徹底的にテストしてください。

ベストプラクティス

• スタンドアロンテストには Mappers.getMapper() を使用し、統合テストには Spring インジェクションを使用する
• 複雑なネストされた構造には usingRecursiveComparison() を使用する
• コレクション変換を含むすべてのマッパーメソッドをテストする
• すべての nullable ソースフィールドの null ハンドリングを検証する
• 双方向マッピングテストは entity→DTO と DTO→entity の間の非対称性を検出する
• マッパーテストを変換の正確性に焦点を当て、実装詳細ではなく保つ

制約と警告

• コンパイル時生成: MapStruct はコンパイル時にコードを生成します。テスト実行前に生成されたクラスが存在することを確認してください
• Null ハンドリング: nullValueMappingStrategy と nullValuePropertyMappingStrategy を適切に設定してください
• 式の検証: @Mapping の式はコンパイル時に検証されません。明示的にテストしてください
• 循環依存: MapStruct はマッパー間の循環依存を処理できません
• コレクション不変性: 不変コレクションのマッピングは特別な設定が必要な場合があります
• 日付/時刻: 日付/時刻オブジェクトがタイムゾーン間で正しくマッピングされることを確認してください

例

インポート付きの完全な実行可能テスト：

package com.example.mapper;

import org.junit.jupiter.api.Test;
import org.mapstruct.factory.Mappers;
import static org.assertj.core.api.Assertions.*;

class UserMapperCompleteTest {
  private final UserMapper mapper = Mappers.getMapper(UserMapper.class);

  @Test
  void shouldMapUserToDto() {
    User user = new User(1L, "Alice", "alice@example.com", 25);
    UserDto dto = mapper.toDto(user);
    assertThat(dto)
      .isNotNull()
      .extracting(UserDto::getName, UserDto::getEmail)
      .containsExactly("Alice", "alice@example.com");
  }

  @Test
  void shouldMaintainRoundTrip() {
    User original = new User(1L, "Alice", "alice@example.com", 25);
    assertThat(mapper.toEntity(mapper.toDto(original)))
      .usingRecursiveComparison()
      .isEqualTo(original);
  }

  @Test
  void shouldHandleNullInput() {
    assertThat(mapper.toDto(null)).isNull();
  }
}

その他の例は references/examples.md を参照してください