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 de uma máquina para outra
Renderização de fontes: o culpado número um
A renderização de fontes é, de longe, a principal fonte de diferenças entre screenshots. Cada sistema operacional utiliza seu próprio motor de renderização tipográfica. O macOS utiliza o Core Text, que prioriza a fidelidade ao desenho da fonte. O Windows utiliza o DirectWrite, que prioriza o alinhamento à grade de pixels. O Linux utiliza o FreeType, cujo comportamento varia conforme a configuração do fontconfig.
O resultado: o mesmo texto, com a mesma fonte, no mesmo tamanho, na mesma página, não produz os mesmos pixels conforme o sistema operacional. As diferenças às vezes são invisíveis a olho nu — um deslocamento de pixel, uma suavização ligeiramente diferente. Mas uma ferramenta de comparação pixel a pixel detecta essas variações e as sinaliza como regressões.
E não para por aí. As fontes disponíveis variam de um sistema para outro. Se o seu CSS especifica uma fonte que não está instalada na máquina de CI, o navegador utiliza uma fonte substituta (fallback). Essa substituição pode alterar o espaçamento, a altura de linha, a largura dos caracteres — e, consequentemente, o layout inteiro.
O motor de renderização do navegador
Mesmo utilizando o mesmo navegador (Chrome, por exemplo), a versão exata do motor de renderização influencia o resultado. O Chrome 120 não produz exatamente a mesma renderização que o Chrome 122 para certas propriedades CSS.
Resolução e escala
O DPI do seu monitor influencia a renderização. Uma tela Retina (2x) produz capturas em uma resolução diferente de uma tela padrão (1x). Servidores de CI geralmente não possuem telas físicas. Eles utilizam um framebuffer virtual (Xvfb no Linux) cuja configuração de DPI pode diferir da sua estação de trabalho 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
Um contêiner Docker para teste visual deve incluir: todas as fontes que sua aplicação utiliza (instaladas localmente, não baixadas em tempo de execução), um navegador em versão fixa, uma configuração de renderização explícita (fontconfig, DPI do framebuffer virtual, configurações de anti-aliasing) e as dependências de sistema necessárias 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.
O Dockerfile como documentação viva
Seu Dockerfile é uma descrição completa e executável do seu ambiente de teste. Quando um novo membro entra na equipe, ele não precisa adivinhar quais fontes instalar ou qual versão do Chrome utilizar. Ele sobe o contêiner e obtém o mesmo ambiente que todos os outros.
Dockerizar seu setup de teste visual: passos-chave
Passo 1: Fixar as versões
Liste tudo que participa da renderização das suas páginas. Fixe cada item a uma versão precisa. Nada de "latest", nada de ranges semânticos. Em teste visual, "qualquer um" é sinônimo de "falsos positivos".
Passo 2: Construir a imagem
Comece a partir de uma imagem base que inclua o navegador em versão fixa. Adicione fontes, configuração do fontconfig e ferramentas necessárias. Ordene as instruções da menos frequente a mais frequente em mudanças (SO, navegador, fontes no topo; código da aplicação, arquivos de teste embaixo) para otimizar o cache de build.
Passo 3: Validar a reprodutibilidade
Construa a imagem. Execute os testes visuais. Construa novamente. Execute de novo. Os resultados devem ser idênticos. Valide em duas máquinas diferentes.
Passo 4: Integrar no pipeline CI/CD
Faça push da sua imagem para um registry e referencie-a na configuração da sua CI. Ao atualizar a imagem, regenere as baselines.
Passo 5: Gerenciar atualizações
Estabeleça um ritmo mensal de atualização. Atualize a versão do navegador no Dockerfile, reconstrua, reexecute os testes, examine as diferenças e atualize as baselines para as mudanças esperadas.
Benefícios além da reprodutibilidade
Paralelização
Contêineres Docker iniciam em segundos. Lance 10, 20, 50 contêineres em paralelo para testar tantas páginas simultaneamente. Testes que levavam 30 minutos em modo sequencial passam a 3 minutos em paralelo.
Isolamento de testes
Cada contêiner parte de um estado limpo. Sem cache persistente do navegador, sem cookies residuais. Cada teste inicia em um ambiente virgem, eliminando uma categoria inteira de falsos positivos.
Onde Delta-QA se encaixa nessa abordagem
O Delta-QA simplifica consideravelmente a equação Docker. Sua análise estrutural é inerentemente menos sensível a variações de renderização entre ambientes. Onde uma ferramenta de comparação pixel a pixel sinaliza cada diferença de subpixel decorrente da renderização de fontes, o Delta-QA analisa as propriedades CSS calculadas — margens, paddings, dimensões, posicionamento — que são as mesmas independentemente do ambiente de renderização.
Isso não significa que o Docker é desnecessário com o Delta-QA. Um ambiente reprodutível continua sendo a melhor prática. Mas a tolerância a variações de ambiente é incomparavelmente maior. Para equipes que não podem ou não querem investir na construção de uma imagem Docker dedicada, essa é uma vantagem decisiva. O Delta-QA oferece resultados confiáveis mesmo em ambientes imperfeitos.
Erros frequentes a evitar
Usar "latest" como tag da imagem
Essa é a causa número um de testes instáveis em contextos Docker. Fixe uma versão precisa e atualize-a de forma controlada.
Esquecer as fontes
Se sua aplicação utiliza Inter, Roboto e uma fonte customizada, instale-as no contêiner. Não dependa de downloads em tempo real a partir do Google Fonts.
Ignorar o tamanho do viewport
Uma tela virtual de 1920x1080 não significa um viewport de 1920x1080. Configure o viewport explicitamente na sua ferramenta de teste visual.
Não versionar a imagem
Faça push das imagens para um registry, marque-as com um hash ou data e referencie a tag exata no seu pipeline de CI.
FAQ
Docker é obrigatório para teste visual?
Não, mas sem Docker você gastará tempo considerável gerenciando falsos positivos.
Qual imagem base Docker você recomenda?
As imagens oficiais do Playwright (mcr.microsoft.com/playwright) são um excelente ponto de partida.
Docker atrasa os testes visuais?
A inicialização do contêiner adiciona alguns segundos. Em contrapartida, o Docker viabiliza uma paralelização massiva, resultando geralmente num saldo de tempo líquido positivo.
Como lidar com Google Fonts em um contêiner Docker?
Baixe os arquivos de fontes e instale-os localmente no contêiner via Dockerfile. Não dependa de downloads em tempo real a partir dos servidores do Google.
Docker Desktop pode ser utilizado para teste visual local?
Sim, e é recomendado durante o desenvolvimento. Você roda o mesmo contêiner da CI na sua estação de trabalho.
O Delta-QA precisa de Docker para funcionar?
Não. O Delta-QA funciona sem Docker graças à sua abordagem de análise estrutural, que é inerentemente menos sensível a variações de renderização. O Docker continua sendo a melhor prática para máxima reprodutibilidade, mas não é um pré-requisito para obter resultados confiáveis com o Delta-QA.
Para aprofundar
- Teste Visual e Headless Browsers: O que o Chromium Sem Cabeca Faz (e Nao Faz) aos Seus Screenshots
- Teste Visual e Imagens Retina: Se Você Não Testa em HiDPI, Não Vê o Que Seus Usuários Veem
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.