Integration Testing with Testcontainers: Practical Spring Boot Guide

May 13, 2026··

11 min read

Integration Testing with Testcontainers: Practical Spring Boot Guide

This guide is a deep dive into using Testcontainers for integration testing Spring Boot applications. It covers the why and how, theory and best practices, concrete code examples (PostgreSQL, Kafka, Docker Compose), CI considerations, debugging, and future directions.

Table of contents

Why use Testcontainers?
Theory and testing strategy
Key Testcontainers concepts
Getting started: dependencies and environment
Example: Spring Boot + PostgreSQL (complete)
Example: Spring Boot + Kafka
Docker Compose with Testcontainers
Common patterns and recipes
Performance, stability, and resource management
CI/CD integration (GitHub Actions / GitLab)
Troubleshooting common errors
Best practices and anti-patterns
Future trends and alternatives
Summary

Why use Testcontainers?

Realism: Run actual database, message broker, or cloud-mock images in containers instead of in-memory or heavily mocked components.
Isolation and reproducibility: Tests run against disposable containers with known images and configurations.
Parity with production: Close environment parity reduces "works on my machine" and surfaces compatibility issues early.
Flexibility: Start different services (DB, Kafka, Redis, S3, etc.) with arbitrary versions and configs.

Theory and testing strategy

Integration testing sits between unit tests and end-to-end/system tests. Goals:

Validate interactions between components (e.g., Spring Data repositories and real DB).
Test external integrations with realistic behavior (transactions, networking, broker semantics).
Provide fast feedback while maintaining reasonable fidelity.

Test strategy using Testcontainers:

Unit tests: lightweight, pure JVM, no containers. Fast.
Integration tests (Testcontainers): run a small set of tests that spin up only what you need (DB, message broker).
End-to-end tests: full system in environment (maybe Kubernetes), longer-running.

Key Testcontainers concepts

Container modules: Core module plus preconfigured containers (PostgreSQLContainer, KafkaContainer, RabbitMQContainer, LocalStackContainer, etc.).
GenericContainer: use for custom images or services not included.
DockerComposeContainer: spin up multiple services defined in docker-compose.yml.
@Testcontainers / @Container (JUnit 5): manage lifecycle from JUnit.
DynamicPropertySource: dynamically inject container properties into Spring context at test startup.
Networks: Docker networks for multi-container interactions.
Wait strategies: Wait.forListeningPort(), Wait.forLogMessage(), Wait.forHttp(), withStartupTimeout().
Reuse/cleanup: Ryuk is used to manage and cleanup containers; reuse mode exists for speed but has trade-offs.
Per-test vs shared containers: static @Container => class-level shared container; non-static => per-test.

Getting started: dependencies and environment

Maven (pom.xml) essentials:

Plain Text

<dependencies>
  <!-- Spring Boot test -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
  </dependency>

  <!-- Testcontainers core -->
  <dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <scope>test</scope>
  </dependency>

  <!-- Add container modules you need -->
  <dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>kafka</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

Gradle (Groovy):

Plain Text

testImplementation 'org.springframework.boot:spring-boot-starter-test'
testImplementation 'org.testcontainers:testcontainers'
testImplementation 'org.testcontainers:postgresql'
testImplementation 'org.testcontainers:kafka'

Environment:

Docker Engine accessible from the build agent (local dev machine or CI).
For mac/arm64 (Apple Silicon), prefer multi-arch images or set the platform accordingly.
Allow Testcontainers to start/stop containers (Docker socket access).

Example: Spring Boot + PostgreSQL (complete)

This is a typical pattern: start PostgreSQL in a container and wire its JDBC URL into Spring Boot tests via @DynamicPropertySource.

Test dependencies: testcontainers, postgresql module (see above).

Sample repository layout (tests):

src/test/java/.../PostgresIntegrationTest.java
src/test/resources/application-test.yml (optional)

Entity / repository setup: assume standard Spring Data JPA with datasource auto-configured.

Test class (JUnit 5 + Spring Boot):

Plain Text

package com.example;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.web.client.TestRestTemplate;
import static org.assertj.core.api.Assertions.assertThat;

@Testcontainers
@SpringBootTest
public class PostgresIntegrationTest {

    @Container
    public static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:14-alpine")
        .withDatabaseName("testdb")
        .withUsername("test")
        .withPassword("test");

    @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);
    }

    @Autowired
    private UserRepository userRepository;

    @Test
    void repositorySavesAndLoads() {
        User u = new User();
        u.setName("Alice");
        userRepository.save(u);

        assertThat(userRepository.findByName("Alice")).isNotEmpty();
    }
}

Notes:

DynamicPropertySource binds container values before the Spring context is initialized.
Use static container field to share the container across test methods in the class (and to start it once).
If you need per-test isolation, make the container non-static (it will be restarted per test method).

Test with Spring Boot Web layer:

