Testcontainers para Java: guía completa con ejemplos prácticos

1. ¿Qué es Testcontainers y por qué usarlo?

Testcontainers es una potente biblioteca para Java (y otros lenguajes JVM) que permite ejecutar contenedores Docker directamente dentro de tus pruebas de integración. En lugar de depender de bases de datos externas, brokers de mensajes u otros servicios que pueden no estar disponibles o configurados de forma diferente en distintos entornos, Testcontainers levanta automáticamente los contenedores necesarios antes de cada prueba y los destruye al finalizar. Esto garantiza pruebas limpias y reproducibles.

¿Por qué es necesario? Las pruebas de integración tradicionales suelen sufrir el "problema del entorno": una prueba puede funcionar en la máquina del desarrollador, pero fallar en el servidor de CI debido a una versión diferente de la base de datos o la ausencia de un servicio concreto. Testcontainers resuelve este problema de forma definitiva. Tú describes la infraestructura necesaria (por ejemplo, "PostgreSQL 15 con la extensión uuid-ossp habilitada") directamente en el código de la prueba, y la biblioteca garantiza que esa infraestructura se cree en un contenedor Docker aislado. Esto hace que las pruebas sean verdaderamente portátiles y fiables.

Esta biblioteca es especialmente útil para probar capas DAO, repositorios, servicios que trabajan con colas (RabbitMQ, Kafka), cachés (Redis) e incluso para probar clientes HTTP utilizando contenedores con WireMock o Nginx. Testcontainers también proporciona módulos convenientes para tecnologías populares (PostgreSQL, MySQL, MongoDB, Redis, Kafka, LocalStack y muchas otras), lo que minimiza la configuración necesaria.

2. Instalación

Testcontainers se distribuye a través de Maven Central. Para añadirlo a tu proyecto Java, agrega la siguiente dependencia en tu archivo pom.xml (Maven) o build.gradle (Gradle).

Maven (pom.xml)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.19.7</version> <!-- Verifica la versión más reciente en Maven Central -->
    <scope>test</scope>
</dependency>

<!-- Módulos adicionales, por ejemplo para 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'

Importante: Asegúrate de que Docker Engine esté instalado y en ejecución en tu máquina (o en el agente de CI). Testcontainers se comunica con Docker a través de un socket. Si usas Docker Desktop en macOS o Windows, debe estar iniciado. En Linux, verifica que el usuario que ejecuta las pruebas tenga permisos para usar Docker (por ejemplo, a través del grupo docker).

3. Inicio rápido: ejemplo mínimo funcional

Escribamos una prueba sencilla que inicie un contenedor con PostgreSQL, cree una tabla, inserte datos y los verifique. Este es el clásico ejemplo "¡Hola, mundo!" de 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 // Habilita la gestión automática del ciclo de vida de los contenedores
class QuickStartTest {

    // @Container indica que el contenedor debe gestionarse (iniciar antes de la prueba, detener después)
    @Container
    private PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres: