giuseppe-trisciuoglio/developer-kit

unit-test-mapper-converter

Provides patterns for unit testing mappers, converters, and bean mappings.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-mapper-converter

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Unit Testing Mappers and Converters

Overview

Provides patterns for unit testing MapStruct mappers and custom converter classes. Covers field mapping accuracy, null handling, type conversions, nested object transformations, bidirectional mapping, enum mapping, and partial updates.

When to Use

  • Writing mapping tests for MapStruct mapper implementations
  • Testing custom entity-to-DTO converters and bean mappings
  • Validating nested object mapping and collection transformations

Instructions

1. Validate Generated Mapper Classes

Before testing, verify generated mapper classes exist:

bash
# Maven
ls target/generated-sources/

# Gradle
ls build/generated/sources/

If generated classes are missing:

  1. Run mvn compile (Maven) or ./gradlew compileJava (Gradle)
  2. Check that the MapStruct annotation processor is configured
  3. Verify @Mapper interfaces are in a compiled source set

2. Test Null Handling

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

Configure nullValueMappingStrategy in mapper if null should return empty/default.

If null tests fail:

  1. Add nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL to @Mapper
  2. Or use nullValuePropertyMappingStrategy for nested property handling

3. Test Bidirectional Mapping

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

If bidirectional tests fail:

  1. Check @Mapping annotations for field name mismatches
  2. Verify both directions are explicitly mapped if auto-mapping fails
  3. Use unmappedTargetPolicy = ReportingPolicy.ERROR to catch missing mappings

4. Test Nested Object Mapping

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

If nested tests fail:

  1. Ensure nested mapper exists or is referenced via uses = NestedMapper.class
  2. Check collection element mappings with elementMappingStrategy

5. Test Custom Expressions

Custom expressions in @Mapping(target = "field", expression = "java(...)") are not compile-time validated.

If expression tests fail:

  1. Verify the expression syntax and method signatures
  2. Check that imported classes are accessible from the expression context

6. Test Enum Mappings

Use @ValueMapping for enum-to-enum translations. Test all enum values exhaustively.

Best Practices

  • Use Mappers.getMapper() for standalone tests, Spring injection for integration tests
  • Use usingRecursiveComparison() for complex nested structures
  • Test all mapper methods including collection transformations
  • Verify null handling for all nullable source fields
  • Test bidirectional mapping catches asymmetries between entity→DTO and DTO→entity
  • Keep mapper tests focused on transformation correctness, not implementation details

Constraints and Warnings

  • Compile-time generation: MapStruct generates code at compile time—verify generated classes exist before running tests
  • Null handling: Configure nullValueMappingStrategy and nullValuePropertyMappingStrategy appropriately
  • Expression validation: Expressions in @Mapping are not validated at compile time—test them explicitly
  • Circular dependencies: MapStruct cannot handle circular dependencies between mappers
  • Collection immutability: Mapping immutable collections may require special configuration
  • Date/Time: Verify date/time objects map correctly across timezones

Examples

Complete executable test with imports:

java
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();
  }
}

Additional examples in: references/examples.md

タスクに関連する項目

同じリポジトリから

関連する Skills

すべての Skills
giuseppe-trisciuoglio
コミュニティ

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

1時間の導入数
2
GitHub Stars
372
更新日
9月10日
giuseppe-trisciuoglio
コミュニティ

adr-drafting

Creates new Architecture Decision Record (ADR) documents for significant architectural changes using a consistent template and repository-aware naming and storage guidance. Use when a user or agent decides on an architectural change, needs to document technical rationale, or wants to add a new ADR to the project history.

1時間の導入数
1
GitHub Stars
372
更新日
9月10日
giuseppe-trisciuoglio
コミュニティ

clean-architecture

Provides implementation patterns for Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design in PHP 8.3+ with Symfony 7.x. Use when architecting enterprise PHP applications with entities/value objects/aggregates, refactoring legacy code to modern patterns, implementing domain-driven design with Symfony, or creating testable backends with clear separation of concerns.

1時間の導入数
1
GitHub Stars
372
更新日
9月10日
giuseppe-trisciuoglio
コミュニティ

langchain4j-spring-boot-integration

Provides integration patterns for LangChain4j with Spring Boot. Configures AI model beans, sets up chat memory with Spring context, integrates RAG pipelines with Spring Data, and handles auto-configuration, dependency injection, and Spring ecosystem integration. Use when embedding LangChain4j into Spring Boot applications, building Java LLM applications with @Bean configuration, or setting up Spring AI patterns.

1時間の導入数
1
GitHub Stars
372
更新日
9月10日