Testcontainers for Java: Complete Guide with Examples

1. What It Is and Why It's Needed

Testcontainers is a powerful library for Java (and other JVM languages) that allows you to run Docker containers directly inside your integration tests. Instead of relying on external databases, message brokers, or other services that may be unavailable or configured differently in various environments, Testcontainers automatically spins up the necessary containers before the test and destroys them after completion. This ensures test cleanliness and reproducibility.

Why is it needed? Traditional integration tests often suffer from the "environment problem": a test may pass on a developer's machine but fail on a CI server due to a different database version or the absence of a specific service. Testcontainers solves this problem once and for all. You describe the required infrastructure (e.g., "PostgreSQL 15 with the uuid-ossp extension enabled") directly in the test code, and the library guarantees that this infrastructure will be created in an isolated Docker container. This makes tests truly portable and reliable.

The library is especially useful for testing DAO layers, repositories, services working with queues (RabbitMQ, Kafka), caches (Redis), and even for testing HTTP clients using containers with WireMock or Nginx. Testcontainers also provides convenient modules for popular technologies (PostgreSQL, MySQL, MongoDB, Redis, Kafka, LocalStack, and many others), minimizing setup effort.

2. Installation

Testcontainers is distributed via Maven Central. To add it to a Java project, include the following dependency in your pom.xml (Maven) or build.gradle (Gradle).

Maven (pom.xml)

<dependency>\n    <groupId>org.testcontainers</groupId>\n    <artifactId>testcontainers</artifactId>\n    <version>1.19.7</version> <!-- Check the latest version on Maven Central -->\n    <scope>test</scope>\n</dependency>\n\n<!-- Additional modules, e.g., for PostgreSQL -->\n<dependency>\n    <groupId>org.testcontainers</groupId>\n    <artifactId>postgresql</artifactId>\n    <version>1.19.7</version>\n    <scope>test</scope>\n</dependency>

Gradle (build.gradle)

testImplementation 'org.testcontainers:testcontainers:1.19.7'\ntestImplementation 'org.testcontainers:postgresql:1.19.7'

Important: Make sure Docker Engine is installed and running on your machine (or CI agent). Testcontainers interacts with Docker via a socket. If you are using Docker Desktop on macOS or Windows, it must be running. On Linux, ensure the user running the tests has permissions to work with Docker (e.g., via the docker group).

3. Quick Start — Minimal Working Example

Let's write a simple test that starts a PostgreSQL container, creates a table, inserts data, and verifies it. This is a classic "Hello, World!" example for Testcontainers.

import org.junit.jupiter.api.Test;\nimport org.testcontainers.containers.PostgreSQLContainer;\nimport org.testcontainers.junit.jupiter.Container;\nimport org.testcontainers.junit.jupiter.Testcontainers;\n\nimport java.sql.Connection;\nimport java.sql.DriverManager;\nimport java.sql.ResultSet;\nimport java.sql.Statement;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\n@Testcontainers // Enables automatic container lifecycle management\nclass QuickStartTest {\n\n    // @Container indicates that the container should be managed (started before the test, stopped after)\n    @Container\n    private PostgreSQLCon