Use @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) and TestRestTemplate or WebTestClient.
Use @LocalServerPort to access the port or rely on TestRestTemplate autowiring.

DB schema and migrations:

Use Flyway/Liquibase (Spring Boot auto-run migrations) — they execute against the container DB when Spring starts.
Alternatively, run SQL scripts via TestExecutionListeners or @Sql.

Example: Spring Boot + Kafka

Start a Kafka broker for event-driven application testing.

Testcontainers Kafka example:

Plain Text

import org.testcontainers.containers.KafkaContainer;
import org.testcontainers.utility.DockerImageName;

@Testcontainers
@SpringBootTest
public class KafkaIntegrationTest {

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

    @DynamicPropertySource
    static void configureKafka(DynamicPropertyRegistry registry) {
        registry.add("spring.kafka.bootstrap-servers", kafka::getBootstrapServers);
    }

    @Autowired
    private KafkaTemplate<String, String> template;

    @Autowired
    private ConsumerService consumer;

    @Test
    void sendAndReceive() {
        template.send("my-topic", "key", "hello");
        // Assert that consumer processed or use consumer polling
    }
}

Notes:

KafkaContainer exposes getBootstrapServers() which you inject into Spring properties to make your KafkaProducer/Consumer connect to the container.
You may need to wait for topics to exist; create topics programmatically or configure client auto-creation.

Docker Compose with Testcontainers

Testcontainers can run a docker-compose file and expose services to tests. Useful when you have multiple services to start together.

docker-compose.yml (src/test/resources/docker-compose.yml):

YAML

version: '3.8'
services:
  db:
    image: postgres:14-alpine
    environment:
      POSTGRES_DB: testdb
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
    ports:
      - "5432"
  redis:
    image: redis:6-alpine
    ports:
      - "6379"

Test:

Plain Text

import org.testcontainers.containers.DockerComposeContainer;
import org.testcontainers.containers.wait.strategy.Wait;

@Container
public static DockerComposeContainer<?> compose =
    new DockerComposeContainer<>(new File("src/test/resources/docker-compose.yml"))
        .withExposedService("db_1", 5432, Wait.forListeningPort())
        .withExposedService("redis_1", 6379, Wait.forListeningPort());

@DynamicPropertySource
static void dynamicProperties(DynamicPropertyRegistry registry) {
    String jdbcUrl = "jdbc:postgresql://" + compose.getServiceHost("db_1", 5432)
        + ":" + compose.getServicePort("db_1", 5432) + "/testdb";
    registry.add("spring.datasource.url", () -> jdbcUrl);
    registry.add("spring.redis.host", () -> compose.getServiceHost("redis_1", 6379));
    registry.add("spring.redis.port", () -> compose.getServicePort("redis_1", 6379).toString());
}

Notes:

Compose service names may be suffixed by indices (db_1). Use compose.getServiceHost/Port to query.
DockerComposeContainer is convenient for multi-service stacks; for tighter control use separate Testcontainers per service and share a Network.

Common patterns and recipes

Shared container for entire test suite: use static container(s) in a dedicated @TestConfiguration or base test class. Careful with state — ensure each test cleans up DB state.
Per-test isolation: non-static container fields or manual cleanup. More costly but safe for stateful tests.
Reusing containers across test runs: enable Testcontainers reuse (fast) with ~/.testcontainers.properties: testcontainers.reuse.enable=true And set environment variable TESTCONTAINERS_RYUK_DISABLED=true to disable Ryuk. Security implications; recommended only in trusted environments.
Use @DynamicPropertySource for injecting runtime container values into Spring config; avoid hardcoding ports.
Use lighter images (alpine-based) and pinned versions to speed startup and improve reproducibility.
Use wait strategies for services that take longer to start: withStartupTimeout and Wait.forLogMessage or Wait.forHttp.

Performance, stability, and resource management

Startup time: container startup is the major cost. Strategies:
- Start shared container per test class or suite (static @Container).
- Reuse containers across runs in local dev (but be careful in CI).
- Use cached images; CI should cache Docker layers or use pre-cached runner images.
Parallel tests: avoid starting many containers simultaneously; it can exhaust resources. Configure test concurrency accordingly.
Memory/CPU: allocate adequate resources to Docker daemon and runners. Containers inherit host constraints.
Image size and architecture: use small images and ensure correct CPU architecture (x86_64 vs arm64). Use proper images or set platform.

CI/CD integration (GitHub Actions / GitLab)

GitHub Actions (simple workflow snippet):

YAML

name: Java CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      docker:
        image: docker:20.10.16
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
      - name: Start Docker
        uses: docker/setup-buildx-action@v2
      - name: Build and test
        run: ./mvnw -DskipTests=false test -B

Notes for CI:

On GitHub-hosted runners Docker is available; ensure no privileged mode required unless using DinD.
On GitLab CI, to use Docker-in-Docker, you may need privileged: true and proper services (docker:dind).
Make sure CI runners have adequate resources (memory/CPU) and that images are compatible with runner architecture.
If using Testcontainers reuse in CI, be cautious — ephemeral containers are preferable for test repeatability.

