How to Use Testcontainers with Spring Boot for Integration Testing

Use Testcontainers in Spring Boot by adding the dependency, annotating your test class with @Testcontainers, and defining container fields with @Container. This lets you run Docker containers (like databases) automatically during tests for realistic integration testing.

Syntax

To use Testcontainers in Spring Boot tests, you typically:

• Add the Testcontainers dependency to your build.gradle or pom.xml.
• Annotate your test class with @Testcontainers to enable container lifecycle management.
• Declare container fields with @Container to start and stop containers automatically.
• Use container properties (like JDBC URL) to configure your Spring Boot datasource during tests.

java

import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@Testcontainers
public class MyIntegrationTest {

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

    // Your test methods here
}

Example

This example shows a Spring Boot integration test using Testcontainers to start a PostgreSQL database container. The test uses the container's JDBC URL to connect and verify the database is running.

java

package com.example.demo;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.beans.factory.annotation.Autowired;
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;

@SpringBootTest
@Testcontainers
public class DemoApplicationTests {

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

    @Autowired
    private JdbcTemplate jdbcTemplate;

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

Output

Test passes if the database container starts and query returns 1.

Common Pitfalls

Common mistakes when using Testcontainers with Spring Boot include:

• Not annotating the test class with @Testcontainers, so containers don't start automatically.
• Declaring container fields without static when using JUnit Jupiter, causing lifecycle issues.
• Not configuring Spring datasource properties to use container URLs, leading to connection failures.
• Forgetting to add the required Testcontainers dependencies for the specific container (e.g., PostgreSQL).

java

/* Wrong: Missing @Testcontainers annotation and non-static container */
public class WrongTest {
    @Container
    public PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15.2-alpine");
}

/* Right: Add @Testcontainers and make container static */
@Testcontainers
public class RightTest {
    @Container
    public static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15.2-alpine");
}

Quick Reference

Summary tips for using Testcontainers with Spring Boot:

• Always add @Testcontainers on your test class.
• Declare containers as static fields with @Container.
• Use the container's JDBC URL to configure Spring datasource properties in tests.
• Add the correct Testcontainers dependencies for your database or service.
• Use Docker Desktop or a compatible Docker environment running locally.

Key Takeaways

Annotate your test class with @Testcontainers to manage container lifecycle automatically.

Declare container fields as static and annotate them with @Container for proper startup and shutdown.

Configure Spring Boot datasource properties to use container-provided URLs during tests.

Add the correct Testcontainers dependencies for your target container (e.g., PostgreSQL).

Ensure Docker is running locally to allow Testcontainers to start containers during tests.