Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
Simular um driver de banco de dados (mock) deixa o teste rápido, mas o mock só consegue retornar o que você mandou ele retornar. Ele não consegue impor uma restrição de unicidade, rejeitar um valor que viola o modo estrito, nem aplicar o seu esquema real. O Testcontainers inicia um contêiner MySQL real e descartável para o teste e o remove depois, então o teste roda contra o mesmo servidor com que sua aplicação roda em produção.

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 do testcontainers-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

Isso traz o próprio 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:
E uma pequena camada de acesso a dados com dois métodos, usando o database/sql da biblioteca padrão:
Nada aqui sabe que está sendo testado. O teste a seguir exercita esse código exatamente como a aplicação o chamaria.

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

Executar isso com 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:
Essa execução usou uma imagem 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 de database/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:
Isso passou contra o contêiner real com 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:
Isso também passou contra o contêiner real com o erro 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 do testcontainers-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 de latest 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:
Para o VillageSQL, fixe da mesma forma assim que tiver uma versão na qual queira permanecer:
Verifique 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. Se docker 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ção Test..., 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êiner mysql: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