Visual testing no GitLab CI: integrar o teste visual ao seu pipeline GitLab

Visual testing no GitLab CI: integrar o teste visual ao seu pipeline GitLab

O teste visual (visual testing) é um método de verificação automatizada que compara screenshots de uma interface web entre duas versões para detectar regressões gráficas (um elemento deslocado, uma cor modificada, um componente que transborda do seu contêiner).

Usamos o GitLab no dia a dia na Delta-QA. Nossos repositórios, nossos pipelines, nossas merge requests, nosso CI/CD: tudo roda no GitLab. Não é uma escolha por padrão: é uma escolha deliberada por uma plataforma que oferece um pipeline integrado nativamente, um registro de contêineres e uma filosofia DevOps coerente de ponta a ponta.

Quando falamos de teste visual no GitLab CI, não estamos repetindo uma documentação lida na véspera. Compartilhamos o que aprendemos usando de verdade. Este artigo cobre as abordagens disponíveis, as particularidades do GitLab CI que afetam o teste visual e como obter um pipeline de regressão visual confiável.

O essencial em uma página (definição, automação sem código, grade de escolha de uma ferramenta): Testes de regressão automatizados, sem código.

Ainda não está pronto para mexer no seu .gitlab-ci.yml? Comece o teste visual fora do pipeline: o Delta-QA compara suas telas sem código, com conta gratuita e sem cartão de crédito. Testar o Delta-QA grátis →

Por que o GitLab CI se presta bem ao teste visual

O GitLab CI tem características que o tornam particularmente adequado ao teste visual, características que os usuários de GitHub Actions ou Jenkins não têm por padrão.

Os artefatos nativos

O GitLab CI gerencia nativamente os artefatos de pipeline. Quando um teste visual produz relatórios HTML, imagens de diff ou screenshots, você os declara como artefatos e eles ficam acessíveis direto na interface da merge request. Não é preciso um serviço externo para armazenar e consultar os resultados.

É uma vantagem subestimada. No GitHub Actions, você precisa configurar um upload de artefato separado ou usar um serviço de terceiros para tornar os resultados acessíveis. No GitLab, é nativo.

Os ambientes de revisão

O GitLab oferece as Review Apps: ambientes efêmeros implantados automaticamente para cada merge request. Sua aplicação roda em um ambiente dedicado, acessível por uma URL temporária. É o ambiente ideal para o teste visual: estável, isolado e representativo da produção.

Os runners próprios

O GitLab permite usar runners hospedados na sua própria infraestrutura. Para o teste visual, isso é crucial: você controla o ambiente de renderização (SO, fontes, GPU), o que reduz os falsos positivos ligados a diferenças de ambiente. Usamos runners dedicados com configuração fixa para garantir a reprodutibilidade das capturas.

O registro de contêineres integrado

Todo projeto GitLab tem um registro de contêineres. Você pode guardar ali uma imagem Docker pré-configurada para o teste visual (com as fontes certas, o navegador certo, as dependências certas) e usá-la como base dos seus jobs de teste. Isso elimina uma das principais fontes de instabilidade.

As abordagens para o teste visual no GitLab CI

Playwright em um job do GitLab CI

O Playwright é a ferramenta open source mais robusta para teste visual em CI. Seu método nativo toHaveScreenshot() cuida da captura, da comparação e dos retries automáticos.

A integração com o GitLab CI. Você cria um job no seu .gitlab-ci.yml que usa a imagem Docker oficial do Playwright, executa seus testes e publica os resultados como artefatos. Os relatórios HTML do Playwright podem ser consultados direto no GitLab.

Para a estrutura exata do arquivo YAML, peça ao seu copiloto de IA (ele é imbatível na sintaxe do GitLab CI, é praticamente a única coisa em que não alucina, ainda). Falando sério, a documentação oficial do Playwright para ambientes de CI é sua melhor referência.

O que funciona bem. A imagem Docker oficial do Playwright inclui todos os navegadores e as dependências de sistema necessárias. Combinada com o registro de contêineres do GitLab, você pode criar uma imagem derivada com suas fontes e configurações específicas. Os artefatos do GitLab tornam os relatórios de teste acessíveis sem configuração adicional.

