Mastering Testcontainers: Real Database Integration Testing in Java

Introduction

Integration testing—the process of verifying interactions between different components of your system—is a critical part of building robust software. However, it often comes with significant challenges, especially when databases are involved. Traditionally, developers have resorted to in-memory databases like H2, mocking frameworks, or complex, shared test environments. While these approaches offer some benefits, they frequently fall short in replicating real-world scenarios, leading to brittle tests, environment-specific bugs, and a false sense of security.

Enter Testcontainers, a powerful Java library that changes the game. Testcontainers allows you to spin up lightweight, throwaway instances of databases, message brokers, web browsers, and practically any other Docker-compatible service directly from your tests. This means you can run your integration tests against a real PostgreSQL, MySQL, or Oracle database, ensuring your code behaves exactly as it would in production. This guide will take you on a deep dive into mastering Testcontainers for Java, focusing specifically on real database integration.

Prerequisites

Before we begin, ensure you have the following installed and configured:

Java Development Kit (JDK): Version 11 or higher.
Maven or Gradle: For dependency management.
Docker Desktop (or Docker Engine): Testcontainers relies heavily on Docker to run its containers. Ensure Docker is running on your machine.
Basic understanding of JUnit 5: Our examples will use JUnit 5 for testing.
IDE: IntelliJ IDEA, VS Code, or Eclipse for development.

The Problem with Traditional Integration Testing

Let's first understand why Testcontainers became such a game-changer by looking at the limitations of older approaches:

1. In-Memory Databases (e.g., H2)

SQL Dialect Differences: H2's SQL dialect, while similar, is not identical to production databases like PostgreSQL or Oracle. Subtle differences in functions, data types, or query syntax can lead to tests passing in H2 but failing in production.
Missing Features: Production-specific features (e.g., specific JSON operators in PostgreSQL, advanced indexing strategies) are often not supported or behave differently in H2.
Performance Characteristics: H2's performance profile is vastly different. Issues related to query optimization or transaction isolation might not surface.
Schema Migration Tools: While Flyway or Liquibase can target H2, their behavior with specific database types might differ.

2. Mocking Database Interactions

Partial Testing: Mocking only verifies that your code calls the data access layer correctly, not that the data access layer actually works with the database.
Complex Mocks: Creating realistic mocks for complex data access patterns (e.g., transactions, lazy loading, cascading operations) can be incredibly difficult and error-prone.
Maintenance Overhead: Mocks need to be updated whenever the database schema or data access logic changes, leading to fragile tests.

3. Shared Test Environments

Isolation Issues: Multiple developers or CI/CD pipelines running tests concurrently against a single shared database can lead to data conflicts, non-deterministic test results, and flaky tests.
Setup Complexity: Setting up and maintaining a dedicated test database server is often a manual, time-consuming process.
Version Drift: The shared database might not always be running the exact version or configuration as your production environment.

Testcontainers addresses all these issues by providing isolated, real database instances for every test run.

What is Testcontainers?

Testcontainers is an open-source Java library that provides a set of lightweight, throwaway instances of common databases, web browsers, and other services that can run in Docker containers. It allows developers to write integration tests that are:

Realistic: Tests run against the actual database technology used in production.
Isolated: Each test (or test class) can have its own dedicated, clean database instance, eliminating side effects.
Consistent: Tests run the same way on any machine with Docker installed, from a developer's laptop to a CI/CD server.
Fast: Containers start quickly, and Testcontainers optimizes resource usage.
Easy to Use: Seamless integration with popular testing frameworks like JUnit 5.

At its core, Testcontainers is a Java library that communicates with the Docker daemon. When you request a container (e.g., a PostgreSQL database), Testcontainers:

Pulls the specified Docker image (if not already present).
Starts a new container instance.
Waits for the container to become healthy and ready.
Provides connection details (JDBC URL, port, credentials).
Shuts down and removes the container after the tests complete.

Getting Started with Testcontainers (Maven/Gradle Setup)

To begin, you need to add the necessary Testcontainers dependencies to your project. We'll use JUnit 5 and the PostgreSQL module as an example.

Maven

