Spring Boot Testing Setup Guide

Spring Boot Testing Setup Guide

This skill provides comprehensive documentation for setting up unit and integration testing in Spring Boot applications, emphasizing auto-configuration and best practices from the Baeldung reference patterns.

Overview

Spring Boot provides powerful testing support with auto-configured test annotations that bootstrap only the necessary parts of the application context. This approach ensures fast, focused tests while maintaining the benefits of Spring's dependency injection.

Note: For Spring Boot 3.4+, use @MockitoBean instead of @MockBean for mocking dependencies. @MockitoBean provides better performance and more consistent behavior with the latest Mockito features.

Dependencies

Add these essential testing dependencies to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</​groupId>
    <artifactId>spring-boot-starter-test</​artifactId>
    <scope>test</​scope>
</​dependency>
<dependency>
    <groupId>com.h2database</​groupId>
    <artifactId>h2</​artifactId>
    <scope>test</​scope>
</​dependency>

The spring-boot-starter-test includes:

• JUnit 5
• Mockito
• MockitoBean (Spring Boot 3.4+)
• AssertJ
• Hamcrest
• Spring Test & Spring Boot Test

Testing Strategy

1. Unit Tests

• Purpose: Test individual components in isolation
• Speed: Fast
• Dependencies: Mocked
• Recommended Annotations: @ExtendWith(SpringExtension.class), @WebMvcTest, @DataJpaTest

2. Integration Tests

• Purpose: Test interaction between layers
• Speed: Slower
• Dependencies: Real or test database
• Recommended Annotations: @SpringBootTest

Auto-Configured Test Annotations

Controller Layer Testing

Use @WebMvcTest for focused controller tests:

@ExtendWith(SpringExtension.class)
@WebMvcTest(EmployeeRestController.class)
public class EmployeeRestControllerTest {

    @Autowired
    private MockMvc mvc;

    @MockitoBean  // Use MockitoBean for Spring Boot 3.4+
    private EmployeeService service;

