Spring TestContainers: Simplifying Integration Testing

Integration testing with containerized services has become a standard practice in modern application development. Spring TestContainers is a library that makes this process significantly easier, especially for Spring and Spring Boot applications.

What is Spring TestContainers?

Spring TestContainers is a Java library that offers a clean, annotation-based way to use Testcontainers in Spring applications. It removes boilerplate and handles container lifecycles for you. Key features include:

• Simple annotation API (@EnablePostgreSQL, @EnableMySQL, @EnableOllamaContainer)

• Automatic container startup and shutdown

• Auto-configuration of Spring environment with container connection details

• Seamless integration with JUnit 5

• Support for multiple container types: PostgreSQL, MySQL, and Ollama

You can also easily add support for new container types by creating a custom container extension. Learn how to do that here: Writing a New Container Extension for Spring TestContainers .

Annotation-Based Approach

Spring TestContainers uses annotations to enable and configure containers. For example:

@SpringBootTest
@EnablePostgreSQL(version = "15")
class MyIntegrationTest {
    @Autowired
    private DataSource dataSource;
 
    @Test
    void testDatabaseConnection() {
        // Test code here
        // Container is automatically started and configured
    }
}

Behind the scenes, the library:

1. Detects the @EnablePostgreSQL annotation
2. Creates and configures a PostgreSQL container with the specified version
3. Starts the container when the Spring context initializes
4. Configures Spring’s environment with the container’s connection details
5. Stops the container when the Spring context is closed

Spring Boot’s ServiceConnection

Spring Boot 3.1+ introduced the ServiceConnection interface as part of its TestContainers support. This approach:

1. Uses a programmatic model rather than annotations
2. Leverages Spring Boot’s auto-configuration capabilities
3. Integrates with Spring Boot’s property system

Example with ServiceConnection:

@SpringBootTest
@Import(MyContainers.class)
class MyIntegrationTest {
    // Test code here
}
 
@TestConfiguration(proxyBeanMethods = false)
class MyContainers {
    @Bean
    @ServiceConnection
    PostgreSQLContainer<?> postgreSQLContainer() {
        return new PostgreSQLContainer<>("postgres:15");
    }
}

Comparing the Approaches

When to Use Each Approach

Choose Spring TestContainers when:

• You want minimal boilerplate code
• You prefer a declarative, annotation-based approach
• You need to support both Spring and Spring Boot applications
• You’re working with supported container types (PostgreSQL, MySQL, Ollama)

Choose Spring Boot’s ServiceConnection when:

• You need more flexibility in container configuration
• You want to leverage Spring Boot’s native container support

Conclusion

Both approaches offer significant improvements over manual Testcontainers setup. Spring TestContainers provides a more concise, annotation-driven approach that works across Spring and Spring Boot applications, while Spring Boot’s ServiceConnection offers deeper integration with Spring Boot’s infrastructure and more flexibility in container configuration.

The choice between them often comes down to personal preference, specific project requirements, and which style (annotation-based vs. bean-based) better fits your testing philosophy.