Testcontainers in Spring Boot: Real Database Integration Tests Without Mocks

In-memory databases and hand-rolled mocks give you fast tests, but they lie to you. H2 silently ignores PostgreSQL-specific SQL, and your mock UserRepository never tests the JPA query you spent an hour debugging. Testcontainers solves this by spinning up real Docker containers — PostgreSQL, Redis, Kafka, Elasticsearch — for the duration of your test suite and tearing them down afterward. This guide walks through the full Testcontainers setup for Spring Boot 3.x, from dependency configuration to parallel test execution in GitHub Actions CI.

Table of Contents

1. Why Testcontainers Over H2 and Mocks
2. Project Setup: Dependencies and Docker Requirements
3. PostgreSQL Integration Tests with @DataJpaTest
4. Singleton Container Pattern: Reusing Containers Across Tests
5. Kafka Integration Testing with EmbeddedKafka vs Testcontainers
6. Redis and Multi-Container Compose Tests
7. Spring Boot 3.1+ ServiceConnection and @ImportTestcontainers
8. Running Testcontainers in GitHub Actions CI/CD
9. Key Takeaways

<!-- pom.xml -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>testcontainers-bom</artifactId>
            <version>1.19.8</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Core Testcontainers -->
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <!-- PostgreSQL module -->
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>postgresql</artifactId>
        <scope>test</scope>
    </dependency>
    <!-- Kafka module -->
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>kafka</artifactId>
        <scope>test</scope>
    </dependency>
    <!-- Spring Boot test integration -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-testcontainers</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class OrderRepositoryTest {

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

    @Autowired
    private OrderRepository orderRepository;

    @Test
    void shouldPersistAndRetrieveOrderWithJsonbMetadata() {
        Order order = new Order();
        order.setStatus("PENDING");
        order.setMetadata("{\"source\": \"web\", \"promoCode\": \"SAVE10\"}"); // JSONB
        Order saved = orderRepository.save(order);

        Optional<Order> found = orderRepository.findById(saved.getId());

        assertThat(found).isPresent();
        assertThat(found.get().getMetadata()).contains("promoCode");
    }

    @Test
    void shouldFindOrdersByStatusUsingCustomQuery() {
        orderRepository.saveAll(List.of(
            new Order("PENDING", null),
            new Order("SHIPPED", null),
            new Order("PENDING", null)
        ));

        List<Order> pending = orderRepository.findByStatus("PENDING");

        assertThat(pending).hasSize(2);
    }
}

// Shared base class — all integration tests extend this
public abstract class AbstractIntegrationTest {

    @Container
    @ServiceConnection
    static final PostgreSQLContainer<?> POSTGRES =
            new PostgreSQLContainer<>("postgres:16-alpine")
                .withReuse(true); // enable container reuse across runs

    static {
        POSTGRES.start();
    }
}

// Test class — inherits the shared container
@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class ProductRepositoryTest extends AbstractIntegrationTest {

    @Autowired
    ProductRepository productRepository;

    @Test
    void shouldCountProductsByCategory() {
        // Container already running — no startup cost
        productRepository.saveAll(List.of(
            new Product("TV", "ELECTRONICS"),
            new Product("Shirt", "CLOTHING"),
            new Product("Phone", "ELECTRONICS")
        ));
        assertThat(productRepository.countByCategory("ELECTRONICS")).isEqualTo(2);
    }
}

@SpringBootTest
@Testcontainers
class OrderEventPublisherTest {

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

    @Autowired
    private OrderEventPublisher publisher;

    @Autowired
    private KafkaTemplate<String, OrderEvent> kafkaTemplate;

    @Test
    void shouldPublishOrderCreatedEventToKafka() throws Exception {
        CountDownLatch latch = new CountDownLatch(1);
        List<OrderEvent> received = new ArrayList<>();

        // Consumer listening on the orders topic
        kafkaTemplate.receive("orders", 0, 0, Duration.ofSeconds(5));

        publisher.publishOrderCreated(new OrderCreatedEvent("order-123", "user-456"));

        // Assert message arrived within 10 seconds
        boolean messageReceived = latch.await(10, TimeUnit.SECONDS);
        assertThat(messageReceived).isTrue();
        assertThat(received).extracting(OrderEvent::getOrderId).contains("order-123");
    }
}

@SpringBootTest
@Testcontainers
class CacheServiceTest {

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

    @Autowired
    private ProductCacheService cacheService;

    @Test
    void shouldCacheProductLookup() {
        cacheService.cacheProduct("prod-1", new Product("Laptop", 1299.00));

        Optional<Product> cached = cacheService.getCachedProduct("prod-1");

        assertThat(cached).isPresent();
        assertThat(cached.get().getName()).isEqualTo("Laptop");
    }

    @Test
    void shouldEvictCacheOnUpdate() {
        cacheService.cacheProduct("prod-2", new Product("Mouse", 29.99));
        cacheService.evict("prod-2");

        Optional<Product> cached = cacheService.getCachedProduct("prod-2");

        assertThat(cached).isEmpty();
    }
}

// Multi-container with Docker Compose
@Testcontainers
class FullStackIntegrationTest {

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

// Centralized container configuration
public class TestContainersConfig {

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

    @Bean
    @ServiceConnection
    RedisContainer redisContainer() {
        return new RedisContainer("redis:7.2-alpine");
    }
}

// Test class imports the shared config — no @Container declarations needed
@SpringBootTest
@ImportTestcontainers(TestContainersConfig.class)
class OrderServiceIntegrationTest {

    @Autowired
    private OrderService orderService;

    @Test
    void shouldCreateOrderAndPublishEvent() {
        OrderRequest req = new OrderRequest("user-1", List.of("sku-A", "sku-B"));
        Order order = orderService.createOrder(req);

        assertThat(order.getId()).isNotNull();
        assertThat(order.getStatus()).isEqualTo("PENDING");
    }
}

# .github/workflows/ci.yml
name: CI — Integration Tests

on: [push, pull_request]

jobs:
  integration-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: maven

      - name: Pull Docker images in parallel
        run: |
          docker pull postgres:16-alpine &
          docker pull redis:7.2-alpine &
          docker pull confluentinc/cp-kafka:7.6.1 &
          wait

      - name: Run integration tests
        run: mvn verify -Pfailsafe -T 2
        env:
          TESTCONTAINERS_RYUK_DISABLED: false

// Build a custom Postgres image with pgvector extension at test time
GenericContainer<?> customPostgres = new GenericContainer<>(
    new ImageFromDockerfile()
        .withDockerfileFromBuilder(builder ->
            builder
                .from("postgres:16-alpine")
                .run("apk add --no-cache build-base && "
                   + "cd /tmp && git clone https://github.com/pgvector/pgvector.git && "
                   + "cd pgvector && make && make install")
                .build()
        )
)
.withExposedPorts(5432)
.withEnv("POSTGRES_DB", "testdb")
.withEnv("POSTGRES_USER", "test")
.withEnv("POSTGRES_PASSWORD", "test")
.waitingFor(Wait.forListeningPort());

// Reference a pre-built image from a private registry
GenericContainer<?> internalService = new GenericContainer<>(
        DockerImageName.parse("registry.internal.example.com/inventory-service:latest"))
    .withExposedPorts(8080)
    .waitingFor(Wait.forHttp("/actuator/health").forStatusCode(200));

@Testcontainers
class OrderServiceIntegrationTest {

    static final Network NETWORK = Network.newNetwork();

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

    @Container
    static GenericContainer<?> inventoryService = new GenericContainer<>("inventory-service:test")
        .withNetwork(NETWORK)
        .withNetworkAliases("inventory")
        .withEnv("DB_URL", "jdbc:postgresql://postgres:5432/testdb")
        .dependsOn(postgres)
        .waitingFor(Wait.forHttp("/actuator/health").forStatusCode(200));

    @DynamicPropertySource
    static void configure(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        // The order service calls inventory via http://inventory:8080
        registry.add("inventory.service.url",
            () -> "http://inventory:" + inventoryService.getMappedPort(8080));
    }
}

# .github/workflows/ci.yml — integrate Testcontainers Cloud
steps:
  - name: Setup Testcontainers Cloud
    uses: atomicjar/testcontainers-cloud-setup-action@v1
    with:
      token: ${{ secrets.TC_CLOUD_TOKEN }}

  - name: Run integration tests
    run: mvn verify -Pfailsafe
    # DOCKER_HOST is automatically configured by the agent
    # No changes to test code required

<!-- Enable parallel test execution with Maven Surefire -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <!-- Run test classes in parallel across 4 JVM forks -->
        <forkCount>4</forkCount>
        <reuseForks>true</reuseForks>
        <parallel>classes</parallel>
        <threadCount>4</threadCount>
        <systemPropertyVariables>
            <surefire.forkNumber>${surefire.forkNumber}</surefire.forkNumber>
        </systemPropertyVariables>
    </configuration>
</plugin>

// Enable container reuse for local development
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
    .withReuse(true)   // Reuse across JVM restarts (requires ~/.testcontainers.properties)
    .withDatabaseName("testdb")
    .withUsername("test")
    .withPassword("test");

// ~/.testcontainers.properties  (developer machine only — not committed to source control)
testcontainers.reuse.enable=true

<!-- Add WireMock Testcontainers module -->
<dependency>
    <groupId>org.wiremock.integrations.testcontainers</groupId>
    <artifactId>wiremock-testcontainers-module</artifactId>
    <version>1.0-alpha-13</version>
    <scope>test</scope>
</dependency>

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

    @Container
    static WireMockContainer wireMock = new WireMockContainer("wiremock/wiremock:3.3.1")
        .withMappingFromResource("stubs/payment-success.json");

    @DynamicPropertySource
    static void configureWireMock(DynamicPropertyRegistry registry) {
        registry.add("payment.gateway.url", wireMock::getBaseUrl);
    }

    @Test
    void chargeCard_success_returnsConfirmation() {
        // Stub configured in src/test/resources/stubs/payment-success.json
        // OR configure programmatically:
        wireMock.stubFor(WireMock.post("/v1/charges")
            .withRequestBody(matchingJsonPath("$.amount"))
            .willReturn(aResponse()
                .withStatus(200)
                .withHeader("Content-Type", "application/json")
                .withBody("""
                    {"chargeId": "ch_test_123", "status": "succeeded"}
                    """)));

        PaymentResult result = paymentService.charge(new ChargeRequest("4111111111111111", 99.99));

        assertThat(result.status()).isEqualTo("succeeded");
        wireMock.verify(1, postRequestedFor(urlEqualTo("/v1/charges")));
    }

    @Test
    void chargeCard_gateway503_throwsPaymentException() {
        wireMock.stubFor(WireMock.post("/v1/charges")
            .willReturn(aResponse().withStatus(503).withFixedDelay(5_000)));

        assertThatThrownBy(() -> paymentService.charge(new ChargeRequest("4111111111111111", 99.99)))
            .isInstanceOf(PaymentGatewayException.class)
            .hasMessageContaining("gateway unavailable");
    }
}

Leave a Comment

Related Posts