Os limites no contexto GitLab. As baselines devem ser geradas no ambiente de CI, não localmente. É uma regra universal do teste visual, mas o GitLab facilita as coisas: você pode disparar um pipeline manualmente para regenerar as baselines. A gestão das baselines no Git continua sendo um desafio (arquivos binários, conflitos de merge), mas o GitLab LFS é integrado nativamente.

Percy com GitLab CI

O Percy (BrowserStack) oferece uma integração oficial com o GitLab CI. O SDK do Percy captura os snapshots durante o seu pipeline e os envia à nuvem do Percy para comparação e revisão.

O que funciona. O Percy detecta automaticamente a branch e a merge request do GitLab. Os resultados aparecem como um status externo na sua MR. O cross-browser é tratado no lado da nuvem.

Os limites. A cobrança por snapshot continua sendo um assunto. E você adiciona uma dependência externa ao pipeline: se o Percy estiver indisponível, seu check fica pendente. Para uma equipe que escolheu o GitLab justamente para dominar sua infraestrutura, essa dependência externa pode contradizer a filosofia.

BackstopJS no GitLab CI

O BackstopJS funciona no GitLab CI pela sua imagem Docker oficial. Os relatórios HTML se encaixam perfeitamente no sistema de artefatos do GitLab.

O que funciona. O relatório HTML do BackstopJS é um dos mais visuais e legíveis do ecossistema. Publicado como artefato do GitLab, pode ser consultado direto no navegador a partir da interface da MR. A configuração por cenários JSON é explícita e versionável.

Os limites. O projeto passou por períodos de manutenção intermitente (verifique a atividade recente antes de se comprometer). A configuração pode ficar verbosa em aplicações complexas, e você precisa gerenciar manualmente a iteração sobre suas páginas ou componentes.

Delta-QA no GitLab CI: o SDK Vision

É pelos seus testes Playwright que o Delta-QA entra em um pipeline do GitLab CI, com o SDK Vision.

Como funciona. Você guarda a chave de API em uma variável CI/CD mascarada (DELTAQA_API_KEY) e adiciona vision.check() nas páginas que os seus testes devem verificar. O job executa npx playwright test como de costume. Para cada check, o Delta-QA compara a página com a sua referência como faria o olho humano e nomeia no relatório os elementos que mudaram.

O que é diferente. Sem baselines para guardar no seu repo: as referências vivem no seu espaço Delta-QA, uma por branch; o SDK não lê nem o git nem a CI: uma linha do seu job informa a branch, a branch de base e o commit. Uma diferença não julgada faz o job falhar, e o log traz o link do relatório, que diz qual elemento mudou; ali se julga "Voulu" (pretendida) ou "Bug". Os testes que informam o mesmo commit formam uma versão, mesmo distribuídos em vários jobs em paralelo.

E sem código. Os fluxos gravados no Delta-QA pela equipe de QA são julgados no mesmo espaço. O SDK cobre Playwright em TypeScript e JavaScript, em Chromium; ele é oferecido primeiro em acesso antecipado, e o acesso é solicitado a partir da própria página.

Antes de escrever o menor job de CI, meça o que o teste visual detecta nas suas páginas. O Delta-QA captura e compara suas telas em poucos cliques, com conta gratuita e sem cartão de crédito. Testar o Delta-QA grátis →

As particularidades do GitLab CI que você precisa conhecer para o teste visual

O cache vs os artefatos

É uma distinção que muita gente confunde. O cache do GitLab CI é compartilhado entre os pipelines de um mesmo projeto (serve para acelerar os jobs: dependências npm, navegadores do Playwright). Os artefatos são as saídas de um job específico: relatórios de teste, screenshots, diffs.

Para o teste visual, use o cache para os navegadores e as dependências, e os artefatos para os resultados de teste. Nunca coloque as baselines em cache (elas devem viver no repo para serem versionadas junto com o código).

Os stages e as dependências entre jobs

O GitLab CI organiza os jobs em stages sequenciais. O teste visual deve estar em um stage que roda depois da implantação da sua Review App. Um padrão comum:

  1. build: compilação da aplicação
  2. deploy-review: implantação da Review App
  3. test-visual: teste visual na Review App
  4. cleanup: remoção do ambiente

A diretiva needs do GitLab CI permite criar dependências explícitas entre jobs sem passar pelos stages sequenciais, o que pode acelerar o seu pipeline.

As variáveis de ambiente protegidas

Os tokens de API dos serviços em nuvem (Percy, Chromatic) devem ser guardados como variáveis CI/CD no GitLab. Atenção: as variáveis protegidas só estão disponíveis em branches protegidas. Se as suas feature branches não forem protegidas, o teste visual com um serviço em nuvem falhará silenciosamente: uma armadilha clássica.

Os limites de tempo e de memória

O teste visual consome muitos recursos. A renderização de páginas em um navegador headless consome memória, e a comparação de imagens leva tempo. Os runners compartilhados do GitLab.com têm limites de tempo (geralmente uma hora por job) e de memória. Para suítes de teste visual grandes, recomendam-se runners próprios com recursos dedicados.

Construir um pipeline de teste visual robusto

Esta é a abordagem que recomendamos, baseada na nossa própria experiência.

Comece pequeno e focado

Não teste visualmente todas as suas páginas no primeiro dia. Identifique as cinco a dez páginas mais críticas (as que os seus usuários veem primeiro, aquelas em que uma regressão visual tem maior impacto no negócio). Depois amplie progressivamente.

Use Review Apps como alvo

Em vez de subir um servidor local no job de CI, implante uma Review App e teste-a. A vantagem: o ambiente é estável, acessível e representativo. A desvantagem: você soma a duração da implantação ao pipeline. O compromisso vale a pena.

Estabilize o seu ambiente de renderização

Crie uma imagem Docker dedicada ao teste visual, guardada no seu registro do GitLab. Inclua as fontes usadas pela aplicação, a versão exata do navegador e todas as dependências de sistema. Versione essa imagem. Quando o ambiente de renderização está fixo, os falsos positivos caem drasticamente.

Comece em modo não bloqueante

Configure o seu job de teste visual com allow_failure: true nas primeiras semanas. Isso permite que a equipe se familiarize com os resultados sem que o teste visual bloqueie as merge requests. Estabelecida a confiança e controlados os falsos positivos, passe para o modo bloqueante.

Notifique com inteligência

O GitLab CI pode enviar notificações por vários canais (Slack, e-mail, webhook). Configure as notificações de teste visual para alertar apenas nas falhas, não nos sucessos. O objetivo é chamar a atenção quando necessário, não afogar a equipe em mensagens.

Aproveitar os artefatos como sistema de referências

Os artefatos do GitLab não servem apenas para publicar relatórios: bem organizados, tornam-se a espinha dorsal da sua estratégia de referências. Duas práticas fazem a diferença.

Estruture os artefatos de forma legível

Não empilhe todos os screenshots num nível só. Crie uma árvore clara: uma pasta por página testada, contendo o screenshot de referência, o screenshot atual e o diff. Coloque um relatório HTML na raiz para navegar entre os resultados. Quando um teste falha, o revisor abre o navegador de artefatos integrado do GitLab, vai até a página em questão e vê a diferença imediatamente, sem sair da interface.

Use os artefatos da main como referências

Em vez de guardar as baselines no repo, você pode aproveitar os artefatos do último pipeline bem-sucedido na branch principal como conjunto de referências. O GitLab CI permite baixar os artefatos de um job específico em uma branch específica pela sua API.

Concretamente, o job de teste visual da sua branch feature começa baixando os screenshots de referência dos artefatos do último pipeline da main. Em seguida, captura os screenshots da branch feature, compara os dois conjuntos e guarda seus próprios resultados como artefatos do pipeline atual. Nenhuma baseline binária polui o seu histórico do Git.

