MapStruct is a powerful Java annotation processor that generates type-safe, performant mappers at compile time, eliminating the need to write repetitive boilerplate code for converting between different Java bean types like DTOs and entities. Let us delve into understanding mapstruct generated mappers unit test, focusing on how to effectively write tests that validate these generated mappings for correctness and reliability.
1. What is MapStruct?
MapStruct is a Java annotation processor-based code generator that simplifies mapping between Java bean types such as Data Transfer Objects (DTOs) and entities. It automatically generates mapping implementations at compile-time, resulting in fast, efficient, and type-safe mappers that reduce runtime overhead compared to reflection-based solutions. Instead of writing repetitive and error-prone boilerplate code manually to map fields between objects, MapStruct allows you to define simple interfaces annotated with @Mapper, which it then uses to generate the implementation code.This approach not only boosts developer productivity but also helps maintain cleaner codebases. For more details on MapStruct and its features, you can visit the official MapStruct website or check out their comprehensive documentation.
2. Code Example
This section provides a detailed, step-by-step example to help you set up and use MapStruct for mapping between Java objects. We start with configuring the necessary Maven dependencies, followed by creating simple Java classes representing the source and target data structures. Finally, we define a MapStruct mapper interface to automatically generate the conversion code at compile-time.
2.1 Maven Dependencies (pom.xml)
To use MapStruct in your Java project, you need to add the necessary dependencies to your pom.xml file if you are using Maven. These include the core MapStruct library, the annotation processor that generates the mapper implementations at compile time, and testing libraries like JUnit and Mockito to write effective unit tests for your mappers.
<dependencies>
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>latest_jar_version</version>
</dependency>
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>latest_jar_version</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>latest_jar_version</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
<version>latest_jar_version</version>
<scope>test</scope>
</dependency>
</dependencies>
2.2 Create Java Classes and Mapper
2.2.1 Source DTO Class
The UserDto class represents the source data transfer object (DTO) that holds user information. It contains fields typically received from external sources such as API requests or UI forms. This class includes a no-argument constructor, a parameterized constructor for easy object creation, and getters and setters to access and modify the fields.
// Source DTO class
public class UserDto {
private String username;
private int age;
private String email;
public UserDto() {}
public UserDto(String username, int age, String email) {
this.username = username;
this.age = age;
this.email = email;
}
// Getters and setters
}
2.2.2 Target Entity Class
The UserEntity class represents the target entity typically used in your application’s business or persistence layer. It has similar fields to the DTO but with different naming conventions. This class also provides constructors, along with getters and setters to access and modify its fields.
// Target Entity class
public class UserEntity {
private String name;
private int age;
private String emailAddress;
public UserEntity() {}
public UserEntity(String name, int age, String emailAddress) {
this.name = name;
this.age = age;
this.emailAddress = emailAddress;
}
// Getters and setters
}
2.2.3 MapStruct Mapper interface
This interface defines the mapping logic between UserDto and UserEntity using MapStruct annotations. MapStruct automatically generates the implementation at compile time, improving performance and type safety compared to reflection-based mappers. The @Mapping annotations specify how differently named fields should be mapped between the source and target objects. The componentModel = "spring" setting allows this mapper to be injected as a Spring bean for seamless integration.
// MapStruct Mapper interface
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;
@Mapper(componentModel = "spring") // better integration if using Spring
public interface UserMapper {
UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
@Mapping(source = "username", target = "name")
@Mapping(source = "email", target = "emailAddress")
UserEntity toEntity(UserDto dto);
@Mapping(source = "name", target = "username")
@Mapping(source = "emailAddress", target = "email")
UserDto toDto(UserEntity entity);
}
2.3 Unit Test for Generated Mapper (without mocking)
This unit test verifies the correctness of the MapStruct-generated mapper implementation. It uses the real mapper instance provided by MapStruct without any mocking, ensuring the mapping methods convert fields between UserDto and UserEntity as expected.
import org.junit.Test;
import static org.junit.Assert.*;
public class UserMapperTest {
private final UserMapper userMapper = UserMapper.INSTANCE;
@Test
public void shouldMapUserDtoToUserEntity() {
UserDto dto = new UserDto("john_doe", 30, "john@example.com");
UserEntity entity = userMapper.toEntity(dto);
assertNotNull(entity);
assertEquals("john_doe", entity.getName());
assertEquals(30, entity.getAge());
assertEquals("john@example.com", entity.getEmailAddress());
}
@Test
public void shouldMapUserEntityToUserDto() {
UserEntity entity = new UserEntity("jane_doe", 25, "jane@example.com");
UserDto dto = userMapper.toDto(entity);
assertNotNull(dto);
assertEquals("jane_doe", dto.getUsername());
assertEquals(25, dto.getAge());
assertEquals("jane@example.com", dto.getEmail());
}
}
The above unit test class UserMapperTest verifies the functionality of the MapStruct-generated UserMapper implementation by testing both directions of mapping: from UserDto to UserEntity and vice versa. The test methods create sample instances of the source objects, invoke the mapper methods toEntity() and toDto(), and then assert that the mapped object’s fields correctly reflect the source data, including proper field name conversions such as username to name and email to emailAddress. The tests ensure the mapper is not null and all expected values match exactly, confirming the mapper’s correctness without any mocking, relying solely on the generated implementation.
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
2.4 Unit Test with Mocked Mapper (using Mockito)
This example demonstrates how to unit test code that depends on the UserMapper by mocking its behavior using Mockito. Instead of using the real MapStruct-generated implementation, the UserMapper interface is mocked to simulate its behavior. The test sets up expectations that when toEntity() is called with a specific UserDto, a predefined UserEntity is returned. The test verifies the method invocation count and asserts that the returned mock object contains the expected values. This approach is useful when testing higher-level services that depend on the mapper, isolating them from the mapper’s actual implementation.
import org.junit.Before;
import org.junit.Test;
import org.mockito.Mockito;
import static org.junit.Assert.*;
import static org.mockito.Mockito.*;
public class UserMapperMockTest {
private UserMapper userMapper;
@Before
public void setup() {
userMapper = mock(UserMapper.class);
}
@Test
public void whenMappingDtoToEntity_thenReturnMockedEntity() {
UserDto dto = new UserDto("mock_user", 40, "mock@example.com");
UserEntity mockedEntity = new UserEntity("mock_user", 40, "mock@example.com");
when(userMapper.toEntity(dto)).thenReturn(mockedEntity);
UserEntity result = userMapper.toEntity(dto);
verify(userMapper, times(1)).toEntity(dto);
assertNotNull(result);
assertEquals("mock_user", result.getName());
assertEquals(40, result.getAge());
assertEquals("mock@example.com", result.getEmailAddress());
}
}
This unit test class UserMapperMockTest shows how to use Mockito to create a mock of the UserMapper interface instead of using the real MapStruct-generated implementation. In the setup() method, the mapper is mocked, allowing controlled behavior during testing. The test whenMappingDtoToEntity_thenReturnMockedEntity() configures the mock to return a predefined UserEntity whenever toEntity() is called with a specific UserDto. It then calls the method, verifies that the method was invoked exactly once, and asserts that the returned mocked entity’s fields match the expected values. This technique is useful to isolate tests when the mapper’s behavior is not the focus, such as in service-layer unit tests.
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
3. Conclusion
Unit testing MapStruct mappers is straightforward when you test the generated mappers directly to verify actual field mappings and use mocking frameworks like Mockito to isolate dependent components. Enhanced examples with multiple fields and clear mappings improve test coverage and maintainability. MapStruct’s compile-time generation ensures fast, reliable, and type-safe mappers, reducing boilerplate code and enabling easier testing. Following these practices leads to robust, clean, and testable mapping code that integrates well within your application.
