Testcontainers für Java: Komplettes Tutorial mit Praxisbeispielen

1. Was ist Testcontainers und warum braucht man es?

Testcontainers ist eine leistungsstarke Bibliothek für Java (und andere JVM-Sprachen), mit der Sie Docker-Container direkt in Ihren Integrationstests starten können. Anstatt sich auf externe Datenbanken, Message-Broker oder andere Dienste zu verlassen, die in verschiedenen Umgebungen unterschiedlich konfiguriert oder nicht verfügbar sein können, startet Testcontainers automatisch die benötigten Container vor dem Test und räumt sie nach Abschluss wieder auf. Das garantiert saubere und reproduzierbare Tests.

Warum ist das notwendig? Herkömmliche Integrationstests leiden oft unter dem "Umgebungsproblem": Ein Test kann auf dem Entwicklerrechner funktionieren, aber auf dem CI-Server fehlschlagen, weil dort eine andere Datenbankversion läuft oder ein bestimmter Dienst fehlt. Testcontainers löst dieses Problem ein für alle Mal. Sie beschreiben die benötigte Infrastruktur (z. B. "PostgreSQL 15 mit aktivierter uuid-ossp-Erweiterung") direkt im Testcode, und die Bibliothek stellt sicher, dass diese Infrastruktur in einem isolierten Docker-Container erstellt wird. Das macht Ihre Tests wirklich portabel und zuverlässig.

Die Bibliothek ist besonders nützlich für das Testen von DAO-Schichten, Repositories, Diensten, die mit Warteschlangen (RabbitMQ, Kafka), Caches (Redis) arbeiten, und sogar für das Testen von HTTP-Clients mit Containern wie WireMock oder Nginx. Testcontainers bietet auch praktische Module für gängige Technologien (PostgreSQL, MySQL, MongoDB, Redis, Kafka, LocalStack und viele mehr), was den Konfigurationsaufwand minimiert.

2. Installation

Testcontainers wird über Maven Central verteilt. Um es in Ihr Java-Projekt einzubinden, fügen Sie die folgende Abhängigkeit in Ihre pom.xml (Maven) oder build.gradle (Gradle) ein.

Maven (pom.xml)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.19.7</version> <!-- Prüfen Sie die aktuelle Version auf Maven Central -->
    <scope>test</scope>
</dependency>

<!-- Zusätzliche Module, z.B. für PostgreSQL -->
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <version>1.19.7</version>
    <scope>test</scope>
</dependency>

Gradle (build.gradle)

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

Wichtig: Stellen Sie sicher, dass auf Ihrem Rechner (oder CI-Agent) Docker Engine installiert und ausgeführt wird. Testcontainers kommuniziert mit Docker über einen Socket. Wenn Sie Docker Desktop auf macOS oder Windows verwenden, muss es gestartet sein. Unter Linux stellen Sie sicher, dass der Benutzer, unter dem die Tests ausgeführt werden, die Berechtigung hat, mit Docker zu arbeiten (z. B. über die Gruppe docker).

3. Schnellstart – Minimales funktionierendes Beispiel

Schreiben wir einen einfachen Test, der einen PostgreSQL-Container startet, eine Tabelle erstellt, Daten einfügt und sie überprüft. Dies ist das klassische "Hello, World!"-Beispiel für Testcontainers.

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;

@Testcontainers // Aktiviert die automatische Lebenszyklusverwaltung der Container
class QuickStartTest {

    // @Container markiert, dass der Container verwaltet werden soll (vor dem Test starten, danach stoppen)
    @Container
    private PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres: