spring-testing

Spring Boot Testing Standards

Context

• Apply when creating or modifying Spring Boot test classes
• For testing controllers, services, repositories, and integration scenarios
• When using Spring Boot Test framework with JUnit 5
• For both unit tests and integration tests with TestContainers
• When using jOOQ for database access and complex mocking scenarios
• Follow integration-first testing approach: comprehensive API tests, then focused unit tests
• Note: Some examples show Spring Boot 4-specific patterns (marked with "Spring Boot 4+"). For Spring Boot 3.5, use PostgreSQLContainer<?> (with generic) and TestRestTemplate from org.springframework.boot.test.web.client.TestRestTemplate without @AutoConfigureTestRestTemplate

Requirements

1. Test Strategy: Prefer integration tests against the API first, then unit tests with mocks for specific logic testing
2. Test Structure: Use appropriate Spring Boot test slices (@WebMvcTest, @DataJpaTest, @JsonTest, etc.)
3. Integration Tests: Use @SpringBootTest with TestContainers for full integration testing
4. Mocking: Use @Mock + @InjectMocks for unit tests. Use @MockitoBean in Spring test slices when bean replacement is necessary
5. Test Profiles: Use @ActiveProfiles("test") for test-specific configuration
6. Database Testing: Use TestContainers with PostgreSQL for realistic database testing
7. Web Layer Testing: Use MockMvc for controller testing with proper content type assertions
8. Base Test Classes: Use inheritance for shared test infrastructure and common setup
9. TestContainers Configuration: Use singleton pattern with @ServiceConnection for container reuse
10. External HTTP APIs: Use WireMock for mocking external HTTP dependencies in tests

Examples

private static final Logger log = LoggerFactory.getLogger(TestcontainersConfiguration.class);
private static final DockerImageName POSTGRES_IMAGE = DockerImageName.parse("postgres:15")
        .asCompatibleSubstituteFor("postgres");

// Spring Boot 4+ / Testcontainers 2.x: No generic type parameter
// Spring Boot 3.5: Use PostgreSQLContainer<?>
private static final PostgreSQLContainer POSTGRES_CONTAINER;

static {
    log.info("Initializing PostgreSQL Testcontainer with reuse enabled...");
    POSTGRES_CONTAINER = new PostgreSQLContainer(POSTGRES_IMAGE)
            .withDatabaseName("bookstore_test")
            .withUsername("test")
            .withPassword("test")
            .withReuse(true)
            .withStartupTimeout(Duration.ofSeconds(60))
            .withConnectTimeoutSeconds(60);

    POSTGRES_CONTAINER.start();

    // Add shutdown hook for robustness
    Runtime.getRuntime().addShutdownHook(new Thread(() -> {
        if (POSTGRES_CONTAINER != null && POSTGRES_CONTAINER.isRunning()) {
            POSTGRES_CONTAINER.close();
        }
    }));
}

@Bean
@ServiceConnection
// Spring Boot 4+ / Testcontainers 2.x: No generic type parameter
// Spring Boot 3.5: Use PostgreSQLContainer<?>
public PostgreSQLContainer postgresContainer() {
    return POSTGRES_CONTAINER;
}

@DynamicPropertySource
public static void registerDynamicProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", POSTGRES_CONTAINER::getJdbcUrl);
    registry.add("spring.datasource.username", POSTGRES_CONTAINER::getUsername);
    registry.add("spring.datasource.password", POSTGRES_CONTAINER::getPassword);
    registry.add("spring.datasource.driver-class-name", POSTGRES_CONTAINER::getDriverClassName);
}

// Spring Boot 4+ / Testcontainers 2.x: No generic type parameter
// Spring Boot 3.5: Use PostgreSQLContainer<?>
public static PostgreSQLContainer getPostgresContainer() {
    return POSTGRES_CONTAINER;
}

}

</example>