Integration Testing Solved: Using Testcontainers for Disposable Database Instances in JUnit

testcontainers/testcontainers-java

Testcontainers is a Java library that allows you to easily spin up real services (like databases, message brokers, web browsers, etc.) as disposable Docker containers right from within your JUnit tests.

Instead of relying on

Mocks or in-memory services (which might not behave like the real thing).

A shared test environment (which often leads to data conflicts and flaky tests).

Manually setting up and tearing down complex local services.

You get an isolated, production-like environment for your tests, controlled entirely by code!

Testcontainers directly addresses some of the biggest pains in integration testing

No Test Pollution
Every test run uses a fresh, clean instance of the dependency (e.g., a database). This means one test's data won't interfere with another's, eliminating a major source of flakiness in your test suite.

Isolation in Parallel Builds
If multiple developers or CI/CD pipelines run tests simultaneously, each will get its own isolated set of containers, preventing conflicts.

Production Parity
You test against the exact same image (e.g., PostgreSQL version 15) that you use in production. This maximizes your confidence that what passes in your test will work in the real environment.

"Shift Left" Testing
You can run complex integration tests right from your IDE with a single click, just like unit tests. No need to wait for the CI pipeline to catch integration issues—you find them faster locally.

Automatic Setup and Cleanup
Testcontainers handles the entire lifecycle
starting the container, waiting until it's ready (using clever Wait Strategies), and reliably cleaning it up afterward, even if the test process crashes.

Random Port Mapping
It automatically maps container ports to random available host ports, solving port conflict headaches on developer machines.

To use Testcontainers for Java, you need Docker installed and running on your machine.

You'll need to add dependencies to your build tool (e.g., Maven or Gradle).

Maven Example

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>VERSION_HERE</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <version>VERSION_HERE</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>VERSION_HERE</version>
    <scope>test</scope>
</dependency>

(Note
Always check the official documentation for the latest version number.)

The core principle is defining a container in your test code and letting Testcontainers manage it.

This example shows how to use a throwaway PostgreSQL database instance for a data access layer integration test using JUnit 5.

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

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

// The @Testcontainers annotation enables JUnit 5 integration
@Testcontainers
class MyDataAccessIntegrationTest {

    // Define the container. Testcontainers will manage its lifecycle.
    @Container
    private static final PostgreSQLContainer<?> postgresContainer = new PostgreSQLContainer<>("postgres:14-alpine")
        .withDatabaseName("testdb")
        .withUsername("testuser")
        .withPassword("testpass");

    @Test
    void testCanConnectAndExecuteQuery() throws Exception {
        // --- 1. Get Connection Details from the Container ---
        String jdbcUrl = postgresContainer.getJdbcUrl();
        String username = postgresContainer.getUsername();
        String password = postgresContainer.getPassword();

        // --- 2. Use those details to connect and test ---
        try (Connection connection = DriverManager.getConnection(jdbcUrl, username, password)) {
            Statement statement = connection.createStatement();
            
            // Create a table
            statement.execute("CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(100))");
            
            // Insert data
            statement.executeUpdate("INSERT INTO users (name) VALUES ('Alice')");

            // Query data
            ResultSet rs = statement.executeQuery("SELECT name FROM users WHERE name = 'Alice'");

            // Assert the result
            assert(rs.next());
            assert("Alice".equals(rs.getString("name")));
            assert(!rs.next()); // Ensure only one result
        }

        // --- 3. Automatic Cleanup ---
        // When this test class finishes, Testcontainers automatically stops and removes
        // the 'postgres:14-alpine' container, ensuring a clean state.
    }
}

In this code

The @Testcontainers and @Container annotations tell the JUnit framework to integrate with the Testcontainers lifecycle.

new PostgreSQLContainer<>("postgres:14-alpine") creates a container based on a specific PostgreSQL Docker image.

Inside the test, we use methods like getJdbcUrl(), getUsername(), and getPassword() to dynamically get the connection properties that point to the running container.

Your code then connects and runs its integration logic against the real database.

After the test, the container is destroyed, giving you a guarantee of isolation and a clean slate for the next test run.