Teste Visual e Docker: Sem Ambiente Reprodutível, seus Screenshots Não Valem Nada
Ambiente reprodutível: configuração de software idêntica a cada execução — mesmo sistema operacional, mesmas bibliotecas, mesmas fontes, mesmo motor de renderização — garantindo que os resultados de um teste não variem conforme a máquina onde é executado. — Princípio fundamental da engenharia de testes automatizados.
Você implementou teste visual. Compara screenshots. Seus testes passam localmente. E quando rodam na CI, você obtém 47 diferenças sinalizadas — nenhuma correspondendo a um bug real.
Esse cenário foi vivido pela grande maioria das equipes que fazem teste visual. E a maioria tira a conclusão errada: «O teste visual gera muito ruído, não funciona.»
O teste visual funciona perfeitamente. O que não funciona é o seu ambiente.
Um screenshot tirado no macOS com fontes Apple nunca será idêntico ao pixel a um screenshot tirado no Ubuntu com fontes FreeType. Um navegador em 1920x1080 com escala 100% não produz a mesma renderização que um em 1920x1080 com escala 125%. Anti-aliasing, hinting de fontes, suavização subpixel — tudo difere.
Docker resolve esse problema. E se você faz teste visual sem Docker, está perdendo tempo.
Por que screenshots diferem entre máquinas
Renderização de fontes: culpado número um
Cada SO usa seu próprio motor de renderização tipográfica. macOS usa Core Text, Windows usa DirectWrite, Linux usa FreeType. O mesmo texto, mesma fonte, mesmo tamanho — não produz os mesmos pixels conforme o SO.
Além disso, fontes disponíveis variam entre sistemas. Se seu CSS especifica uma fonte não instalada na máquina de CI, o navegador usa uma fonte substituta que pode alterar todo o layout.
O motor de renderização do navegador
Chrome 120 não produz exatamente a mesma renderização que Chrome 122 para certas propriedades CSS.
Resolução e escala
O DPI do monitor influencia a renderização. Servidores de CI usam framebuffers virtuais cuja configuração pode diferir da máquina de desenvolvimento.
Docker: o ambiente idêntico, sempre
Docker encapsula todo o ambiente de teste em um contêiner. Mesmo SO, mesmas fontes, mesmo navegador, mesma versão — seja no seu Mac, num runner GitHub Actions ou numa instância EC2.
O que o contêiner deve conter
Fontes (instaladas localmente), navegador em versão fixa, configuração de renderização explícita (fontconfig, DPI do framebuffer virtual, anti-aliasing), e dependências de sistema para o navegador headless.
A imagem base: não reinvente a roda
As imagens oficiais do Playwright são um excelente ponto de partida. Parta de uma imagem que funciona, adicione suas fontes e configuração específica.
Dockerizar seu setup: passos-chave
- Fixar as versões — nada de "latest", nada de ranges semânticos
- Construir a imagem — camadas estáveis em cima, código que muda embaixo
- Validar a reprodutibilidade — construir duas vezes, resultados devem ser idênticos
- Integrar no CI/CD — push para o registro, referenciar o tag exato
- Gerenciar atualizações — ritmo mensal, regenerar baselines
Benefícios além da reprodutibilidade
Paralelização
Lance 10, 20, 50 contêineres em paralelo. Testes de 30 minutos sequenciais passam a 3 minutos em paralelo.
Isolamento de testes
Cada contêiner parte de um estado limpo. Sem cache nem cookies residuais.
Onde Delta-QA se encaixa
A análise estrutural do Delta-QA é inerentemente menos sensível a variações de renderização. Onde uma comparação pixel a pixel sinaliza cada diferença de subpixel, Delta-QA analisa propriedades CSS calculadas — margens, paddings, dimensões, posicionamento — que são iguais independentemente do ambiente.
Isso não significa que Docker é inútil com Delta-QA. Mas a tolerância a variações é incomparavelmente maior. Para equipes que não podem investir em uma imagem Docker dedicada, é uma vantagem decisiva.
Erros frequentes a evitar
- Usar "latest" como tag — primeira causa de testes instáveis
- Esquecer as fontes — instale-as localmente no contêiner
- Ignorar o tamanho do viewport — configure-o explicitamente na ferramenta
- Não versionar a imagem — push para registro com tag exato
FAQ
Docker é obrigatório para teste visual?
Não, mas sem Docker você gastará tempo considerável gerenciando falsos positivos.
Qual imagem base recomendam?
As imagens oficiais do Playwright (mcr.microsoft.com/playwright).
Docker atrasa os testes?
A inicialização adiciona segundos, mas a paralelização compensa com folga.
Como lidar com Google Fonts no Docker?
Baixe os arquivos e instale-os localmente no contêiner.
Delta-QA precisa de Docker?
Não. Funciona sem Docker graças à análise estrutural. Docker continua sendo boa prática mas não é pré-requisito.
Um screenshot que muda de uma máquina para outra não é um teste. É ruído. Docker transforma suas capturas em evidências confiáveis e reprodutíveis.