Troubleshooting common errors

No Docker environment found / IllegalStateException: Docker not available:
- Ensure Docker daemon running and accessible from test process (correct user permissions).
- On CI, enable Docker-in-Docker or use runners with Docker.
Ryuk errors / Cannot connect to / permission denied:
- Ryuk manages containers; if Ryuk fails or is blocked by firewall/selinux, disable or fix Docker config. Alternatively set TESTCONTAINERS_RYUK_DISABLED=true (not recommended for general use).
Port already in use / Bind errors:
- Avoid binding fixed host ports; use container-provided ports (getJdbcUrl, getMappedPort).
Tests flaky due to startup time:
- Increase startup timeout with withStartupTimeout() and use explicit Wait strategies.
Image/architecture mismatch on Apple Silicon:
- Use multi-arch images or explicit platform in image name (e.g., DockerImageName.parse("postgres:14").withArchitecture("amd64")) — but be careful and prefer multi-arch official images.

Best practices and anti-patterns

Best practices:

Use @DynamicPropertySource to inject container values.
Pin container image versions for reproducibility.
Share containers when safe; prefer per-class static containers over per-method where appropriate.
Use integration tests for behavior that cannot be reliably simulated by unit tests.
Clean DB state between tests (truncate tables or use transactions with rollback depending on test style).
Capture container logs on failure to aid debugging.
Limit test scope: keep expensive container tests focused and small; reserve heavy end-to-end tests to a separate pipeline stage.

Anti-patterns:

Starting huge stacks for every test method.
Relying on fixed host ports in tests.
Disabling Ryuk and leaving containers running forever in shared environments.
Using Testcontainers as a substitute for proper unit tests — integration tests should complement, not replace, unit tests.

Advanced features

Custom wait strategies: implement or compose Wait strategies for better stability.
Networks: Network.newNetwork() to connect containers in the same Docker network.
Init scripts: configure container initialization (SQL files for DB containers via withInitScript()).
Custom images: extend GenericContainer for tailored startup commands and volume mounts.
LocalStackContainer: simulate AWS services (S3, SQS, DynamoDB).
Testcontainers JDBC module: allows JVM-level DataSource that starts containers automatically (useful in some setups).
Remote Docker / Docker over TCP: configure Testcontainers to use DOCKER_HOST.

Future trends and alternatives

Testcontainers will likely continue to be a standard for JVM-based integration testing due to its balance of realism and test automation convenience.
Alternatives:
- Embedded-mode libraries (embedded Kafka, embedded Redis) — faster but provide less fidelity.
- Service virtualization and dedicated test environments (Kubernetes-based test clusters).
- Contract testing (Pact) for API interactions.
For large microservices landscapes, moving tests to ephemeral Kubernetes clusters (e.g., KinD, kind + Helm) may provide better integration parity with production, but with higher complexity and cost.

Complete, realistic example (Spring Boot + REST + Postgres)

application-test.yml (optional):

YAML

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    hikari:
      maximum-pool-size: 5
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        show_sql: false

Test class:

Plain Text

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Testcontainers
public class UserApiIntegrationTest {

    @Container
    private static final PostgreSQLContainer<?> postgres = 
        new PostgreSQLContainer<>("postgres:14-alpine")
        .withDatabaseName("app_test")
        .withUsername("user")
        .withPassword("pass");

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

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void createUser_thenReadBack() {
        UserDto create = new UserDto(null, "[email protected]", "Bob");
        ResponseEntity<UserDto> createResponse = 
            restTemplate.postForEntity("/api/users", create, UserDto.class);
        assertThat(createResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        UserDto saved = createResponse.getBody();
        assertThat(saved.getId()).isNotNull();

        ResponseEntity<UserDto> getResponse = restTemplate.getForEntity("/api/users/" + saved.getId(), UserDto.class);
        assertThat(getResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(getResponse.getBody().getEmail()).isEqualTo("[email protected]");
    }
}

This pattern combines: containerized DB, Spring Boot test server on a random port, and HTTP verification (black-box style) against a realistic backing DB.

Conclusion

Testcontainers enables robust, maintainable integration testing for Spring Boot applications by providing real containerized services, high configurability, and straightforward JUnit integration. Use it to raise confidence in database migrations, message processing, and external integrations. Balance realism and speed: keep unit tests plentiful and use Testcontainers selectively for scenarios that truly need a real service. In CI, ensure Docker access, resource sizing, and image caching to keep feedback fast and reliable.

If you want, I can:

Provide a fully working sample Git repository with Maven/Gradle, Dockerfiles, and test classes.
Create a concise checklist for migrating existing integration tests to Testcontainers.
Provide CI workflow templates (GitHub Actions or GitLab CI) tailored to your environment. Which would you prefer?