unit-test-mapper-converter

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:

# 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

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

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

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