Back to Testing & Quality Assurance
unit-test-mapper-converter
unit testingmappersconvertersMapStructJavaDTOdata transformationsoftware testing
Install this skill
npx skills add giuseppe-trisciuoglio/developer-kitWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
This skill provides a systematic approach for testing object-relational mapping logic, focusing on MapStruct implementations and custom data conversion classes. It validates the translation between domain entities and data transfer objects (DTOs), ensuring that field names, nested structures, and type conversions maintain integrity during serialization. The methodology emphasizes isolated unit testing using JUnit 5 and AssertJ to inspect object properties, collection handling, and edge cases like null values. By treating mappers as independent testable components, you reduce integration runtime failures and detect configuration errors in mapping definitions before they impact application service layers or database persistence flows.
When to Use This Skill
- •Confirming field renames work when mapping entities to view models
- •Ensuring legacy data types convert correctly to modern application types
- •Testing deep object nesting where child properties must propagate correctly
- •Validating default values or calculated fields triggered by @Mapping expressions
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “unit test my mapstruct interface
- “verify mapping logic for this converter class
- “write a junit test for this dto mapper
- “how to test nested object transformation in java
- “test my custom mapstruct expression
Pro Tips
- 💡Utilize data builders or factories to easily create test data, improving readability and reducing boilerplate in your test cases.
- 💡Focus on edge cases: thoroughly test null inputs, empty collections, boundary values, and invalid data types to ensure mapper robustness.
- 💡Leverage assertion libraries like AssertJ for fluent and expressive assertions, making your test failures clearer and easier to debug.
What this skill does
- •Validates direct field-to-field mapping accuracy between entities and DTOs
- •Verifies complex nested object graph transformations
- •Ensures consistent null safety handling for missing input values
- •Confirms successful execution of custom Java expressions within mapping logic
- •Tests bulk processing of object collections via iterable mapping
When not to use it
- ✕Verifying full database persistence logic or cross-service connectivity
- ✕Testing API response structures or HTTP status codes
- ✕Performance testing for large-scale object transformation throughput
Example workflow
- Define the target DTO and source entity structures
- Declare the MapStruct interface with appropriate @Mapping annotations
- Initialize the mapper instance in the test suite using Mappers.getMapper()
- Prepare input objects with expected field values and nested children
- Invoke the mapping method under test
- Use AssertJ to verify that all properties in the resulting object match the expected output
Prerequisites
- –JUnit 5
- –AssertJ
- –MapStruct library configured in project dependencies
Pitfalls & limitations
- !Assuming the mapper handles nulls automatically without testing edge cases
- !Failing to update mapper tests when entity class fields are renamed or removed
- !Overlooking potential NullPointerExceptions in nested path mapping
FAQ
Do I need to run a full Spring Context for these tests?
No. These are standard unit tests. You can instantiate mappers directly using MapStruct's static Mappers class, keeping test execution fast.
How do I handle custom conversion logic?
Test them by providing input data that specifically triggers your custom @Mapping expression and verify the computed output property.
Should I mock the mapper instead of using it?
Usually no. Since mappers are functional components, testing the real implementation is faster and more reliable than mocking.
How it compares
Unlike manual conversion testing which often repeats boilerplate code, this skill creates standardized, readable assertion patterns that catch silent failures in mapping configuration.
📄 Full skill instructions — original source: giuseppe-trisciuoglio/developer-kit
# Unit Testing Mappers and Converters
Test MapStruct mappers and custom converter classes. Verify field mapping accuracy, null handling, type conversions, and nested object transformations.
## When to Use This Skill
Use this skill when:
- Testing MapStruct mapper implementations
- Testing custom entity-to-DTO converters
- Testing nested object mapping
- Verifying null handling in mappers
- Testing type conversions and transformations
- Want comprehensive mapping test coverage before integration tests
## Setup: Testing Mappers
### Maven
### Gradle
## Basic Pattern: Testing MapStruct Mapper
### Simple Entity to DTO Mapping
## Testing Nested Object Mapping
### Map Complex Hierarchies
## Testing Custom Mapping Methods
### Mapper with @Mapping Annotations
## Testing Enum Mapping
### Map Enums Between Entity and DTO
## Testing Custom Type Conversions
### Non-MapStruct Custom Converter
## Testing Bidirectional Mapping
### Entity ↔ DTO Round Trip
## Testing Partial Mapping
### Update Existing Entity from DTO
## Best Practices
- **Test all mapper methods** comprehensively
- **Verify null handling** for every nullable field
- **Test nested objects** independently and together
- **Use recursive comparison** for complex nested structures
- **Test bidirectional mapping** to catch asymmetries
- **Keep mapper tests simple and focused** on transformation correctness
- **Use Mappers.getMapper()** for non-Spring standalone tests
## Common Pitfalls
- Not testing null input cases
- Not verifying nested object mappings
- Assuming bidirectional mapping is symmetric
- Not testing edge cases (empty collections, etc.)
- Tight coupling of mapper tests to MapStruct internals
## Troubleshooting
**Null pointer exceptions during mapping**: Check
**Enum mapping not working**: Verify
**Nested mapping produces null**: Ensure nested mapper interfaces are also mapped in parent mapper.
## References
- [MapStruct Official Documentation](https://mapstruct.org/)
- [MapStruct Mapping Strategies](https://mapstruct.org/documentation/stable/reference/html/)
- [JUnit 5 Best Practices](https://junit.org/junit5/docs/current/user-guide/)
Test MapStruct mappers and custom converter classes. Verify field mapping accuracy, null handling, type conversions, and nested object transformations.
## When to Use This Skill
Use this skill when:
- Testing MapStruct mapper implementations
- Testing custom entity-to-DTO converters
- Testing nested object mapping
- Verifying null handling in mappers
- Testing type conversions and transformations
- Want comprehensive mapping test coverage before integration tests
## Setup: Testing Mappers
### Maven
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>1.5.5.Final</version>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
<scope>test</scope>
</dependency>### Gradle
dependencies {
implementation("org.mapstruct:mapstruct:1.5.5.Final")
testImplementation("org.junit.jupiter:junit-jupiter")
testImplementation("org.assertj:assertj-core")
}## Basic Pattern: Testing MapStruct Mapper
### Simple Entity to DTO Mapping
// Mapper interface
@Mapper(componentModel = "spring")
public interface UserMapper {
UserDto toDto(User user);
User toEntity(UserDto dto);
List<UserDto> toDtos(List<User> users);
}
// Unit test
import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.*;
class UserMapperTest {
private final UserMapper userMapper = Mappers.getMapper(UserMapper.class);
@Test
void shouldMapUserToDto() {
User user = new User(1L, "Alice", "[email protected]", 25);
UserDto dto = userMapper.toDto(user);
assertThat(dto)
.isNotNull()
.extracting("id", "name", "email", "age")
.containsExactly(1L, "Alice", "[email protected]", 25);
}
@Test
void shouldMapDtoToEntity() {
UserDto dto = new UserDto(1L, "Alice", "[email protected]", 25);
User user = userMapper.toEntity(dto);
assertThat(user)
.isNotNull()
.hasFieldOrPropertyWithValue("id", 1L)
.hasFieldOrPropertyWithValue("name", "Alice");
}
@Test
void shouldMapListOfUsers() {
List<User> users = List.of(
new User(1L, "Alice", "[email protected]", 25),
new User(2L, "Bob", "[email protected]", 30)
);
List<UserDto> dtos = userMapper.toDtos(users);
assertThat(dtos)
.hasSize(2)
.extracting(UserDto::getName)
.containsExactly("Alice", "Bob");
}
@Test
void shouldHandleNullEntity() {
UserDto dto = userMapper.toDto(null);
assertThat(dto).isNull();
}
}## Testing Nested Object Mapping
### Map Complex Hierarchies
// Entities with nesting
class User {
private Long id;
private String name;
private Address address;
private List<Phone> phones;
}
// Mapper with nested mapping
@Mapper(componentModel = "spring")
public interface UserMapper {
UserDto toDto(User user);
User toEntity(UserDto dto);
}
// Unit test for nested objects
class NestedObjectMapperTest {
private final UserMapper userMapper = Mappers.getMapper(UserMapper.class);
@Test
void shouldMapNestedAddress() {
Address address = new Address("123 Main St", "New York", "NY", "10001");
User user = new User(1L, "Alice", address);
UserDto dto = userMapper.toDto(user);
assertThat(dto.getAddress())
.isNotNull()
.hasFieldOrPropertyWithValue("street", "123 Main St")
.hasFieldOrPropertyWithValue("city", "New York");
}
@Test
void shouldMapListOfNestedPhones() {
List<Phone> phones = List.of(
new Phone("123-456-7890", "MOBILE"),
new Phone("987-654-3210", "HOME")
);
User user = new User(1L, "Alice", null, phones);
UserDto dto = userMapper.toDto(user);
assertThat(dto.getPhones())
.hasSize(2)
.extracting(PhoneDto::getNumber)
.containsExactly("123-456-7890", "987-654-3210");
}
@Test
void shouldHandleNullNestedObjects() {
User user = new User(1L, "Alice", null);
UserDto dto = userMapper.toDto(user);
assertThat(dto.getAddress()).isNull();
}
}## Testing Custom Mapping Methods
### Mapper with @Mapping Annotations
@Mapper(componentModel = "spring")
public interface ProductMapper {
@Mapping(source = "name", target = "productName")
@Mapping(source = "price", target = "salePrice")
@Mapping(target = "discount", expression = "java(product.getPrice() * 0.1)")
ProductDto toDto(Product product);
@Mapping(source = "productName", target = "name")
@Mapping(source = "salePrice", target = "price")
Product toEntity(ProductDto dto);
}
class CustomMappingTest {
private final ProductMapper mapper = Mappers.getMapper(ProductMapper.class);
@Test
void shouldMapFieldsWithCustomNames() {
Product product = new Product(1L, "Laptop", 999.99);
ProductDto dto = mapper.toDto(product);
assertThat(dto)
.hasFieldOrPropertyWithValue("productName", "Laptop")
.hasFieldOrPropertyWithValue("salePrice", 999.99);
}
@Test
void shouldCalculateDiscountFromExpression() {
Product product = new Product(1L, "Laptop", 100.0);
ProductDto dto = mapper.toDto(product);
assertThat(dto.getDiscount()).isEqualTo(10.0);
}
@Test
void shouldReverseMapCustomFields() {
ProductDto dto = new ProductDto(1L, "Laptop", 999.99);
Product product = mapper.toEntity(dto);
assertThat(product)
.hasFieldOrPropertyWithValue("name", "Laptop")
.hasFieldOrPropertyWithValue("price", 999.99);
}
}## Testing Enum Mapping
### Map Enums Between Entity and DTO
// Enum with different representation
enum UserStatus { ACTIVE, INACTIVE, SUSPENDED }
enum UserStatusDto { ENABLED, DISABLED, LOCKED }
@Mapper(componentModel = "spring")
public interface UserMapper {
@ValueMapping(source = "ACTIVE", target = "ENABLED")
@ValueMapping(source = "INACTIVE", target = "DISABLED")
@ValueMapping(source = "SUSPENDED", target = "LOCKED")
UserStatusDto toStatusDto(UserStatus status);
}
class EnumMapperTest {
private final UserMapper mapper = Mappers.getMapper(UserMapper.class);
@Test
void shouldMapActiveToEnabled() {
UserStatusDto dto = mapper.toStatusDto(UserStatus.ACTIVE);
assertThat(dto).isEqualTo(UserStatusDto.ENABLED);
}
@Test
void shouldMapSuspendedToLocked() {
UserStatusDto dto = mapper.toStatusDto(UserStatus.SUSPENDED);
assertThat(dto).isEqualTo(UserStatusDto.LOCKED);
}
}## Testing Custom Type Conversions
### Non-MapStruct Custom Converter
// Custom converter class
public class DateFormatter {
private static final DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd");
public static String format(LocalDate date) {
return date != null ? date.format(formatter) : null;
}
public static LocalDate parse(String dateString) {
return dateString != null ? LocalDate.parse(dateString, formatter) : null;
}
}
// Unit test
class DateFormatterTest {
@Test
void shouldFormatLocalDateToString() {
LocalDate date = LocalDate.of(2024, 1, 15);
String result = DateFormatter.format(date);
assertThat(result).isEqualTo("2024-01-15");
}
@Test
void shouldParseStringToLocalDate() {
String dateString = "2024-01-15";
LocalDate result = DateFormatter.parse(dateString);
assertThat(result).isEqualTo(LocalDate.of(2024, 1, 15));
}
@Test
void shouldHandleNullInFormat() {
String result = DateFormatter.format(null);
assertThat(result).isNull();
}
@Test
void shouldHandleInvalidDateFormat() {
assertThatThrownBy(() -> DateFormatter.parse("invalid-date"))
.isInstanceOf(DateTimeParseException.class);
}
}## Testing Bidirectional Mapping
### Entity ↔ DTO Round Trip
class BidirectionalMapperTest {
private final UserMapper mapper = Mappers.getMapper(UserMapper.class);
@Test
void shouldMaintainDataInRoundTrip() {
User original = new User(1L, "Alice", "[email protected]", 25);
UserDto dto = mapper.toDto(original);
User restored = mapper.toEntity(dto);
assertThat(restored)
.hasFieldOrPropertyWithValue("id", original.getId())
.hasFieldOrPropertyWithValue("name", original.getName())
.hasFieldOrPropertyWithValue("email", original.getEmail())
.hasFieldOrPropertyWithValue("age", original.getAge());
}
@Test
void shouldPreserveAllFieldsInBothDirections() {
Address address = new Address("123 Main", "NYC", "NY", "10001");
User user = new User(1L, "Alice", "[email protected]", 25, address);
UserDto dto = mapper.toDto(user);
User restored = mapper.toEntity(dto);
assertThat(restored).usingRecursiveComparison().isEqualTo(user);
}
}## Testing Partial Mapping
### Update Existing Entity from DTO
@Mapper(componentModel = "spring")
public interface UserMapper {
void updateEntity(@MappingTarget User entity, UserDto dto);
}
class PartialMapperTest {
private final UserMapper mapper = Mappers.getMapper(UserMapper.class);
@Test
void shouldUpdateExistingEntity() {
User existing = new User(1L, "Alice", "[email protected]", 25);
UserDto dto = new UserDto(1L, "Alice", "[email protected]", 26);
mapper.updateEntity(existing, dto);
assertThat(existing)
.hasFieldOrPropertyWithValue("email", "[email protected]")
.hasFieldOrPropertyWithValue("age", 26);
}
@Test
void shouldNotUpdateFieldsNotInDto() {
User existing = new User(1L, "Alice", "[email protected]", 25);
UserDto dto = new UserDto(1L, "Bob", null, 0);
mapper.updateEntity(existing, dto);
// Assuming null-aware mapping is configured
assertThat(existing.getEmail()).isEqualTo("[email protected]");
}
}## Best Practices
- **Test all mapper methods** comprehensively
- **Verify null handling** for every nullable field
- **Test nested objects** independently and together
- **Use recursive comparison** for complex nested structures
- **Test bidirectional mapping** to catch asymmetries
- **Keep mapper tests simple and focused** on transformation correctness
- **Use Mappers.getMapper()** for non-Spring standalone tests
## Common Pitfalls
- Not testing null input cases
- Not verifying nested object mappings
- Assuming bidirectional mapping is symmetric
- Not testing edge cases (empty collections, etc.)
- Tight coupling of mapper tests to MapStruct internals
## Troubleshooting
**Null pointer exceptions during mapping**: Check
nullValuePropertyMappingStrategy and nullValueCheckStrategy in @Mapper.**Enum mapping not working**: Verify
@ValueMapping annotations correctly map source to target values.**Nested mapping produces null**: Ensure nested mapper interfaces are also mapped in parent mapper.
## References
- [MapStruct Official Documentation](https://mapstruct.org/)
- [MapStruct Mapping Strategies](https://mapstruct.org/documentation/stable/reference/html/)
- [JUnit 5 Best Practices](https://junit.org/junit5/docs/current/user-guide/)
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/unit-test-mapper-converter/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/giuseppe-trisciuoglio/developer-kit/unit-test-mapper-converter/SKILL.md - Cursor:
~/.cursor/skills/giuseppe-trisciuoglio/developer-kit/unit-test-mapper-converter/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/giuseppe-trisciuoglio/developer-kit/unit-test-mapper-converter/SKILL.md
🚀 Install with CLI:npx skills add giuseppe-trisciuoglio/developer-kit
Recommended Rules
View more rules →Spring Boot Java Expert
Spring BootJavaBackend
You are an expert in Spring Boot and Java enterprise development. Key Principles: - Convention over Configuration - Standalone, production-grade appl...
JavaScript ES6+ Modern Features Expert
JavaScriptES6+Modern JavaScript
You are an expert in modern JavaScript ES6+ features and best practices. Key Principles: - Use modern JavaScript syntax - Leverage ES6+ features for ...
Unit Testing Best Practices
TestingUnit TestQA
You are an expert in Unit Testing principles and best practices. Key Principles: - Test small, isolated units of code (functions/classes) - Tests mus...
Recommended Workflows
View more workflows →Check SSL Certificates
SecurityDevOpsSSL
--- description: Verify SSL certificate validity and expiration --- 1. **Check Expiry**: - Use openssl to check a domain. Replace `google.com` wit...
Setup Semantic Versioning
VersioningReleasesGit
--- description: Automate version bumps and changelog generation --- 1. **Install semantic-release**: - Automate versioning based on commit messag...
Implement Feature Flags
Feature FlagsDeploymentA/B Testing
--- description: Safely release features with toggles for gradual rollouts --- 1. **Simple Approach: Environment Variables**: - Use env vars for b...