Spring Boot 3.2 + Testcontainers: Reliable Integration Testing with Real Dependencies

Without Testcontainers, your integration tests might pass locally with H2 but fail in CI when connecting to a mismatched PostgreSQL version. Production database migrations succeed in development but break when applied to a different database engine.

Prerequisites

• Java 17 or later
• Spring Boot 3.2.x
• Docker Engine 24.0+ with Docker Compose
• JUnit Jupiter 5.9+
• Testcontainers 1.19.3

Configuring Testcontainers for Database Testing

Testcontainers provides disposable database instances for integration tests. Add these dependencies to your pom.xml:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.4</version>
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>1.19.3</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>postgresql</artifactId>
        <version>1.19.3</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Disable the default datasource in test configuration:

# src/test/resources/application.properties
spring.datasource.driver-class-name=org.testcontainers.jdbc.ContainerDatabaseDriver
spring.datasource.url=jdbc:tc:postgresql:15-alpine:///test?TC_DAEMON=true
spring.flyway.enabled=false

Writing a Containerized Integration Test

This test verifies database schema initialization using a real PostgreSQL instance. The container starts before tests and destroys itself afterward:

package com.example.orderservice;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.jdbc.core.JdbcTemplate;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import static org.assertj.core.api.Assertions.assertThat;

@Testcontainers
@SpringBootTest
class OrderRepositoryIntegrationTest {

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

    @Autowired
    private JdbcTemplate jdbcTemplate;

    @Test
    void should_connect_to_live_database() {
        Integer result = jdbcTemplate.queryForObject("SELECT 1", Integer.class);
        assertThat(result).isEqualTo(1);
    }
}

Run the test with Docker Desktop active. Testcontainers will download the PostgreSQL image on first execution and reuse it for subsequent runs.

Managing Container Lifecycles

Define a base test class to share containers across multiple test classes:

package com.example.shared;

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;

@Testcontainers
public abstract class BaseIntegrationTest {

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

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

Common Mistakes

Mistake 1: Non-static container field causing multiple instances

@Container // Missing static modifier
PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>();

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

Testcontainers requires static fields for class-level containers. Non-static fields create new containers per test method.

Mistake 2: Hardcoded JDBC URL in test properties

spring.datasource.url=jdbc:postgresql://localhost:5432/test

@DynamicPropertySource
static void registerProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", postgres::getJdbcUrl);
}

Hardcoded URLs bypass container networking. Use @DynamicPropertySource to inject runtime connection details.

Mistake 3: Missing container reuse configuration

new PostgreSQLContainer<>("postgres:15-alpine");

new PostgreSQLContainer<>("postgres:15-alpine")
    .withReuse(true);

Without reuse, Testcontainers destroys containers after each test class. Enable reuse in .testcontainers.properties and chain withReuse(true).

Summary

• Replace in-memory databases with Testcontainers-managed PostgreSQL instances using @Testcontainers and @Container
• Inject dynamic connection properties using @DynamicPropertySource registry
• Enable container reuse with .withReuse(true) and testcontainers.reuse.enable=true in .testcontainers.properties

The author publishes Spring Boot starter templates at https://gumroad.com