Bancos de dados efêmeros em contêineres para testes de integração

Objetivo

Executar os testes de acesso a dados e de integração contra o motor de banco de dados real, iniciado do zero a cada execução, para que os testes detectem diferenças de dialeto, de constraints e de comportamento transacional que um substituto em memória ou um repositório simulado (mock) esconderia.

Pré-requisitos

Um runtime de contêineres nas máquinas dos desenvolvedores e no CI; migrações que possam ser aplicadas do zero com um único comando; testes que leiam as configurações de conexão da configuração, em vez de presumir uma porta fixa ou um banco já existente.

Passos

1. Inicie o motor uma vez por execução de testes, e não por teste. O Testcontainers se descreve como uma ferramenta que fornece instâncias leves e descartáveis de bancos de dados em contêineres Docker, iniciadas a partir do código de teste e removidas depois; a alternativa simples é usar docker run com uma porta publicada aleatória, obtida a partir do runtime.
2. Coloque o diretório de dados em um mount tmpfs (--tmpfs no docker run) e relaxe as configurações de durabilidade do motor para uso fora de produção, já que os dados são descartáveis.
3. Aplique as migrações uma só vez em um banco-modelo (template). A documentação do PostgreSQL afirma que CREATE DATABASE funciona copiando um banco existente; assim, CREATE DATABASE t_42 TEMPLATE t_base entrega a cada arquivo de teste uma cópia nova sem reexecutar as migrações. O banco de origem não pode ter outras conexões enquanto é copiado.
4. Escolha uma única estratégia de isolamento e aplique-a em todo lugar: um banco novo por arquivo de teste, uma transação por teste revertida ao final (rollback) ou o truncamento das tabelas que o teste tocou.
5. Gere as configurações de conexão a partir do contêiner em execução e passe-as pelo mesmo caminho de configuração que a aplicação usa em produção, de modo que o teste também cubra o tratamento da configuração.
6. Fixe a tag da imagem na versão major de produção e use exatamente a mesma configuração localmente e no CI.

Resultado esperado

Os testes exercitam o planejador de consultas, as constraints, os níveis de isolamento e as funções de extensão reais; uma execução verde significa que o esquema e as consultas estão de acordo, e uma migração que quebra uma consulta falha antes do deploy.

Limites e base de verificação

A inicialização acrescenta alguns segundos a cada execução; por isso, mantenha os testes unitários puros em uma suíte separada e mais rápida. O Testcontainers documenta a reutilização de um contêiner entre execuções como um recurso experimental, opcional e inadequado para uso em CI. Uma transação revertida não consegue testar código que faz commit, usa várias conexões ou depende de triggers disparados no commit. Um banco de dados gerenciado em nuvem pode diferir da imagem em extensões e parâmetros; este método testa o motor, não o serviço gerenciado. Não se afirma nenhum tempo de execução.