Testcontainers para Java: guia completo com exemplos práticos

1. O que é e para que serve

Testcontainers é uma biblioteca poderosa para Java (e outras linguagens JVM) que permite executar containers Docker diretamente dentro dos seus testes de integração. Em vez de depender de bancos de dados externos, brokers de mensagens ou outros serviços que podem estar indisponíveis ou configurados de forma diferente em cada ambiente, o Testcontainers sobe automaticamente os containers necessários antes do teste e os destrói após a conclusão. Isso garante testes limpos e reproduzíveis.

Para que serve isso? Testes de integração tradicionais sofrem frequentemente do "problema de ambiente": o teste pode passar na máquina do desenvolvedor, mas falhar no servidor de CI devido a uma versão diferente do banco de dados ou à ausência de um serviço específico. O Testcontainers resolve esse problema de uma vez por todas. Você descreve a infraestrutura necessária (por exemplo, "PostgreSQL 15 com a extensão uuid-ossp habilitada") diretamente no código do teste, e a biblioteca garante que essa infraestrutura será criada em um container Docker isolado. Isso torna os testes verdadeiramente portáteis e confiáveis.

A biblioteca é especialmente útil para testar camadas DAO, repositórios, serviços que trabalham com filas (RabbitMQ, Kafka), caches (Redis) e até mesmo para testar clientes HTTP com containers WireMock ou Nginx. O Testcontainers também oferece módulos convenientes para tecnologias populares (PostgreSQL, MySQL, MongoDB, Redis, Kafka, LocalStack e muitas outras), minimizando a configuração necessária.

2. Instalação

O Testcontainers é distribuído através do Maven Central. Para adicioná-lo ao seu projeto Java, inclua a seguinte dependência no seu pom.xml (Maven) ou build.gradle (Gradle).

Maven (pom.xml)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.19.7</version> <!-- Verifique a versão mais recente no Maven Central -->
    <scope>test</scope>
</dependency>

<!-- Módulos adicionais, por exemplo 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: Certifique-se de que o Docker Engine esteja instalado e em execução na sua máquina (ou agente de CI). O Testcontainers se comunica com o Docker através de um socket. Se você usa Docker Desktop no macOS ou Windows, ele deve estar em execução. No Linux, verifique se o usuário que executa os testes tem permissão para usar o Docker (por exemplo, através do grupo docker).

3. Início rápido — exemplo mínimo funcional

Vamos escrever um teste simples que inicia um container PostgreSQL, cria uma tabela, insere dados e os verifica. Este é o clássico exemplo "Hello, World!" para 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 // Ativa o gerenciamento automático do ciclo de vida dos containers
class QuickStartTest {

    // @Container indica que o container deve ser gerenciado (iniciado antes do teste, parado depois)
    @Container
    private PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres: