Wer Integration-Tests schreibt, kennt das Problem: Entweder man arbeitet mit Mocks, die nur begrenzt die Realität abbilden, oder man kämpft mit langsamen, schwer wartbaren Testumgebungen. Mocks haben den Charme, dass Tests schnell durchlaufen und keine externe Infrastruktur benötigen. Doch sie bergen eine Gefahr: Die Tests werden grün, weil die Mocks perfekt zu den Tests passen. Das heißt nicht unbedingt, dass der Code mit echten Systemen funktioniert. Wer garantiert, dass der Mock das Verhalten einer PostgreSQL-Datenbank oder einer Kafka-Queue korrekt abbildet?

Die Alternative in Form einer dedizierten Testumgebung mit echten Diensten bringt andere Probleme mit sich: Wie setzt man den Zustand zwischen Tests zurück? Wie verhindert man, dass Tests sich gegenseitig beeinflussen? Und wie stellt man sicher, dass die Testumgebung exakt der Produktionsumgebung entspricht?

Mit TestContainers gibt es einen pragmatischen Ausweg: Die Bibliothek startet echte Dienste in wegwerfbaren Docker-Containern. Jeder Test bekommt seine eigene, frische Instanz – komplett isoliert, mit definiertem Startzustand – und nach Testende automatisch aufgeräumt. Der Ansatz ist allerdings nur dann praktikabel, wenn die containerisierten Dienste schnell genug starten. Bei einer Datenbank, die in weniger als einer Sekunde bereit ist, lässt sich für jeden einzelnen Test ein neuer Container hochfahren. Bei Diensten mit mehreren Minuten Startzeit muss man hingegen zu Shared Containers greifen.

Die Idee hinter TestContainers

TestContainers ist ein Projekt zur programmatischen Steuerung von Docker-Containern in Tests. Der Kerngedanke ist simpel: Statt Mocks zu schreiben oder manuelle Testumgebungen zu pflegen, lässt man den Test selbst die benötigte Infrastruktur hochfahren. Nach Testende räumt TestContainers automatisch auf – kein manuelles Stoppen von Containern, keine vergessenen Ressourcen.

Die konzeptionelle Funktionsweise ist schnell erklärt: Ein Test startet einen oder mehrere Container, wartet, bis sie bereit sind, führt die eigentlichen Testschritte durch und stoppt zum Schluss die Container. TestContainers übernimmt dabei die dynamische Portzuordnung, sodass der Test sich nicht um Portkonflikte kümmern muss. Ein integrierter Reaper-Mechanismus sorgt dafür, dass Container auch dann aufgeräumt werden, wenn ein Test abstürzt oder abbricht.

Besonders wichtig sind die Wait Strategies. Ein gestarteter Container ist nämlich nicht automatisch sofort bereit, Anfragen zu verarbeiten. Eine Datenbank braucht beispielsweise Zeit zum Initialisieren, ein Webserver muss zunächst hochfahren. Wait Strategies definieren, wann ein Container als bereit gilt – etwa wenn ein bestimmter Port lauscht, eine HTTP-Anfrage erfolgreich ist oder eine spezifische Logzeile erscheint.

TestContainers bietet dabei bereits für viele gängige Anwendungen und Dienste vorgefertigte Module wie PostgreSQL, MySQL, Redis, MongoDB und Kafka. Diese Module sind Wrapper-Klassen um die generische Container-API, die bereits sinnvolle Defaults mitbringen, etwa Standardports, typische Umgebungsvariablen und passende Wait Strategies.

Für weniger verbreitete Dienste oder eigene Systeme kann man eigene Wrapper schreiben. Sie bauen auf dem GenericContainer auf und kapseln domänenspezifische Konfiguration. Das praktische Beispiel im Folgenden zeigt, wie unkompliziert die Umsetzung ist: eine Klasse, die das Image, Ports und Kommandozeilenparameter konfiguriert und eine Client-Instanz zurückgibt. Der Wrapper abstrahiert die TestContainers-API und bietet eine auf den konkreten Dienst zugeschnittene Schnittstelle.

Auf den ersten Blick scheint Docker Compose eine Alternative zu sein, das ebenfalls Container für Tests starten kann. Der Unterschied liegt jedoch in der Herangehensweise: Docker Compose arbeitet deklarativ mit YAML-Dateien und richtet typischerweise eine geteilte Umgebung für mehrere Tests ein. TestContainers hingegen ist programmatisch und integriert sich direkt in den Testcode. Jeder Test kann seine eigene Containerkonfiguration haben, Container werden im laufenden Betrieb gestartet und wieder gestoppt.

Ein weiterer Unterschied: Bei Compose muss man explizit darauf achten, Container zwischen verschiedenen Tests zurückzusetzen. Bei TestContainers ist das Design von Anfang an auf Isolation ausgelegt. Jeder Test bekommt neue Container, was sie robuster und unabhängiger voneinander macht.

Mehr Idee als Projekt

TestContainers ist kein monolithisches Open-Source-Projekt, sondern eher eine Idee, die in verschiedenen Programmiersprachen umgesetzt wurde. Es gibt TestContainers für Java, Go, .NET, Node.js, Python, PHP, Rust und zahlreiche weitere Sprachen – entwickelt von verschiedenen Maintainer-Teams mit unterschiedlichen Schwerpunkten.

Das bedeutet, dass beispielsweise Features, die in der Java-Implementierung selbstverständlich sind, in der Python-Version fehlen können – und umgekehrt. Auch die API-Gestaltung unterscheidet sich zwischen den Programmiersprachen, selbst wenn die Konzepte gleich bleiben. Die Dokumentationsqualität variiert und die Reife der Implementierungen ebenso.

Die Community und der Support sind pro Sprache organisiert: Hilfe zur Go-Implementierung findet man in anderen Foren als Hilfe zur PHP-Version.

Man sollte nicht davon ausgehen, dass ein bestimmtes Feature existiert, nur weil man es aus einer anderen Sprache kennt. Ein Blick in die Dokumentation der jeweiligen Implementierung ist unerlässlich. Die gute Nachricht: Die Grundkonzepte sind überall gleich. Wer das Prinzip verstanden hat, findet sich grundsätzlich auch in anderen Implementierungen zügig zurecht.

Ein Praxisbeispiel

Um die Unterschiede zwischen TestContainers-Implementierungen konkret zu zeigen, dient die Datenbank EventSourcingDB als Beispiel. Dabei handelt es sich um eine auf Event Sourcing spezialisierte, von the native web entwickelte Datenbank. Sie ist Closed Source, aber die zugehörigen Client-SDKs (Software Development Kits) sind Open Source auf GitHub verfügbar.

EventSourcingDB steht dabei exemplarisch für einen typischen Service, den man in Anwendungen benötigt – sei es eine Datenbank, eine Message-Queue oder ein anderer Infrastrukturdienst. Der entscheidende Vorteil für unser Beispiel: EventSourcingDB startet in weniger als einer Sekunde, was den „Container pro Test“-Ansatz praktikabel macht. Die Client-SDKs für verschiedene Sprachen enthalten jeweils eine eigene TestContainers-Integration, deren Implementierung sich lohnt anzuschauen.

Dieser Artikel betrachtet die Go- und PHP-Implementierung im Detail. Beide verfolgen konzeptionell den gleichen Ansatz, unterscheiden sich aber in wichtigen Details. Daher eignen sich die Implementierungen gut, um die Unterschiede zwischen TestContainers-Implementierungen zu illustrieren.