Add the following to your pom.xml:

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>1.19.7</version> <!-- Use the latest stable version -->
    <scope>test</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <version>1.19.7</version> <!-- Must match junit-jupiter version -->
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.3</version> <!-- Your JDBC driver version -->
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>5.10.2</version> <!-- Your JUnit 5 version -->
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.10.2</version> <!-- Your JUnit 5 version -->
    <scope>test</scope>
</dependency>

Gradle

Add the following to your build.gradle:

dependencies {
    testImplementation 'org.testcontainers:junit-jupiter:1.19.7' // Use the latest stable version
    testImplementation 'org.testcontainers:postgresql:1.19.7'   // Must match junit-jupiter version
    testImplementation 'org.postgresql:postgresql:42.7.3'       // Your JDBC driver version
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.2'
    testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.10.2'
}

Remember to replace the version numbers with the latest stable releases.

Basic Database Test with PostgreSQL

Let's write a simple JUnit 5 test that spins up a PostgreSQL database and performs a basic query.

package com.example.testcontainers;

import org.junit.jupiter.api.DisplayName;
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;

import static org.junit.jupiter.api.Assertions.assertTrue;

@Testcontainers
@DisplayName("Basic PostgreSQL Testcontainers Example")
class SimplePostgreSqlTest {

    // Define a PostgreSQL container. Testcontainers will automatically start and stop it.
    @Container
    private static PostgreSQLContainer<?> postgreSQLContainer = new PostgreSQLContainer<>("postgres:13")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @Test
    void testPostgreSqlContainerConnectivity() throws Exception {
        // Get connection details from the running container
        String jdbcUrl = postgreSQLContainer.getJdbcUrl();
        String username = postgreSQLContainer.getUsername();
        String password = postgreSQLContainer.getPassword();

        // Use a standard JDBC connection to interact with the database
        try (Connection connection = DriverManager.getConnection(jdbcUrl, username, password);
             Statement statement = connection.createStatement()) {

            // Execute a simple query to verify connectivity
            ResultSet resultSet = statement.executeQuery("SELECT 1");
            assertTrue(resultSet.next());
            assertTrue(resultSet.getInt(1) == 1);

            // Create a table and insert data
            statement.executeUpdate("CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(255))");
            statement.executeUpdate("INSERT INTO users (name) VALUES ('Alice')");
            statement.executeUpdate("INSERT INTO users (name) VALUES ('Bob')");

            // Query the data
            ResultSet userResultSet = statement.executeQuery("SELECT COUNT(*) FROM users");
            assertTrue(userResultSet.next());
            assertTrue(userResultSet.getInt(1) == 2);

            System.out.println("Successfully connected to PostgreSQL and performed operations!");
        }
    }
}

Explanation:

@Testcontainers: This JUnit 5 extension enables Testcontainers integration for the test class.
@Container: This annotation tells Testcontainers to manage the lifecycle of the postgreSQLContainer field. It will start the container before any test methods run and stop it after all tests in the class complete.
new PostgreSQLContainer<>("postgres:13"): We instantiate a PostgreSQLContainer specifying the Docker image to use (here, postgres:13). Testcontainers handles pulling this image if it's not local.
.withDatabaseName("testdb"), .withUsername("test"), .withPassword("test"): These methods configure the database name and credentials within the container.
postgreSQLContainer.getJdbcUrl(), .getUsername(), .getPassword(): After the container starts, Testcontainers provides methods to retrieve the dynamically assigned port and connection details, which you can then use with your standard JDBC driver.

This setup ensures that each time SimplePostgreSqlTest runs, it gets a fresh, isolated PostgreSQL instance.

Managing Container Lifecycles (Static vs. Instance)

Testcontainers offers flexibility in how you manage container lifecycles, primarily through static versus instance fields.

1. Static Container (Shared Across Test Methods)

When a @Container field is declared static, Testcontainers starts the container once before all tests in the class run and stops it once all tests in the class have finished. This is generally faster as the container only starts and stops once, but it means all test methods share the same container instance.

package com.example.testcontainers;

import org.junit.jupiter.api.DisplayName;
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.Statement;
import java.sql.ResultSet;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Testcontainers
@DisplayName("Static PostgreSQL Container - Shared state")
class StaticPostgreSqlTest {

