Testcontainers pour Java : guide complet avec exemples

1. Qu'est-ce que Testcontainers et pourquoi l'utiliser ?

Testcontainers est une bibliothèque puissante pour Java (et d'autres langages JVM) qui permet de lancer des conteneurs Docker directement dans vos tests d'intégration. Au lieu de dépendre de bases de données externes, de courtiers de messages ou d'autres services qui peuvent être indisponibles ou configurés différemment selon les environnements, Testcontainers démarre automatiquement les conteneurs nécessaires avant le test et les détruit après son exécution. Cela garantit des tests propres et reproductibles.

Pourquoi en avez-vous besoin ? Les tests d'intégration traditionnels souffrent souvent du "problème d'environnement" : un test peut passer sur la machine du développeur, mais échouer sur le serveur CI à cause d'une version différente de la base de données ou de l'absence d'un service spécifique. Testcontainers résout ce problème une fois pour toutes. Vous décrivez l'infrastructure nécessaire (par exemple, "PostgreSQL 15 avec l'extension uuid-ossp activée") directement dans le code du test, et la bibliothèque garantit que cette infrastructure sera créée dans un conteneur Docker isolé. Cela rend les tests véritablement portables et fiables.

La bibliothèque est particulièrement utile pour tester les couches DAO, les repositories, les services qui interagissent avec des files d'attente (RabbitMQ, Kafka), des caches (Redis) et même pour tester des clients HTTP à l'aide de conteneurs WireMock ou Nginx. Testcontainers fournit également des modules pratiques pour les technologies populaires (PostgreSQL, MySQL, MongoDB, Redis, Kafka, LocalStack, etc.), ce qui réduit la configuration au minimum.

2. Installation

Testcontainers est distribué via Maven Central. Pour l'ajouter à votre projet Java, incluez la dépendance suivante dans votre fichier pom.xml (Maven) ou build.gradle (Gradle).

Maven (pom.xml)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.19.7</version> <!-- Vérifiez la version actuelle sur Maven Central -->
    <scope>test</scope>
</dependency>

<!-- Modules supplémentaires, par exemple pour 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'

Important : Assurez-vous que Docker Engine est installé et en cours d'exécution sur votre machine (ou votre agent CI). Testcontainers communique avec Docker via un socket. Si vous utilisez Docker Desktop sur macOS ou Windows, il doit être lancé. Sous Linux, vérifiez que l'utilisateur qui exécute les tests a les droits nécessaires pour utiliser Docker (par exemple, via le groupe docker).

3. Démarrage rapide — exemple minimal fonctionnel

Écrivons un test simple qui lance un conteneur PostgreSQL, crée une table, insère des données et les vérifie. C'est l'exemple classique "Hello, World!" pour 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 // Active la gestion automatique du cycle de vie des conteneurs
class QuickStartTest {

    // @Container indique que le conteneur doit être géré (démarré avant le test, arrêté après)
    @Container
    private PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres: