Testcontainers

O Testcontainers é uma biblioteca open source, disponível para Java, Node.js, .NET, Go, Python e outras linguagens, que controla o Docker de dentro dos seus testes. Um teste pede “um banco Postgres 16”, a biblioteca sobe um container, espera até ele estar pronto, entrega os dados de conexão e remove o container quando o teste termina. Você testa contra o motor de banco de dados real, em vez de um substituto em memória ou de um ambiente compartilhado.

Exemplo (Testcontainers for Java 1.x, JUnit 5)

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 static org.junit.jupiter.api.Assertions.assertTrue;

@Testcontainers
class DatabaseIT {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @Test
    void canQueryTheDatabase() throws Exception {
        try (Connection conn = DriverManager.getConnection(
                postgres.getJdbcUrl(), postgres.getUsername(), postgres.getPassword());
             ResultSet rs = conn.createStatement().executeQuery("SELECT 1")) {
            assertTrue(rs.next());
        }
    }
}

Um campo static compartilha um único container entre todos os testes da classe; um campo de instância subiria um novo a cada teste. Em uma suíte real, você apontaria o seu repositório ou o contexto do Spring para getJdbcUrl() e rodaria as migrations primeiro.

Por que isso importa

Testes de integração contra H2 ou SQLite muitas vezes passam enquanto o banco de produção rejeita o mesmo SQL, porque dialetos, constraints e comportamento de transações são diferentes. O Testcontainers entrega o motor real com quase a mesma praticidade de um mock, e cada execução começa de um estado limpo, o que elimina a instabilidade causada por dados compartilhados.

O que é bom saber

• Ele precisa de um runtime compatível com Docker na máquina e nos runners de CI. Os runners Ubuntu hospedados pelo GitHub já têm Docker disponível.
• Subir um container custa segundos. Compartilhe containers por classe ou por suíte e limpe os dados entre os testes, em vez de reiniciar o container.
• Fixe as versões das imagens para corresponderem à produção.
• Existem módulos prontos para serviços comuns (Postgres, MySQL, Kafka, LocalStack, Selenium e outros), e o GenericContainer cobre qualquer outra imagem.
• Ele complementa os test doubles em vez de substituí-los: os testes unitários ainda devem continuar em memória e rápidos.