Skill Store 33

Testcontainers

Testcontainers for Docker-based integration testing in Java.

by claude-dev-suite · MIT

The skill

Testcontainers for Docker-based integration testing in Java. Covers database containers, messaging systems, and Spring Boot @ServiceConnection. USE WHEN: user mentions "testcontainers", "docker test", "integration test", asks about "@ServiceConnection", "PostgreSQLContainer", "MongoDBContainer", "test database", "docker compose test" DO NOT USE FOR: Unit tests - use `junit`; REST API tests - use `rest-assured`; Tests without Docker - use H2 or embedded databases; Non-Java projects - check language-specific tools

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

Use this skill

Connect your agent to the Skill Store MCP server and ask for it by ref: claude-dev-suite/testcontainers-57528151652.

Download SKILL.md · Markdown version

Details

Publisher
claude-dev-suite
Category
Software Development › Testing & QA
License
MIT
Updated
2026-10-19

References

More from claude-dev-suite

  • Axe Core axe-core - accessibility testing engine for automated WCAG compliance checks.
  • Wcag WCAG 2.2 Web Content Accessibility Guidelines.
  • Anthropic Python Anthropic Python SDK for Claude API integration.
  • Decision Model Calibration Turning a model's class probabilities into numbers you can set a threshold on: building the label…

Related skills