    @Container
    private static PostgreSQLContainer<?> postgreSQLContainer = new PostgreSQLContainer<>("postgres:13")
            .withDatabaseName("static_testdb")
            .withUsername("static_user")
            .withPassword("static_pass");

    // This method will run before each test, ensuring a clean schema if needed
    // For a static container, you might want to clean data, but not recreate schema
    // or use withInitScript() to create schema once.

    @Test
    void testInsertFirstUser() throws Exception {
        try (Connection connection = DriverManager.getConnection(postgreSQLContainer.getJdbcUrl(), postgreSQLContainer.getUsername(), postgreSQLContainer.getPassword());
             Statement statement = connection.createStatement()) {
            statement.executeUpdate("CREATE TABLE IF NOT EXISTS shared_users (id SERIAL PRIMARY KEY, name VARCHAR(255))");
            statement.executeUpdate("INSERT INTO shared_users (name) VALUES ('Charlie')");

            ResultSet rs = statement.executeQuery("SELECT COUNT(*) FROM shared_users");
            assertTrue(rs.next());
            assertEquals(1, rs.getInt(1));
        }
    }

    @Test
    void testInsertSecondUser() throws Exception {
        try (Connection connection = DriverManager.getConnection(postgreSQLContainer.getJdbcUrl(), postgreSQLContainer.getUsername(), postgreSQLContainer.getPassword());
             Statement statement = connection.createStatement()) {
            // This test sees data from the previous test if schema not reset
            statement.executeUpdate("INSERT INTO shared_users (name) VALUES ('Diana')");

            ResultSet rs = statement.executeQuery("SELECT COUNT(*) FROM shared_users");
            assertTrue(rs.next());
            // This will be 2 if the previous test's data persists
            assertEquals(2, rs.getInt(1));
        }
    }
}

Tradeoffs of Static Containers:

Pros: Faster test execution due to fewer container startups/shutdowns. Good for tests that don't modify the database state significantly or where setup is complex but data can be easily reset (e.g., using transactions).
Cons: Potential for test isolation issues if tests modify the shared database state without proper cleanup between tests. Requires careful management of data.

2. Instance Container (New Container per Test Method)

If the @Container field is not static, Testcontainers will start a new container instance for each test method in the class and stop it after that method completes. This provides maximum isolation but can be slower due to repeated container lifecycles.

package com.example.testcontainers;

import org.junit.jupiter.api.DisplayName;
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.Statement;
import java.sql.ResultSet;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Testcontainers
@DisplayName("Instance PostgreSQL Container - Isolated state")
class InstancePostgreSqlTest {

    // Note: No 'static' keyword. A new container will be created for each test method.
    @Container
    PostgreSQLContainer<?> postgreSQLContainer = new PostgreSQLContainer<>("postgres:13")
            .withDatabaseName("instance_testdb")
            .withUsername("instance_user")
            .withPassword("instance_pass");

    @Test
    void testFirstUserInsert() throws Exception {
        try (Connection connection = DriverManager.getConnection(postgreSQLContainer.getJdbcUrl(), postgreSQLContainer.getUsername(), postgreSQLContainer.getPassword());
             Statement statement = connection.createStatement()) {
            statement.executeUpdate("CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(255))");
            statement.executeUpdate("INSERT INTO users (name) VALUES ('Frank')");

            ResultSet rs = statement.executeQuery("SELECT COUNT(*) FROM users");
            assertTrue(rs.next());
            assertEquals(1, rs.getInt(1));
        }
    }

    @Test
    void testSecondUserInsert() throws Exception {
        try (Connection connection = DriverManager.getConnection(postgreSQLContainer.getJdbcUrl(), postgreSQLContainer.getUsername(), postgreSQLContainer.getPassword());
             Statement statement = connection.createStatement()) {
            // This test runs with a fresh, empty database, independent of testFirstUserInsert
            statement.executeUpdate("CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(255))");
            statement.executeUpdate("INSERT INTO users (name) VALUES ('Grace')");

            ResultSet rs = statement.executeQuery("SELECT COUNT(*) FROM users");
            assertTrue(rs.next());
            assertEquals(1, rs.getInt(1));
        }
    }
}

Tradeoffs of Instance Containers:

Pros: Maximum test isolation, eliminating side effects between test methods. Easier to reason about test state.
Cons: Slower test execution due to repeated container lifecycles. Can be resource-intensive if you have many test methods in a single class.

Recommendation: For most integration tests, a static container for the test class combined with transactional rollbacks or explicit data cleanup between tests (@BeforeEach, @AfterEach) offers a good balance of speed and isolation. Use instance containers only when absolute isolation per test method is paramount and performance is not a critical concern.

Initializing the Database Schema and Data

Most real-world applications require a predefined schema and possibly some initial data for tests. Testcontainers provides convenient ways to achieve this.

1. Using `withInitScript()`

The withInitScript() method allows you to execute a SQL script (located on the classpath) immediately after the database container starts. This is ideal for schema creation and populating baseline data.

package com.example.testcontainers;

import org.junit.jupiter.api.DisplayName;
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;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Testcontainers
@DisplayName("PostgreSQL with Init Script")
class InitScriptPostgreSqlTest {

    @Container
    private static PostgreSQLContainer<?> postgreSQLContainer = new PostgreSQLContainer<>("postgres:13")
            .withDatabaseName("init_testdb")
            .withUsername("init_user")
            .withPassword("init_pass")
            .withInitScript("sql/init_postgresql.sql"); // Path to your SQL script on classpath

    @Test
    void testDataInitializedFromScript() throws Exception {
        String jdbcUrl = postgreSQLContainer.getJdbcUrl();
        String username = postgreSQLContainer.getUsername();
        String password = postgreSQLContainer.getPassword();

        try (Connection connection = DriverManager.getConnection(jdbcUrl, username, password);
             Statement statement = connection.createStatement()) {

            // Verify table and data from init script
            ResultSet rs = statement.executeQuery("SELECT COUNT(*) FROM products");
            assertTrue(rs.next());
            assertEquals(2, rs.getInt(1)); // Expecting 2 rows from init_postgresql.sql

            rs = statement.executeQuery("SELECT name FROM products WHERE id = 1");
            assertTrue(rs.next());
            assertEquals("Laptop", rs.getString("name"));
        }
    }
}

src/test/resources/sql/init_postgresql.sql:

CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    price DECIMAL(10, 2) NOT NULL
);

INSERT INTO products (name, price) VALUES ('Laptop', 1200.00);
INSERT INTO products (name, price) VALUES ('Mouse', 25.50);

2. Integration with Schema Migration Tools (Flyway/Liquibase)

For more complex schema management, Testcontainers integrates seamlessly with tools like Flyway and Liquibase. You simply point your migration tool to the Testcontainers-provided JDBC URL, and it will apply migrations as usual.

package com.example.testcontainers;

import org.flywaydb.core.Flyway;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.DisplayName;
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;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Testcontainers
@DisplayName("PostgreSQL with Flyway Migrations")
class FlywayPostgreSqlTest {

    @Container
    private static PostgreSQLContainer<?> postgreSQLContainer = new PostgreSQLContainer<>("postgres:13")
            .withDatabaseName("flyway_testdb")
            .withUsername("flyway_user")
            .withPassword("flyway_pass");

    @BeforeAll
    static void setupDatabase() {
        // Apply Flyway migrations to the Testcontainers database
        Flyway flyway = Flyway.configure()
                .dataSource(postgreSQLContainer.getJdbcUrl(), postgreSQLContainer.getUsername(), postgreSQLContainer.getPassword())
                .locations("classpath:db/migration") // Point to your migration scripts
                .load();
        flyway.migrate();
    }

    @Test
    void testFlywayMigrationApplied() throws Exception {
        try (Connection connection = DriverManager.getConnection(postgreSQLContainer.getJdbcUrl(), postgreSQLContainer.getUsername(), postgreSQLContainer.getPassword());
             Statement statement = connection.createStatement()) {

            ResultSet rs = statement.executeQuery("SELECT COUNT(*) FROM persons");
            assertTrue(rs.next());
            assertEquals(1, rs.getInt(1)); // Expecting 1 row from V1__initial_schema.sql

            rs = statement.executeQuery("SELECT name FROM persons WHERE id = 101");
            assertTrue(rs.next());
            assertEquals("John Doe", rs.getString("name"));
        }
    }
}

