Testcontainers (Postgres / Kafka / Redis)

Testcontainers is a Java library that allows you to run real databases and external services inside Docker containers during Spring Boot tests. Instead of using in-memory databases or mocks, Testcontainers helps you test applications in a production-like environment.

It is widely used for integration testing to ensure your application behaves the same way in testing as it does in production.

What Is Testcontainers?

Testcontainers automatically starts temporary Docker containers for required services—such as databases, message brokers, and caches—during test execution and shuts them down once tests complete.

This provides:

• Isolated test environments
• Clean state for every test run
• Zero manual setup or teardown
• Consistent behavior across local and CI environments

Example: How Testcontainers Works in a Test

The example below shows how Testcontainers starts a PostgreSQL Docker container automatically when the test runs.

@Testcontainers
@SpringBootTest
classUserRepositoryTest {

@Container
static PostgreSQLContainer<?> postgres =
newPostgreSQLContainer<>("postgres:15")
                    .withDatabaseName("testdb")
                    .withUsername("test")
                    .withPassword("test");

@Test
voidcontextLoads() {
// Testcontainers automatically:
// 1. Starts PostgreSQL in Docker
// 2. Runs the test
// 3. Stops and removes the container
    }
}

Why Use Testcontainers?

Testcontainers improves test reliability by using real infrastructure instead of mocks.

Key Benefits

• Uses real services, not in-memory databases
• Detects database- and vendor-specific issues early
• Ensures application behavior matches production environments
• Works smoothly with CI/CD pipelines
• Reduces bugs after deployment

Common Use Cases of Testcontainers

Testcontainers is commonly used to test applications with real infrastructure components instead of mocks or in-memory services. It helps ensure your application behaves correctly in production-like environments.

Testcontainers with PostgreSQL

PostgreSQL Testcontainers run a real Postgres database during tests, allowing accurate validation of database behavior.

What You Can Test

• SQL queries
• Indexes and constraints
• Transactions
• Schema migrations (Flyway / Liquibase)

PostgreSQL Testcontainer Example

@Testcontainers
@SpringBootTest
classUserRepositoryTest {

@Container
static PostgreSQLContainer<?> postgres =
newPostgreSQLContainer<>("postgres:15")
                    .withDatabaseName("testdb")
                    .withUsername("test")
                    .withPassword("test");

@DynamicPropertySource
staticvoidoverrideProps(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }
}

Testcontainers with Kafka

Kafka Testcontainers allow you to test event-driven architectures using a real Kafka broker.

Example: Kafka Testcontainer

@Container
static KafkaContainer kafka =
        new KafkaContainer(
            DockerImageName.parse("confluentinc/cp-kafka:7.5.0")
        );

registry.add(
    "spring.kafka.bootstrap-servers",
    kafka::getBootstrapServers
);

Testcontainers with Redis

Redis Testcontainers is used to test caching, session management, and distributed locking in Spring Boot applications.

Example: Redis Testcontainer

@Container
static GenericContainer<?> redis =
newGenericContainer<>("redis:7")
                .withExposedPorts(6379);

Maven Dependencies

<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>postgresql</artifactId>
<scope>test</scope>
</dependency>

Spring Boot 3.1+ (Recommended Setup)

Spring Boot 3.1+ provides automatic Testcontainers integration, reducing configuration overhead.

spring.testcontainers.enabled=true
spring.datasource.url=jdbc:tc:postgresql:15:///testdb

@Testcontainers
@SpringBootTest
classUserRepositoryIT {

@Container
static PostgreSQLContainer<?> postgres =
newPostgreSQLContainer<>("postgres:15");
}

Benefits

• Zero manual configuration
• Clean and fast setup
• Official Spring Boot support

Container Lifecycle

The container lifecycle in Testcontainers defines when containers start and stop during test execution. Choosing the right lifecycle helps balance test speed, isolation, and reliability.

Reusable Containers (Local Only)

Reusable containers allow Testcontainers to reuse the same Docker container across multiple test runs on your local machine. This significantly reduces test startup time during development.

Step 1: Enable reuse in configuration

Add the following line to your local Testcontainers configuration file:

testcontainers.reuse.enable=true

Step 2: Mark the container as reusable

.withReuse(true)

When to Use Testcontainers?

Use Testcontainers when:

• H2 or in-memory databases are not sufficient
• Database behavior differs by vendor
• Testing Kafka, Redis, or other external services
• Writing integration or system tests
• You need production-like test accuracy

When NOT to Use Testcontainers?

Avoid Testcontainers for:

• Unit tests (containers are slower)
• Simple repository tests where H2 is enough
• Pure business logic tests using Mockito

Testcontainers vs In-Memory Database

Common Mistakes

• Docker not installed or running
• Using non-static containers (slow tests)
• Mixing H2 and real DB assumptions
• Parallel tests without proper isolation

Key Takeaways

• Testcontainers provides real infrastructure for testing
• Supports PostgreSQL, Kafka, Redis, and many more
• Ideal for integration and system testing
• Improves test reliability and production confidence
• Helps catch issues before deployment

Conclusion

Testcontainers enables real, production-like integration testing in Spring Boot by running actual services like PostgreSQL, Kafka, and Redis in Docker. It helps catch real-world issues early, ensures consistent behavior across environments, and makes applications more reliable and production-ready.