Provides patterns for unit testing mappers, converters, and bean mappings. Validates entity-to-DTO and model transformation logic in isolation. Generates executable mapping tests with MapStruct and custom converter test coverage. Use when writing mapping tests, converter tests, entity mapping tests, or ensuring correct data transformation between DTOs and domain objects.
This skill provides patterns for unit testing MapStruct mappers and custom converter classes in Java. It solves the problem of verifying data transformation correctness — entity-to-DTO mapping, null handling, type conversion, nested objects, bidirectional round trips, and enum mapping — in isolated, executable tests.
The guidance begins by verifying that MapStruct's compile-time generated mapper classes exist before testing, with fallback steps to run compilation and check the annotation processor. It then covers testing null handling and configuring nullValueMappingStrategy, bidirectional round-trip mapping using usingRecursiveComparison, nested object and collection mapping via referenced mappers, custom @Mapping expressions that are not compile-time validated, and exhaustive enum-to-enum @ValueMapping tests. A best-practices section recommends Mappers.getMapper for standalone tests and Spring injection for integration tests, plus focusing tests on transformation correctness. Constraints call out compile-time generation, circular dependency limits, collection immutability, and date/time timezone handling. Reference examples include basic mappers, nested and list mapping, custom field-name and expression mapping, enum mapping, a custom date formatter/converter, and partial update mapping.
It targets Java developers using MapStruct for DTO and domain-object mapping who want reliable regression coverage of their transformation layer. It fits teams standardizing mapping tests across a codebase.
MapStruct (version 1.5.5.Final in the examples), plus custom hand-written converter classes.
MapStruct generates mapper implementations at compile time; the skill has you verify the generated sources exist and, if missing, run compilation and check the annotation processor configuration.
By mapping an entity to a DTO and back, then comparing with usingRecursiveComparison to catch asymmetries between the two directions.
Yes, and the skill warns that expressions in @Mapping are not validated at compile time, so they must be tested explicitly.
MapStruct cannot handle circular dependencies between mappers, mapping immutable collections may need special configuration, and date/time mapping should be verified across timezones.
Quick Setup:
.claude/skills/Repository
giuseppe-trisciuoglio/developer-kit