VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
Como o Testcontainers Se Encaixa em uma Suíte de Testes
O Testcontainers é uma biblioteca, não um serviço separado. Ele conversa com o daemon do Docker que já está rodando na sua máquina ou no runner de CI, inicia um contêiner antes de o corpo do teste rodar, espera até que o contêiner esteja realmente pronto para aceitar conexões e o derruba quando o teste termina. Cada teste (ou cada arquivo de teste, dependendo de como você define o escopo) recebe seu próprio contêiner, então os testes não compartilham estado e não precisam de um banco de dados de teste compartilhado que alguém tenha de lembrar de redefinir. Este guia usa Go e o módulo MySQL oficial dotestcontainers-go, porque o pacote testing do Go torna fácil mostrar o ciclo de vida do contêiner por completo. O Testcontainers tem módulos equivalentes para Java, Python e Node.js/TypeScript; a configuração varia por linguagem, mas o padrão (iniciar o contêiner, esperar ficar pronto, executar o esquema, executar o teste, derrubar) é o mesmo.
Configuração do Projeto
testcontainers-go como dependência transitiva do módulo MySQL, junto com o driver go-sql-driver/mysql que o teste usa para de fato conectar e executar consultas.
O Esquema e o Código Sob Teste
Um esquema mínimo com uma restrição que vale a pena testar:database/sql da biblioteca padrão:
Iniciando o Contêiner e Carregando o Esquema
tcmysql.WithScripts monta o schema.sql no diretório /docker-entrypoint-initdb.d/ do contêiner, que a imagem oficial do MySQL executa automaticamente uma vez, na primeira vez em que o contêiner inicia com um diretório de dados vazio. container.ConnectionString retorna um DSN pronto para uso, com o nome de usuário, a senha, o host e a porta mapeada já preenchidos. As chamadas t.Cleanup rodam em ordem inversa à do registro, independentemente de o teste passar ou falhar, e é isso que derruba o contêiner: não há uma etapa de encerramento separada para esquecer.
Executando um Teste Contra o Banco de Dados Real
go test -v inicia um contêiner real, aplica o esquema, insere uma linha por meio de CreateUser, lê a linha de volta por meio de GetUserByEmail e derruba o contêiner:
mysql:8.0.36 já baixada. A primeira execução em uma máquina que nunca baixou essa imagem demora bem mais: em uma execução medida aqui, o primeiro teste da suíte levou 25,95 segundos de ponta a ponta (download da imagem incluído), e cada teste seguinte na mesma invocação de go test levou de 6,8 a 7,5 segundos, porque o Docker só baixa uma imagem uma vez e o Testcontainers inicia um contêiner novo a partir da imagem já local a cada chamada Run seguinte. De “contêiner iniciado” até “contêiner pronto”, especificamente, o contêiner MySQL nessa execução levou cerca de 5 segundos para aceitar conexões.
Por Que Não Simular o Banco de Dados
Um mock dedatabase/sql retorna o que você mandou ele retornar. Ele não tem um mecanismo de restrições nem modo estrito, então não consegue reproduzir o que o MySQL realmente faz quando seu código envia um valor que o MySQL rejeita. Dois testes contra o contêiner real no store_test.go deste projeto demonstram isso diretamente.
O esquema declara UNIQUE KEY uq_users_email (email). Inserir o mesmo e-mail duas vezes contra o contêiner real falha com um erro específico e real do MySQL:
mysqlErr.Number igual a 1062, o código ER_DUP_ENTRY real que o MySQL retorna para uma violação de chave única. Um mock precisaria ser instruído de antemão a retornar exatamente esse erro exatamente nesse formato; o banco de dados real o impõe porque a restrição existe no esquema, não no teste.
A coluna age é TINYINT UNSIGNED, então ela não pode guardar um número negativo. Sob o modo estrito padrão do MySQL (o padrão desde o MySQL 5.7), o servidor rejeita um valor fora do intervalo em vez de limitá-lo silenciosamente a zero:
1264, ER_WARN_DATA_OUT_OF_RANGE. Nenhum desses comportamentos vem do código da aplicação. Os dois vêm do próprio MySQL, e é exatamente por isso que um mock no nível do banco de dados não consegue reproduzi-los sem ser codificado à mão para falsificar esse caso específico.
Apontando o Testcontainers para uma Imagem do VillageSQL
O VillageSQL fala o mesmo protocolo de rede que o MySQL, então o mesmo módulo MySQL dotestcontainers-go pode controlar um contêiner villagesql/server em vez de um mysql padrão. Fazer isso exigiu uma alteração. A verificação de prontidão padrão do módulo espera pela linha de log literal port: 3306 MySQL Community Server, que o log de inicialização do VillageSQL nunca imprime; a linha de pronto do VillageSQL diz ... ready for connections. Version: '8.4.11-villagesql-0.0.6' ... port: 3306 .... Substituir a estratégia de espera para corresponder a essa linha é suficiente:
WithOccurrence(2) é necessário porque o script de entrypoint inicia primeiro um servidor temporário, para executar os scripts de inicialização, e depois inicia o servidor real que o contêiner mantém rodando. Saiba o que a segunda ocorrência realmente é: o log traz três linhas correspondentes, porque a inicialização do servidor real imprime uma para o X Plugin e uma para o próprio mysqld. A ocorrência 2 é a linha do X Plugin, que chega uma fração de milissegundo antes de o mysqld se anunciar, então esperar por ela é próximo o suficiente na prática. Em vez disso, use "/usr/bin/mysqld: ready for connections" se quiser a espera presa à linha do próprio servidor, já que essa string aparece exatamente duas vezes. Com essa estratégia de espera, o contêiner iniciou, aplicou o schema.sql e aceitou uma conexão em 6,81 segundos em uma execução capturada aqui, e SELECT VERSION() retornou 8.4.11-villagesql-0.0.6. Todo o resto, WithDatabase, WithUsername, WithPassword, WithScripts e ConnectionString, funcionou sem alterações.
Escolhendo uma Imagem e uma Versão
Fixe uma tag exata em vez delatest para qualquer teste que rode em CI, para que uma nova versão da imagem upstream não possa mudar os resultados dos seus testes sem aviso:
docker manifest inspect <image>:<tag> antes de se comprometer com uma tag, para confirmar que ela existe e ver quais arquiteturas ela publica; tanto mysql:8.0.36 quanto villagesql/server:latest publicavam manifestos amd64 e arm64 no momento desta escrita, então a mesma tag roda em runners de CI Intel e Apple Silicon sem substituição de plataforma.
Perguntas Frequentes
O Testcontainers precisa de um daemon do Docker real, ou funciona com um mock?
Ele precisa de um daemon do Docker real, acessível de onde o teste roda: o Docker Desktop localmente, ou um runner Docker-in-Docker ou com o socket do Docker montado em CI. Sedocker info falha na máquina que executa o teste, o Testcontainers não consegue iniciar o contêiner e o teste falha com um erro de conexão antes mesmo de chegar ao seu código.
Cada teste recebe seu próprio contêiner, ou os testes podem compartilhar um?
Essa é uma escolha que você faz no código de teste, não algo que o Testcontainers impõe. Chamar o helper que inicia o contêiner de dentro de cada funçãoTest..., como mostrado acima, dá a cada teste seu próprio contêiner e o isolamento mais forte. Iniciar o contêiner uma vez em TestMain e compartilhá-lo entre os testes de um pacote é mais rápido, mas então cada teste é responsável por limpar as linhas que inseriu para não ver os dados de outro teste.
Quanto tempo um contêiner leva para ficar pronto?
Nas execuções capturadas para este guia, um contêinermysql:8.0.36 levou cerca de 5 segundos de “contêiner iniciado” até “pronto para conexões” quando a imagem já estava baixada localmente, e um contêiner villagesql/server:latest levou um tempo comparável. O primeiro contêiner a iniciar em uma execução de go test que nunca baixou a imagem antes leva bem mais tempo, porque paga também pelo download da imagem; uma execução medida aqui levou 25,95 segundos para esse primeiro contêiner.
Posso executar a ferramenta de migração de esquema que já uso em vez de um arquivo SQL simples?
Sim.WithScripts apenas monta arquivos em /docker-entrypoint-initdb.d/, que aceita arquivos .sql e .sh. Um script de shell nesse diretório pode invocar qualquer ferramenta de migração capaz de rodar contra um host e uma porta, desde que a ferramenta esteja disponível dentro do contêiner ou você a instale como parte do script.
Solução de Problemas
Veja também
- MySQL no Docker — a imagem, as variáveis de ambiente e o comportamento de volumes sobre os quais o Testcontainers se apoia
- Migrações de Esquema no MySQL — executando em produção as mesmas alterações de esquema que este guia carrega por meio de
WithScripts - MySQL com ORMs — usando o pool de conexões e as ferramentas de migração de um ORM contra um banco de dados gerenciado pelo Testcontainers