unit-test-mapper-converter_skill

Overview

This skill provides practical, focused patterns for unit testing mappers and converters (MapStruct and custom converters). It helps validate field mapping, null handling, nested transformations, enum mappings, type conversions, bidirectional consistency, and partial updates in isolation. Use it to catch mapping defects early without spinning up integration layers.

How this skill works

The skill describes concrete unit-test patterns: obtain mapper instances with Mappers.getMapper() for standalone tests, assert field-level mappings, and use recursive comparison for nested structures. It covers tests for nulls, enums, custom expressions, type converters, round-trip mapping, and partial updates using @MappingTarget. Examples use JUnit 5 and AssertJ and include Maven/Gradle setup notes.

When to use it

• When verifying MapStruct-generated mappers in unit tests
• When testing custom converter classes (date/time, formatting, parsing)
• When validating nested object and collection transformations
• When confirming null handling and null-aware mapping strategies
• When checking enum/value mapping and custom expression logic
• Before integration tests to ensure mapping correctness in isolation

Best practices

• Test every public mapper method and both directions where applicable
• Use Mappers.getMapper() for non-Spring standalone tests to avoid DI complexity
• Assert null and edge cases (null inputs, empty collections, invalid formats) explicitly
• Use assertThat().usingRecursiveComparison() for complex nested objects
• Write focused tests for custom expressions and converters to isolate logic
• Keep tests deterministic: avoid relying on generated code side effects or runtime environment

Example use cases

• Unit test that entity→DTO mapping maps each field and nested address correctly
• Verify DTO→entity reverse mapping preserves values in a round-trip test
• Test custom date formatter parse/format methods and invalid input handling
• Validate @ValueMapping enum translations between domain and DTO enums
• Check updateEntity(@MappingTarget) only changes intended fields and respects null-aware strategies
• Test list mapping and collection immutability behavior for mapped collections