src/test/resources/db/migration/V1__initial_schema.sql:

CREATE TABLE persons (
    id INT PRIMARY KEY,
    name VARCHAR(255) NOT NULL
);

INSERT INTO persons (id, name) VALUES (101, 'John Doe');

Integrating with Spring Boot (and Data JPA)

Testcontainers shines when integrated with Spring Boot, especially for data-driven applications using Spring Data JPA. Spring Boot 2.2+ offers excellent support via @DynamicPropertySource.

package com.example.testcontainers;

import com.example.testcontainers.repository.ProductRepository;
import com.example.testcontainers.entity.Product;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
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 java.math.BigDecimal;
import java.util.Optional;

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

// Assume you have a simple Spring Boot application with Product entity and ProductRepository
// Product.java:
// @Entity @Table(name = "products") public class Product { @Id @GeneratedValue private Long id; private String name; private BigDecimal price; ...getters/setters... }
// ProductRepository.java:
// public interface ProductRepository extends JpaRepository<Product, Long> {}

@SpringBootTest
@Testcontainers
class SpringBootPostgreSqlIntegrationTest {

    @Container
    private static PostgreSQLContainer<?> postgreSQLContainer = new PostgreSQLContainer<>("postgres:13")
            .withDatabaseName("spring_testdb")
            .withUsername("spring_user")
            .withPassword("spring_pass");

    @Autowired
    private ProductRepository productRepository;

    @DynamicPropertySource
    static void registerPgProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgreSQLContainer::getJdbcUrl);
        registry.add("spring.datasource.username", postgreSQLContainer::getUsername);
        registry.add("spring.datasource.password", postgreSQLContainer::getPassword);
        registry.add("spring.jpa.hibernate.ddl-auto", () -> "create-drop"); // Ensure schema is created
    }

    @Test
    void testProductPersistence() {
        Product newProduct = new Product();
        newProduct.setName("Test Gadget");
        newProduct.setPrice(new BigDecimal("99.99"));

        Product savedProduct = productRepository.save(newProduct);
        assertThat(savedProduct).isNotNull();
        assertThat(savedProduct.getId()).isNotNull();

        Optional<Product> foundProduct = productRepository.findById(savedProduct.getId());
        assertThat(foundProduct).isPresent();
        assertThat(foundProduct.get().getName()).isEqualTo("Test Gadget");
    }

    @Test
    void testAnotherProductPersistence() {
        Product anotherProduct = new Product();
        anotherProduct.setName("Super Widget");
        anotherProduct.setPrice(new BigDecimal("19.99"));

        productRepository.save(anotherProduct);

        assertThat(productRepository.count()).isEqualTo(2); // Assuming previous test also ran and saved one.
    }
}

Explanation:

@SpringBootTest: Standard Spring Boot test annotation.
@Testcontainers and @Container: As before, to manage the PostgreSQL container.
@DynamicPropertySource: This powerful annotation (introduced in Spring Boot 2.2) allows you to dynamically set Spring properties before the application context is loaded. Here, we're telling Spring to use the JDBC URL, username, and password provided by the running Testcontainers instance.
spring.jpa.hibernate.ddl-auto=create-drop: This HBM2DDL setting ensures that Hibernate creates the schema (based on your entities) when the application context starts and drops it when it closes, giving you a clean slate for each test class run (since the container is static for the class).

This setup ensures your Spring Boot application always connects to a real, isolated PostgreSQL database during integration tests.

GenericContainer and Custom Docker Images

While Testcontainers provides specific modules for common databases (PostgreSQL, MySQL, Oracle, etc.), sometimes you need to test against a service that doesn't have a dedicated module or requires a custom Docker image. For these scenarios, GenericContainer is your go-to.

GenericContainer allows you to launch any Docker image and interact with it. You can define port mappings, environment variables, and wait strategies.

