testcontainers

name	testcontainers
description	| Use when this capability is needed.

Testcontainers - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: testcontainers for comprehensive documentation.

When NOT to Use This Skill

• Unit Tests - Use junit with Mockito for fast isolated tests
• REST API Tests Only - Use rest-assured without containers if API is mocked
• Environments Without Docker - Use H2 or embedded databases
• CI with Limited Resources - Containers may be too heavy, use mocks
• Non-Java Projects - Check language-specific Testcontainers libraries

Setup Base

Maven Dependencies

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-testcontainers</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>
<!-- Database specific -->
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>mongodb</artifactId>
    <scope>test</scope>
</dependency>

Gradle Dependencies

testImplementation("org.springframework.boot:spring-boot-testcontainers")
testImplementation("org.testcontainers:junit-jupiter")
testImplementation("org.testcontainers:postgresql")
testImplementation("org.testcontainers:mongodb")

@ServiceConnection (Spring Boot 3.1+)

Pattern Raccomandato

@SpringBootTest
@Testcontainers
class MyIntegrationTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres =
        new PostgreSQLContainer<>("postgres:16-alpine");

    @Test
    void testWithDatabase() {
        // Connection auto-configured
    }
}

Container Supportati

Container	Maven Artifact	Connection Details
PostgreSQLContainer	postgresql	JDBC + R2DBC
MySQLContainer	mysql	JDBC + R2DBC
MariaDBContainer	mariadb	JDBC + R2DBC
MongoDBContainer	mongodb	MongoConnectionDetails
KafkaContainer	kafka	KafkaConnectionDetails
RedisContainer	-	RedisConnectionDetails
RabbitMQContainer	rabbitmq	RabbitConnectionDetails
ElasticsearchContainer	elasticsearch	ElasticsearchConnectionDetails
CassandraContainer	cassandra	CassandraConnectionDetails

GenericContainer con @ServiceConnection

@Container
@ServiceConnection(name = "redis")
static GenericContainer<?> redis =
    new GenericContainer<>("redis:7-alpine")
        .withExposedPorts(6379);

Lifecycle Management

Static Container (Shared across tests - RECOMMENDED)

@Testcontainers
class SharedContainerTest {

    @Container
    static PostgreSQLContainer<?> postgres =
        new PostgreSQLContainer<>("postgres:16-alpine");

    @Test
    void test1() { /* same container */ }

    @Test
    void test2() { /* same container */ }
}

Spring Bean Container (Best lifecycle control)

@TestConfiguration(proxyBeanMethods = false)
class TestContainersConfig {

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

@SpringBootTest
@Import(TestContainersConfig.class)
class ManagedContainerTest {
    // Container lifecycle managed by Spring
    // Started before beans, stopped after beans
}

Container Reuse (Development)

static PostgreSQLContainer<?> postgres =
    new PostgreSQLContainer<>("postgres:16-alpine")
        .withReuse(true);

Richiede in ~/.testcontainers.properties:

testcontainers.reuse.enable=true

Database Containers

PostgreSQL

@Container
@ServiceConnection
static PostgreSQLContainer<?> postgres =
    new PostgreSQLContainer<>("postgres:16-alpine")
        .withDatabaseName("testdb")
        .withUsername("test")
        .withPassword("test")
        .withInitScript("init.sql");

MongoDB

@Container
@ServiceConnection
static MongoDBContainer mongo =
    new MongoDBContainer("mongo:7.0")
        .withSharding();

MySQL

@Container
@ServiceConnection
static MySQLContainer<?> mysql =
    new MySQLContainer<>("mysql:8.0")
        .withDatabaseName("testdb")
        .withUsername("test")
        .withPassword("test");

Messaging Containers

Kafka

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

RabbitMQ

@Container
@ServiceConnection
static RabbitMQContainer rabbitmq =
    new RabbitMQContainer("rabbitmq:3.12-management")
        .withExposedPorts(5672, 15672);

Redis

@Container
@ServiceConnection
static GenericContainer<?> redis =
    new GenericContainer<>("redis:7-alpine")
        .withExposedPorts(6379);

Messaging Container Test Patterns

Dedicated skills: For comprehensive messaging test coverage, see messaging-testing-kafka, messaging-testing-rabbitmq, and messaging-testing.

Kafka: Produce → Consume → Assert

@SpringBootTest
@Testcontainers
class KafkaProduceConsumeTest {

    @Container
    @ServiceConnection
    static KafkaContainer kafka = new KafkaContainer(
        DockerImageName.parse("apache/kafka-native:3.8.0"));

    @Autowired
    private KafkaTemplate<String, OrderEvent> kafkaTemplate;

    @Autowired
    private OrderRepository orderRepository;

    @Test
    void shouldProcessOrderViaKafka() throws Exception {
        kafkaTemplate.send("orders", "key-1",
            new OrderEvent("123", "CREATED")).get(10, TimeUnit.SECONDS);

        await().atMost(Duration.ofSeconds(10))
            .untilAsserted(() ->
                assertThat(orderRepository.findById("123")).isPresent());
    }
}

RabbitMQ: Send → Listen → Assert

@SpringBootTest
@Testcontainers
class RabbitProduceConsumeTest {

    @Container
    @ServiceConnection
    static RabbitMQContainer rabbit = new RabbitMQContainer("rabbitmq:3.13-management");

