testcontainers-go: Docker em testes com Go

No desenvolvimento de software moderno, testar integrações com serviços externos (bancos de dados, brokers de mensagens, caches) é um dos maiores desafios. Abordagens tradicionais, como usar bancos de dados de teste compartilhados ou mocks, frequentemente geram problemas: os testes se tornam frágeis, dependentes do ambiente ou não refletem o comportamento real do sistema. A biblioteca testcontainers-go oferece uma solução elegante: ela permite iniciar contêineres Docker isolados diretamente do código de teste em Go, garantindo um ambiente limpo, reproduzível e próximo da produção para cada execução de teste.

A ideia central do testcontainers-go é gerenciar o ciclo de vida de contêineres Docker programaticamente. Você descreve o serviço necessário (por exemplo, PostgreSQL, Redis, Kafka) no código do teste, a biblioteca baixa automaticamente a imagem (se não estiver disponível), inicia o contêiner, aguarda até que ele esteja pronto e fornece os parâmetros de conexão (host, porta, credenciais). Após a conclusão do teste, o contêiner é automaticamente parado e removido, sem deixar resíduos no sistema. Isso torna os testes independentes, rápidos e seguros.

testcontainers-go é a implementação em Go do popular projeto Testcontainers, que surgiu originalmente em Java e foi posteriormente portado para outras linguagens. A biblioteca é ativamente mantida pela comunidade e oferece módulos prontos para a maioria dos serviços populares: PostgreSQL, MySQL, Redis, MongoDB, Kafka, RabbitMQ, Elasticsearch e muitos outros. Ela é ideal para escrever testes de integração, testes end-to-end e até mesmo para desenvolvimento local, quando você precisa subir um ambiente rapidamente.

Instalação

Para instalar o testcontainers-go, use o gerenciador de pacotes padrão do Go. Certifique-se de ter o Docker (ou Podman) e o Go versão 1.19 ou superior instalados.

go get github.com/testcontainers/testcontainers-go

Para trabalhar com serviços específicos (como PostgreSQL), instale o módulo correspondente:

go get github.com/testcontainers/testcontainers-go/modules/postgres
go get github.com/testcontainers/testcontainers-go/modules/redis
go get github.com/testcontainers/testcontainers-go/modules/mongodb
go get github.com/testcontainers/testcontainers-go/modules/kafka
# e assim por diante

Após a instalação, importe os pacotes no seu arquivo de teste:

import (
    "context"
    "testing"
    
    "github.com/testcontainers/testcontainers-go"
    "github.com/testcontainers/testcontainers-go/wait"
    "github.com/testcontainers/testcontainers-go/modules/postgres"
)

Primeiros passos: exemplo mínimo funcional

Vamos escrever um teste simples que inicia um contêiner PostgreSQL, cria uma tabela, insere dados e os verifica. Isso mostrará os princípios básicos de uso da biblioteca.

package main

import (
    "context"
    "database/sql"
    "testing"
    "time"

    "github.com/testcontainers/testcontainers-go"
    "github.com/testcontainers/testcontainers-go/modules/postgres"
    "github.com/testcontainers/testcontainers-go/wait"
    _ "github.com/lib/pq" // driver PostgreSQL
)

func TestPostgresIntegration(t *testing.T) {
    ctx := context.Background()

    // 1. Inicia o contêiner PostgreSQL
    postgresContainer, err := postgres.RunContainer(ctx,
        testcontainers.WithImage("postgres:16-alpine"),
        postgres.WithDatabase("testdb"),
        postgres.WithUsername("testuser"),
        postgres.WithPassword("testpass"),
        testcontainers.WithWaitStrategy(
            wait.ForLog("database system is ready to accept connections").
                WithOccurrence(2).
                WithStartupTimeout(60*time.Second)),
    )
    if err != nil {
        t.Fatal(err)
    }
    defer postgres