package com.example.testcontainers;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.stream.Collectors;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Testcontainers
@DisplayName("GenericContainer Example - Nginx")
class GenericContainerTest {

    // Start an Nginx container
    @Container
    private static GenericContainer<?> nginx = new GenericContainer<>("nginx:latest")
            .withExposedPorts(80)
            .waitingFor(Wait.forHttp("/").forStatusCode(200)); // Wait until Nginx responds on port 80

    @Test
    void testNginxContainerIsRunningAndAccessible() throws Exception {
        // Get the dynamically mapped host port
        Integer mappedPort = nginx.getFirstMappedPort();
        String host = nginx.getHost();

        URL url = new URL("http://" + host + ":" + mappedPort);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("GET");

        int responseCode = connection.getResponseCode();
        assertEquals(200, responseCode);

        try (BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
            String response = in.lines().collect(Collectors.joining("\n"));
            assertTrue(response.contains("Welcome to nginx!"));
        }
    }

    // Example of using a custom Dockerfile (imagine a simple app)
    // For this to run, you'd need a Dockerfile in src/test/resources/my-app/
    // Dockerfile content: FROM alpine/git COPY . /app WORKDIR /app CMD ["sh", "-c", "echo Hello from custom app && sleep 3600"]
    @Container
    private static GenericContainer<?> customApp = new GenericContainer<>(
            new org.testcontainers.images.builder.ImageFromDockerfile()
                    .withDockerfileFromBuilder(dockerfileBuilder ->
                            dockerfileBuilder
                                    .from("alpine/git")
                                    .copy("app.sh", "/app/app.sh")
                                    .run("chmod +x /app/app.sh")
                                    .cmd("sh", "/app/app.sh")
                                    .build())
                    .withFileFromClasspath("app.sh", "my-app/app.sh") // Ensure this file exists in src/test/resources/my-app/
    )
            .withExposedPorts(8080) // If your app exposes a port
            .waitingFor(Wait.forLogMessage(".*Hello from custom app.*", 1)); // Wait for a specific log message

    @Test
    void testCustomAppContainerLogs() throws Exception {
        // You can verify logs, or interact with ports if your app exposes them
        assertTrue(customApp.isRunning());
        // The waitingFor strategy already confirmed the log message
        System.out.println("Custom app container started and logged: " + customApp.getLogs());
    }
}

src/test/resources/my-app/app.sh (for the custom app example):

#!/bin/sh
echo "Hello from custom app"
sleep 5
echo "App finished"

Key GenericContainer methods:

withExposedPorts(): Declares which container ports should be exposed to the host. Testcontainers dynamically maps these to available host ports.
withEnv(): Sets environment variables inside the container.
withCommand(): Overrides the default command for the container.
waitingFor(): Crucial for ensuring the container is truly ready before tests try to connect. Testcontainers provides various WaitStrategy implementations (Wait.forHttp, Wait.forLogMessage, Wait.forListeningPort, etc.).
ImageFromDockerfile: Allows you to build a Docker image on the fly from a Dockerfile located in your classpath or even constructed programmatically.

Advanced Features & Best Practices

1. Reusable Containers (`@Testcontainers(disabledWithoutDocker = true)`) and Testcontainers Cloud

By default, Testcontainers creates unique containers for each test run. For very large test suites, this can still be slow. Testcontainers offers features for reusing containers across multiple test classes or even across JVM invocations:

Reusable Containers (Local): By setting the testcontainers.reuse.enable=true property (e.g., in ~/.testcontainers.properties) and adding .withReuse(true) to your container definition, Testcontainers will try to reuse existing containers that match the configuration, rather than starting new ones.
Testcontainers Cloud: For CI/CD environments, Testcontainers Cloud (or self-hosted solutions like Testcontainers Cloud for Docker Compose) allows you to offload container management to a dedicated service, speeding up CI builds by reusing containers across different build jobs or even different repositories.

// Example of a reusable container
@Container
private static PostgreSQLContainer<?> reusablePg = new PostgreSQLContainer<>("postgres:13")
        .withReuse(true) // Enable reuse
        .withDatabaseName("reusable_db")
        .withUsername("reusable_user")
        .withPassword("reusable_pass");

2. Wait Strategies

Waiting for a container to be truly ready is paramount. Testcontainers provides a robust WaitStrategy API:

Wait.forListeningPort(): Waits until a specific port inside the container is listening.
Wait.forHttp(path): Waits for an HTTP GET request to a specific path to return a 2xx status code.
Wait.forLogMessage(regexp, times): Waits until a specific log message appears a certain number of times in the container logs.
Wait.forHealthcheck(): Waits for the container's Docker HEALTHCHECK to pass.
Wait.forJDBC(jdbcUrl, username, password): Specific for JDBC connections.

Always use an appropriate wait strategy to prevent flaky tests.

3. Networking and Container Linking

If your tests involve multiple services (e.g., a database and a message queue), Testcontainers can link them for you. Services running within Testcontainers can communicate with each other using their container names as hostnames.

@Container
private static Network network = Network.newNetwork();

@Container
private static PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:13")
        .withNetwork(network)
        .withNetworkAliases("mypostgres"); // Alias for other containers to reach it

@Container
private static GenericContainer<?> app = new GenericContainer<>("my-custom-app:latest")
        .withNetwork(network)
        .withEnv("DATABASE_HOST", "mypostgres") // App connects to 'mypostgres'
        .withEnv("DATABASE_PORT", "5432"); // Standard Postgres port

4. Performance Tips

Reuse Containers: As discussed, enable withReuse(true) and configure testcontainers.reuse.enable=true globally.
Static Containers: Use static container fields for test classes to minimize container startup/shutdown overhead.
Thin Images: Prefer smaller Docker images (e.g., alpine variants) when possible to reduce download times.
Pre-pull Images: In CI environments, pre-pulling common Docker images can save time.
Resource Limits: Be mindful of Docker resource limits (CPU, memory) on your host, especially in CI, to prevent bottlenecks.

Common Pitfalls and Troubleshooting

1. Docker Not Running or Accessible

Symptom: Could not connect to Docker daemon or Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Solution: Ensure Docker Desktop (or Docker Engine) is running and accessible. Check Docker logs. On Linux, ensure your user is in the docker group (sudo usermod -aG docker $USER && newgrp docker).

2. Image Pull Failures

Symptom: Failed to pull image 'postgres:13'
Solution: Check your internet connection. Ensure the Docker image name and tag are correct. Sometimes, Docker Hub rate limits can cause issues; try again later or use a different mirror.

3. Container Startup Timeouts

Symptom: Container startup failed: Waited 60 seconds for container to start
Solution: This usually means your WaitStrategy isn't being met. Increase the timeout with withStartupTimeout(Duration.ofSeconds(120)). More importantly, refine your WaitStrategy. Is the port correct? Is the log message appearing as expected? Check container logs (container.getLogs()) for clues.

4. Port Conflicts (Less Common with Testcontainers)

Symptom: Bind for 0.0.0.0:xxxx failed: port is already allocated
Solution: Testcontainers typically handles dynamic port mapping, so this is rare. If it occurs, it might be an issue with Docker itself or another application hogging a specific port that Testcontainers tries to use for internal communication. Restarting Docker often helps.

5. Resource Consumption

Symptom: Slow tests, system freezing, out-of-memory errors.
Solution: Testcontainers can consume significant CPU and RAM, especially with many containers or large images. Use static containers, enable reuse, and ensure your Docker daemon has sufficient resources allocated (e.g., in Docker Desktop settings).

Conclusion

Testcontainers has fundamentally transformed how developers approach integration testing in Java. By providing isolated, real-world service instances on demand, it eliminates the compromises of in-memory databases and the complexities of shared environments. This leads to more reliable, consistent, and maintainable tests that truly reflect your application's behavior in production.

From basic database connectivity to complex Spring Boot integrations and custom Docker services, Testcontainers offers a flexible and powerful toolkit. Embrace it to build confidence in your integration tests, accelerate your development cycles, and deliver higher-quality software.

Start experimenting with Testcontainers today, and experience the power of truly realistic integration testing. Your future self (and your users) will thank you!