unit-test-mapper-converter

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

概要

MapStruct のマッパーとカスタムコンバータークラスをユニットテストするためのパターンを紹介します。フィールドマッピングの正確性、null の処理、型変換、ネストされたオブジェクトの変換、双方向マッピング、列挙型マッピング、部分更新を扱います。

使用する場面

• 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. 列挙型マッピングをテストする

列挙型から列挙型への変換には @ValueMapping を使用します。すべての列挙値を漏れなくテストします。

ベストプラクティス

• 単独のテストには Mappers.getMapper() を使用し、統合テストには Spring のインジェクションを使用します
• 複雑なネスト構造には usingRecursiveComparison() を使用します
• コレクション変換を含む、すべてのマッパーメソッドをテストします
• null 許容のすべてのソースフィールドについて、null の処理を検証します
• 双方向マッピングをテストして、エンティティ→DTO と DTO→エンティティ間の非対称性を検出します
• マッパーテストは、実装の詳細ではなく変換の正確性に焦点を絞ります

制約と警告

• コンパイル時の生成：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", "[email protected]", 25);
    UserDto dto = mapper.toDto(user);
    assertThat(dto)
      .isNotNull()
      .extracting(UserDto::getName, UserDto::getEmail)
      .containsExactly("Alice", "[email protected]");
  }

  @Test
  void shouldMaintainRoundTrip() {
    User original = new User(1L, "Alice", "[email protected]", 25);
    assertThat(mapper.toEntity(mapper.toDto(original)))
      .usingRecursiveComparison()
      .isEqualTo(original);
  }

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

その他の例：references/examples.md