    @Autowired
    private RabbitTemplate rabbitTemplate;

    @Autowired
    private OrderRepository orderRepository;

    @Test
    void shouldProcessOrderViaRabbit() {
        rabbitTemplate.convertAndSend("orders.exchange", "orders.created",
            new OrderEvent("456", "CREATED"));

        await().atMost(Duration.ofSeconds(10))
            .untilAsserted(() ->
                assertThat(orderRepository.findById("456")).isPresent());
    }
}

Redis Pub/Sub: Publish → Subscribe → Assert

@SpringBootTest
@Testcontainers
class RedisPubSubTest {

    @Container
    @ServiceConnection(name = "redis")
    static GenericContainer<?> redis =
        new GenericContainer<>("redis:7-alpine").withExposedPorts(6379);

    @Autowired
    private StringRedisTemplate redisTemplate;

    @Test
    void shouldPublishAndReceiveMessage() throws Exception {
        CountDownLatch latch = new CountDownLatch(1);
        List<String> received = new CopyOnWriteArrayList<>();

        RedisMessageListenerContainer container = new RedisMessageListenerContainer();
        container.setConnectionFactory(redisTemplate.getConnectionFactory());
        container.addMessageListener((message, pattern) -> {
            received.add(new String(message.getBody()));
            latch.countDown();
        }, new ChannelTopic("orders"));
        container.afterPropertiesSet();
        container.start();

        redisTemplate.convertAndSend("orders", "{\"orderId\":\"789\"}");

        assertThat(latch.await(5, TimeUnit.SECONDS)).isTrue();
        assertThat(received.get(0)).contains("789");
        container.stop();
    }
}

Legacy Pattern (@DynamicPropertySource)

@Testcontainers
@SpringBootTest
class LegacyTest {

    @Container
    static PostgreSQLContainer<?> postgres =
        new PostgreSQLContainer<>("postgres:16");

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

Network & Compose

Container Network

@Testcontainers
class NetworkTest {

    static Network network = Network.newNetwork();

    @Container
    static PostgreSQLContainer<?> postgres =
        new PostgreSQLContainer<>("postgres:16")
            .withNetwork(network)
            .withNetworkAliases("postgres");

    @Container
    static GenericContainer<?> app =
        new GenericContainer<>("myapp:latest")
            .withNetwork(network)
            .dependsOn(postgres)
            .withEnv("DATABASE_HOST", "postgres");
}

Docker Compose

@Testcontainers
class ComposeTest {

    @Container
    static DockerComposeContainer<?> compose =
        new DockerComposeContainer<>(new File("docker-compose-test.yml"))
            .withExposedService("postgres", 5432)
            .withExposedService("redis", 6379);

    @Test
    void test() {
        String host = compose.getServiceHost("postgres", 5432);
        int port = compose.getServicePort("postgres", 5432);
    }
}

Wait Strategies

new GenericContainer<>("custom-image")
    .waitingFor(Wait.forHttp("/health").forStatusCode(200))
    .waitingFor(Wait.forLogMessage(".*Started.*", 1))
    .waitingFor(Wait.forListeningPort())
    .withStartupTimeout(Duration.ofMinutes(2));

Best Practices

Do	Don't
Use static containers	Create container per test method
Use @ServiceConnection	Manual property configuration
Use Spring Bean lifecycle	JUnit lifecycle for app-dependent containers
Enable container reuse in dev	Start fresh containers every run
Use specific image tags	Use latest tag
Share containers via base class	Duplicate container declarations

Common Issues

Container not starting

// Check Docker is running
// Check image exists
// Increase startup timeout
.withStartupTimeout(Duration.ofMinutes(5))

Port conflicts

// Always use exposed port mapping
container.getMappedPort(5432)
// Never hardcode ports

Slow tests

// Enable reuse
.withReuse(true)
// Use lighter images (-alpine)
new PostgreSQLContainer<>("postgres:16-alpine")

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
Creating container per test method	Extremely slow	Use static containers shared across tests
Not using @ServiceConnection	Manual config duplication	Let Spring auto-configure from container
Using latest tag	Non-deterministic tests	Pin specific version (postgres:16-alpine)
No withReuse for local dev	Slow dev feedback loop	Enable reuse in ~/.testcontainers.properties
Hardcoded ports	Port conflicts	Use getMappedPort() for dynamic ports
Ignoring startup timeout	Tests hang	Set withStartupTimeout appropriately
Not cleaning up test data	Tests interfere with each other	Use @Transactional or manual cleanup

Quick Troubleshooting

Problem	Likely Cause	Solution
"Could not find image"	Docker not running or image unavailable	Start Docker, check image name
Container startup timeout	Image too large or slow startup	Increase timeout, use lighter images
Port already in use	Previous test didn't clean up	Use dynamic ports with getMappedPort()
Tests very slow	Starting containers every test	Use static containers
Connection refused	Using localhost instead of container host	Use container.getHost() and getMappedPort()
"@ServiceConnection not working"	Wrong Spring Boot version	Requires Spring Boot 3.1+, check version

Reference Documentation

• Testcontainers Official Docs
• Spring Boot Testcontainers

---

Source: claude-dev-suite/claude-dev-suite — distributed by TomeVault.