Spring Boot Testing Patterns

Overview

Comprehensive guidance for writing robust test suites for Spring Boot applications using JUnit 5, Mockito, Testcontainers, and performance-optimized slice testing patterns.

When to Use

• Writing unit tests for services or repositories with mocked dependencies

• Implementing integration tests with real databases via Testcontainers

• Testing REST APIs with @WebMvcTest or MockMvc

• Configuring @ServiceConnection for container management in Spring Boot 3.5+

Quick Reference

Test Type Annotation Target Time Use Case

Unit Tests @ExtendWith(MockitoExtension.class)

< 50ms Business logic without Spring context

Repository Tests @DataJpaTest

< 100ms Database operations with minimal context

Controller Tests @WebMvcTest / @WebFluxTest

< 100ms REST API layer testing

Integration Tests @SpringBootTest

< 500ms Full application context with containers

Testcontainers @ServiceConnection / @Testcontainers

Varies Real database/message broker containers

Core Concepts

Test Architecture Philosophy

• Unit Tests — Fast, isolated tests without Spring context (< 50ms)

• Slice Tests — Minimal Spring context for specific layers (< 100ms)

• Integration Tests — Full Spring context with real dependencies (< 500ms)

Key Annotations

Spring Boot Test:

• @SpringBootTest — Full application context (use sparingly)

• @DataJpaTest — JPA components only (repositories, entities)

• @WebMvcTest — MVC layer only (controllers, @ControllerAdvice )

• @WebFluxTest — WebFlux layer only (reactive controllers)

• @JsonTest — JSON serialization components only

Testcontainers:

• @ServiceConnection — Wire Testcontainer to Spring Boot (3.5+)

• @DynamicPropertySource — Register dynamic properties at runtime

• @Testcontainers — Enable Testcontainers lifecycle management

Instructions

1. Unit Testing Pattern

Test business logic with mocked dependencies:

@ExtendWith(MockitoExtension.class) class UserServiceTest { @Mock private UserRepository userRepository;

@InjectMocks
private UserService userService;

@Test
void shouldFindUserByIdWhenExists() {
    when(userRepository.findById(1L)).thenReturn(Optional.of(user));
    Optional<User> result = userService.findById(1L);
    assertThat(result).isPresent();
    verify(userRepository).findById(1L);
}

}

See unit-testing.md for advanced patterns.

2. Slice Testing Pattern

Use focused test slices for specific layers:

@DataJpaTest @AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE) @TestContainerConfig class UserRepositoryIntegrationTest { @Autowired private UserRepository userRepository;

@Test
void shouldSaveAndRetrieveUser() {
    User saved = userRepository.save(user);
    assertThat(userRepository.findByEmail("test@example.com")).isPresent();
}

}

See slice-testing.md for all slice patterns.

3. REST API Testing Pattern

Test controllers with MockMvc:

@WebMvcTest(UserController.class) class UserControllerTest { @Autowired private MockMvc mockMvc;

@MockBean
private UserService userService;

@Test
void shouldGetUserById() throws Exception {
    mockMvc.perform(get("/api/users/1"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.email").value("test@example.com"));
}

}

4. Testcontainers with @ServiceConnection

Configure containers with Spring Boot 3.5+:

@TestConfiguration public class TestContainerConfig { @Bean @ServiceConnection public PostgreSQLContainer<?> postgresContainer() { return new PostgreSQLContainer<>("postgres:16-alpine"); } }

Apply with @Import(TestContainerConfig.class) on test classes. See testcontainers-setup.md for detailed configuration.

5. Add Dependencies

Include required testing dependencies:

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.testcontainers</groupId> <artifactId>junit-jupiter</artifactId> <version>1.19.0</version> <scope>test</scope> </dependency>

See test-dependencies.md for complete dependency list.

6. Configure CI/CD

Set up GitHub Actions for automated testing:

name: Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest services: docker: image: docker:20-dind steps: - uses: actions/checkout@v4 - name: Set up JDK 17 uses: actions/setup-java@v4 with: distribution: 'temurin' - name: Run tests run: ./mvnw test

See ci-cd-configuration.md for full CI/CD patterns.

Validation Checkpoints

After implementing tests, verify:

• Container running: docker ps (look for testcontainer images)

• Context loaded: check startup logs for "Started Application in X.XX seconds"

• Test isolation: run tests individually and confirm no cross-contamination

Examples

Full Integration Test with @ServiceConnection

@SpringBootTest @Import(TestContainerConfig.class) class OrderServiceIntegrationTest {

@Autowired
private OrderService orderService;

@Autowired
private UserRepository userRepository;

@Test
void shouldCreateOrderForExistingUser() {
    User user = userRepository.save(User.builder()
        .email("order-test@example.com")
        .build());

    Order order = orderService.createOrder(user.getId(), List.of(
        new OrderItem("SKU-001", 2)
    ));

    assertThat(order.getId()).isNotNull();
    assertThat(order.getStatus()).isEqualTo(OrderStatus.PENDING);
}

}

@DataJpaTest with Real Database

@DataJpaTest @AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE) @TestContainerConfig class UserRepositoryTest {

@Autowired
private UserRepository userRepository;

@Test
void shouldFindByEmail() {
    userRepository.save(User.builder()
        .email("jpa-test@example.com")
        .build());
    assertThat(userRepository.findByEmail("jpa-test@example.com"))
        .isPresent();
}

}

See workflow-patterns.md for complete end-to-end examples.

Best Practices

• Use the right test type: @DataJpaTest for repositories, @WebMvcTest for controllers, @SpringBootTest only for full integration

• Prefer @ServiceConnection on Spring Boot 3.5+ for cleaner container management over @DynamicPropertySource

• Keep tests deterministic: Initialize all test data explicitly in @BeforeEach

• Organize by layer: Group tests by layer to maximize context caching

• Reuse Testcontainers at JVM level (withReuse(true)

• TESTCONTAINERS_REUSE_ENABLE=true )

• Avoid @DirtiesContext : Forces context rebuild, significantly hurts performance

• Mock external services, use real databases only when necessary

• Performance targets: Unit < 50ms, Slice < 100ms, Integration < 500ms

Constraints and Warnings

• Never use @DirtiesContext unless absolutely necessary (forces context rebuild)

• Avoid mixing @MockBean with different configurations (creates separate contexts)

• Testcontainers require Docker; ensure CI/CD pipelines have Docker support

• Do not rely on test execution order; each test must be independent

• Be cautious with @TestPropertySource (creates separate contexts)

• Do not use @SpringBootTest for unit tests; use plain Mockito instead

• Context caching can be invalidated by different @MockBean configurations

• Avoid static mutable state in tests (causes flaky tests)

References

• test-dependencies.md — Maven/Gradle test dependencies

• unit-testing.md — Unit testing with Mockito patterns

• slice-testing.md — Repository, controller, and JSON slice tests

• testcontainers-setup.md — Testcontainers configuration patterns

• ci-cd-configuration.md — GitHub Actions, GitLab CI, Docker Compose

• api-reference.md — Complete test annotations and utilities

• best-practices.md — Testing patterns and optimization

• workflow-patterns.md — Complete integration test examples