    @Test
    public void givenEmployees_whenGetEmployees_thenReturnJsonArray() throws Exception {
        Employee alex = new Employee("alex");
        List<Employee> allEmployees = Arrays.asList(alex);

        given(service.getAllEmployees()).willReturn(allEmployees);

        mvc.perform(get("/​api/​employees")
                .contentType(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$", hasSize(1)))
                .andExpect(jsonPath("$[0].name", is(alex.getName())));
    }
}

Benefits:

• Auto-configures MockMvc
• Loads only controller-related beans
• Mocks dependencies with @MockitoBean (Spring Boot 3.4+) or @MockBean (older versions)
• Fast execution

Persistence Layer Testing

Use @DataJpaTest for repository tests:

@ExtendWith(SpringExtension.class)
@DataJpaTest
public class EmployeeRepositoryTest {

    @Autowired
    private TestEntityManager entityManager;

    @Autowired
    private EmployeeRepository employeeRepository;

    @Test
    public void whenFindByName_thenReturnEmployee() {
        Employee alex = new Employee("alex");
        entityManager.persist(alex);
        entityManager.flush();

        Employee found = employeeRepository.findByName(alex.getName());

        assertThat(found.getName()).isEqualTo(alex.getName());
    }
}

Auto-configuration includes:

• In-memory H2 database
• Hibernate, Spring Data, DataSource
• Entity scanning
• SQL logging

Service Layer Testing

Use @ExtendWith with @MockBean for service tests:

@ExtendWith(SpringExtension.class)
public class EmployeeServiceTest {

    @MockitoBean  // Use MockitoBean for Spring Boot 3.4+
    private EmployeeRepository employeeRepository;

    @Autowired
    private EmployeeService employeeService;

    @BeforeEach
    public void setUp() {
        Employee alex = new Employee("alex");
        when(employeeRepository.findByName(alex.getName())).thenReturn(alex);
    }

    @Test
    public void whenValidName_thenEmployeeShouldBeFound() {
        String name = "alex";
        Employee found = employeeService.getEmployeeByName(name);

        assertThat(found.getName()).isEqualTo(name);
    }
}

Full Integration Testing

Use @SpringBootTest for end-to-end tests:

@ExtendWith(SpringExtension.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
@AutoConfigureMockMvc
@TestPropertySource(locations = "classpath:application-integrationtest.properties")
public class EmployeeRestControllerIntegrationTest {

    @Autowired
    private MockMvc mvc;

    @Autowired
    private EmployeeRepository repository;

    @Test
    public void givenEmployees_whenGetEmployees_thenStatus200() throws Exception {
        createTestEmployee("bob");

        mvc.perform(get("/​api/​employees")
                .contentType(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_JSON))
                .andExpect(jsonPath("$[0].name", is("bob")));
    }

    private void createTestEmployee(String name) {
        Employee employee = new Employee(name);
        repository.save(employee);
    }
}

Test Configuration

Test-Specific Configuration

Use @TestConfiguration for test-specific beans:

@TestConfiguration
public class EmployeeServiceTestConfig {

    @Bean
    @Primary
    public EmployeeService employeeService() {
        return new EmployeeServiceImpl() {
            // Test-specific implementation
        };
    }
}

Import in tests:

@ExtendWith(SpringExtension.class)
@Import(EmployeeServiceTestConfig.class)
public class EmployeeServiceTest {
    // Test implementation
}

Test Properties

Create test-specific configuration files. Spring Boot supports both .properties and .yml formats:

For .properties format (application-integrationtest.properties):

spring.datasource.url=jdbc:h2:mem:test
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto=create-drop
logging.level.org.hibernate.SQL=DEBUG

For .yml format (application-integrationtest.yml):

spring:
  datasource:
    url: jdbc:h2:mem:test
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.H2Dialect
    hibernate:
      ddl-auto: create-drop
logging:
  level:
    org.hibernate.SQL: DEBUG

Note: Use the same format as your main application configuration. If your project uses application.yml, create application-integrationtest.yml for consistency.

Specialized Auto-Configured Tests

WebFlux Testing

@WebFluxTest(HomeController.class)
public class HomeControllerTest {
    // Test reactive controllers
}

JSON Testing

@JsonTest
public class EmployeeJsonTest {
    @Autowired
    private JacksonTester<Employee> json;

    @Test
    public void employeeSerializationTest() throws IOException {
        Employee employee = new Employee("John");
        assertThat(json.write(employee)).isEqualToJson("expected.json");
    }
}

REST Client Testing

@RestClientTest(EmployeeClient.class)
public class EmployeeClientTest {
    @Autowired
    private MockRestServiceServer server;

    @Autowired
    private EmployeeClient client;
}

Database Testing

JDBC Testing

@JdbcTest
public class EmployeeJdbcTest {
    @Autowired
    private JdbcTemplate jdbcTemplate;
}

MongoDB Testing

@DataMongoTest
public class EmployeeMongoTest {
    @Autowired
    private MongoTemplate mongoTemplate;
}

Best Practices

1. Test Organization

• Keep unit tests in src/​test/​java
• Separate integration tests with @Test annotation profiles
• Use descriptive test names

2. Auto-Configuration Priority

Always prefer auto-configured test annotations:

• Use @WebMvcTest instead of @SpringBootTest for controller tests
• Use @DataJpaTest instead of @SpringBootTest for repository tests
• Use @SpringBootTest only when necessary

3. Mocking Strategy

• Mock external dependencies with @MockitoBean (Spring Boot 3.4+) or @MockBean (older versions)
• Use @TestConfiguration for test-specific beans
• Avoid mocking the layer you're testing

4. Test Data Management

• Use TestEntityManager for JPA tests
• Clean up test data in @AfterEach
• Use @Transactional for rollback behavior

5. Performance Considerations

• Run unit tests separately from integration tests
• Use in-memory databases for testing
• Limit @SpringBootTest usage

Test Execution Profiles

Maven Configuration

<profiles>
    <profile>
        <id>unit-tests</​id>
        <build>
            <plugins>
                <plugin>
                    <artifactId>maven-surefire-plugin</​artifactId>
                    <configuration>
                        <includes>
                            <include>**/​*Test.java</​include>
                        </​includes>
                        <excludes>
                            <exclude>**/​*IntegrationTest.java</​exclude>
                        </​excludes>
                    </​configuration>
                </​plugin>
            </​plugins>
        </​build>
    </​profile>
    <profile>
        <id>integration-tests</​id>
        <build>
            <plugins>
                <plugin>
                    <artifactId>maven-failsafe-plugin</​artifactId>
                    <configuration>
                        <includes>
                            <include>**/​*IntegrationTest.java</​include>
                        </​includes>
                    </​configuration>
                </​plugin>
            </​plugins>
        </​build>
    </​profile>
</​profiles>

Running Tests

# Unit tests only
mvn test -Punit-tests

# Integration tests only
mvn verify -Pintegration-tests

# All tests
mvn test

Common Patterns

Service Layer with Repository Mock

@ExtendWith(SpringExtension.class)
public class EmployeeServiceTest {

    @MockitoBean  // Use MockitoBean for Spring Boot 3.4+
    private EmployeeRepository repository;

    @InjectMocks
    @Autowired
    private EmployeeService service;

    @Test
    public void whenFindById_thenReturnEmployee() {
        // Given
        Employee employee = new Employee("John");
        when(repository.findById(1L)).thenReturn(Optional.of(employee));

        // When
        Employee found = service.findById(1L);

        // Then
        assertThat(found.getName()).isEqualTo("John");
    }
}

Controller with Service Mock

@WebMvcTest(EmployeeController.class)
public class EmployeeControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean  // Use MockitoBean for Spring Boot 3.4+
    private EmployeeService service;

    @Test
    public void getEmployee_shouldReturnEmployee() throws Exception {
        Employee employee = new Employee("John");
        when(service.findById(1L)).thenReturn(employee);

        mockMvc.perform(get("/​employees/​1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.name", is("John")));
    }
}

Repository Integration Test

@DataJpaTest
@TestPropertySource(properties = {
    "spring.jpa.hibernate.ddl-auto=create-drop"
})
public class EmployeeRepositoryTest {

    @Autowired
    private TestEntityManager entityManager;

    @Autowired
    private EmployeeRepository repository;

    @Test
    public void findByName_shouldReturnEmployee() {
        Employee employee = new Employee("John");
        entityManager.persistAndFlush(employee);

        Optional<Employee> found = repository.findByName("John");

        assertThat(found).isPresent();
        assertThat(found.get().getName()).isEqualTo("John");
    }
}

Conclusion

Spring Boot's auto-configured test annotations provide a powerful, efficient way to structure tests. By choosing the right annotation for each test type and leveraging auto-configuration, you can create fast, maintainable test suites that provide comprehensive coverage while minimizing setup complexity.

Key takeaways:

1. Prefer auto-configured annotations over manual configuration
2. Choose the right test slice for the layer you're testing
3. Mock dependencies appropriately with @MockitoBean (Spring Boot 3.4+) or @MockBean (older versions)
4. Separate test types for better performance and organization
5. Use test-specific configuration for specialized test needs