Uma política de retenção em dois níveis

A duração de retenção dos artefatos do GitLab é configurável, e para o teste visual uma política em dois patamares funciona bem:

  • Branch principal: 30 dias (ou mais). Esses artefatos servem de referências estáveis para todas as comparações.
  • Branches feature: 7 dias. O tempo para a merge request ser tratada e mergeada.

Ajuste conforme o seu ritmo: uma equipe com ciclos longos (branches que vivem várias semanas) precisará de retenção maior na main e terá de fazer rebase regularmente ou rebaixar as referências mais recentes a cada execução, para evitar comparar com baselines vencidas.

FAQ

O GitLab CI é tão bom quanto o GitHub Actions para teste visual?

Para o teste visual especificamente, o GitLab CI tem vantagens nativas: artefatos integrados, Review Apps, registro de contêineres e runners próprios. Esses recursos facilitam montar um ambiente de teste visual estável e reproduzível. O GitHub Actions tem seu próprio marketplace rico, mas alguns desses recursos exigem configurações adicionais.

São necessários runners próprios para o teste visual no GitLab CI?

Não é obrigatório, mas é fortemente recomendado. Os runners compartilhados do GitLab.com funcionam, mas a configuração de hardware variável pode introduzir diferenças de renderização. Um runner próprio com configuração fixa (fontes, navegador, resolução) elimina essa fonte de falsos positivos e costuma oferecer melhor desempenho.

Como gerenciar as baselines de teste visual em um repositório GitLab?

Se você usa Playwright ou BackstopJS, as baselines (arquivos PNG) vivem no seu repo. Ative o GitLab LFS para evitar que os arquivos binários inflem o seu histórico do Git. Para conflitos de merge nas baselines, a estratégia mais simples é aceitar as novas baselines da branch de origem e regenerar se necessário. Com o Delta-QA, as baselines são gerenciadas pela ferramenta e não poluem o seu repo.

Dá para usar as Review Apps do GitLab como ambiente de teste visual?

Sim, e é inclusive a abordagem que recomendamos. A Review App fornece um ambiente estável e isolado para cada merge request. Seu job de teste visual espera a Review App ser implantada, captura os screenshots na URL temporária e compara com as referências. É mais confiável do que um servidor subido na hora dentro do job de CI.

O teste visual no GitLab CI funciona com monorepos?

Sim. O GitLab CI suporta regras condicionais que permitem disparar o teste visual apenas se os arquivos de front-end tiverem sido modificados. Combinado com a diretiva only:changes, você evita executar testes visuais inúteis quando só o backend mudou. É essencial para manter um pipeline rápido em um monorepo.

Qual é a melhor imagem Docker para teste visual no GitLab CI?

A imagem oficial do Playwright (mcr.microsoft.com/playwright) é um excelente ponto de partida. Ela inclui os navegadores e as dependências de sistema. Para um ambiente ainda mais estável, crie uma imagem derivada que adicione as fontes da sua aplicação e fixe as versões exatas. Guarde-a no registro de contêineres do seu projeto GitLab para acesso rápido.

Conclusão

O GitLab CI é uma plataforma naturalmente adequada ao teste visual. Seus recursos nativos (artefatos, Review Apps, registro de contêineres, runners próprios) resolvem problemas que outras plataformas de CI exigem tratar manualmente.

Mas a plataforma não faz tudo. O teste visual em CI continua sendo um desafio de engenharia: estabilizar a renderização, gerenciar as baselines, tratar os falsos positivos e construir um workflow de revisão que funcione para toda a equipe.

Se você está no GitLab e quer adicionar o teste visual ao seu pipeline sem a complexidade dos scripts de teste e da gestão manual de baselines, o Delta-QA foi concebido para se integrar nativamente ao seu workflow do GitLab CI.

Pronto para tornar suas merge requests mais confiáveis com o teste visual? Inicie sua primeira comparação com o Delta-QA, de graça e sem cartão de crédito, antes mesmo de mexer no seu .gitlab-ci.yml. Testar o Delta-QA grátis →