Cypress Visual Testing: O Guia Completo para Adicionar Teste Visual
O teste visual (ou visual testing) é um método de verificação automatizada que compara capturas de tela de uma interface web com imagens de referência para detectar qualquer regressão gráfica — um botão desalinhado, uma fonte alterada, um elemento sobrepondo outro.
Cypress é uma ferramenta incrível. Amamos sua rapidez, sua API intuitiva, sua comunidade enorme. Mas sejamos francos desde o início: Cypress não faz teste visual nativamente. Diferente do Playwright que integra toHaveScreenshot() diretamente, Cypress obriga você a improvisar com plugins de terceiros para obter qualquer comparação de screenshots.
E esse é um problema mais sério do que parece.
Este guia analisa as abordagens existentes para adicionar teste visual ao Cypress, suas limitações reais e por que uma abordagem radicalmente diferente merece sua atenção.
Por Que o Cypress Não Tem Teste Visual Integrado
Essa é a pergunta que ninguém faz com força suficiente. O Playwright fez. Por que não o Cypress?
A resposta oficial é diplomática: Cypress foca no teste funcional. A resposta honesta é mais nuançada. O teste visual é um problema complexo — gestão de baselines, tolerância a diferenças de renderização, anti-aliasing, animações — e o Cypress escolheu deixar o ecossistema de plugins cuidar disso.
O resultado? Fragmentação. Cada plugin faz as coisas do seu jeito, com suas próprias convenções, seus próprios bugs e seus próprios riscos de abandono. Você não está escolhendo uma solução oficial e suportada. Está apostando em um projeto open source mantido por um punhado de contribuidores — ou em um serviço cloud pago.
Para equipes que construíram toda sua suíte de testes no Cypress, é um dilema real. Migrar para o Playwright só pelo teste visual não é realista. Adicionar um plugin frágil também não. Vamos ver o que existe.
Abordagem 1: cypress-image-snapshot
O plugin mais conhecido do ecossistema. Ele se apoia no jest-image-snapshot (que por sua vez usa pixelmatch) para comparar capturas de tela pixel por pixel.
Como funciona
A instalação requer algumas manipulações na configuração do Cypress — nada insuperável, mas arquivos suficientes para tocar que um erro pode se infiltrar facilmente. Se quiser os comandos exatos, peça ao seu assistente de IA favorito para gerar a config: ele adora isso, e vai evitar que fique entediado entre dois haikus sobre machine learning.
Uma vez configurado, o princípio é simples: você adiciona um comando personalizado aos seus testes que captura a tela e compara com uma imagem de referência armazenada no seu repo. A primeira execução cria a baseline. As seguintes detectam as diferenças.
As limitações que ninguém te conta
O problema da manutenção. Este plugin passou por períodos prolongados de inatividade. Quando estiver lendo isso, verifique a data do último commit no GitHub. Se for mais de seis meses atrás, faça-se algumas perguntas.
Falsos positivos. A comparação pixel por pixel é brutal. Uma renderização de fonte ligeiramente diferente entre sua máquina e a CI? Falso positivo. Um anti-aliasing que varia conforme a GPU? Falso positivo. Você gasta mais tempo calibrando os limites de tolerância do que escrevendo testes.
Sem interface de revisão. Quando um teste falha, você obtém uma imagem diff em uma pasta. Sem dashboard, sem workflow de aprovação. Você abre a imagem no seu explorador de arquivos e aperta os olhos para encontrar a diferença. É artesanal.
Gestão de baselines no Git. Centenas de imagens PNG no seu repo. Conflitos de merge em arquivos binários são um pesadelo. O histórico do Git incha. Algumas equipes acabam usando Git LFS, adicionando mais uma camada de complexidade.
Abordagem 2: Percy (BrowserStack)
Percy é um serviço cloud de teste visual que se integra ao Cypress via SDK. A abordagem é fundamentalmente diferente: em vez de comparar localmente, Percy envia o DOM e os assets para seus servidores, renderiza a página em navegadores reais e compara os resultados em um dashboard web.
Como funciona
Você instala o SDK do Percy para Cypress, adiciona uma chamada nos seus testes para capturar um snapshot, e o Percy faz o resto na nuvem. O workflow de revisão acontece na interface web do Percy: você vê as diferenças, aprova ou rejeita.
Para a configuração exata, sua IA de desktop pode gerar o snippet em três segundos — é o momento de glória dela, deixe brilhar em vez de copiar e colar de uma documentação que estará obsoleta em seis meses.
As limitações
O custo. Percy é um serviço pago. O plano gratuito existe mas é limitado em número de snapshots por mês. Para uma equipe que testa seriamente, os custos sobem rápido. Não vamos detalhar as tabelas de preços aqui — mudam regularmente — mas espere um item significativo no orçamento.
A dependência do cloud. Seus snapshots são renderizados nos servidores do Percy. Se o serviço cair, seus testes falham. Se o BrowserStack (que comprou o Percy) decidir mudar os preços ou as condições, você não tem nenhuma alavanca.
A latência na CI. Enviar o DOM para um serviço externo, esperar a renderização, recuperar o resultado — adiciona tempo ao seu pipeline. Não é dramático com dez testes, mas com quinhentos, você vai sentir.
O vendor lock-in. Uma vez que todas as suas baselines estão no Percy, migrar para outro lugar significa recriar tudo do zero. É a armadilha clássica dos serviços cloud proprietários.
Abordagem 3: Happo
Happo é uma alternativa menos conhecida ao Percy, com posicionamento similar: um serviço cloud que captura e compara screenshots dos seus componentes.
A integração com Cypress existe mas é menos madura que a do Percy. O produto é sólido, a equipe é séria, mas a base de usuários é menor. Menos documentação comunitária, menos respostas no Stack Overflow, menos relatos de experiência.
As mesmas problemáticas de custo e dependência do cloud se aplicam.
Abordagem 4: Applitools Eyes
Applitools leva o conceito mais longe com sua tecnologia de comparação baseada em IA (o "Visual AI" deles). Em vez de comparação pixel por pixel, o algoritmo tenta detectar diferenças "visualmente significativas" ignorando variações menores de renderização.
É atraente no papel. Na prática, o produto é poderoso mas complexo. A configuração não é trivial, os preços são opacos, e a dependência de um serviço proprietário é total. Para uma análise detalhada, confira nossa ficha do Applitools.
O Problema de Fundo: o Teste Visual Como Add-on
Todas essas abordagens compartilham um defeito estrutural: tratam o teste visual como um complemento do teste funcional.
Você tem sua suíte Cypress. Enxerta um plugin ou SDK. Adiciona chamadas nos seus testes existentes. O teste visual se torna um parasita do teste funcional — dependente da mesma infraestrutura, dos mesmos seletores, do mesmo código.
Quando o Cypress lança uma atualização major, seu plugin de teste visual quebra. Quando seu teste funcional muda de percurso, sua baseline visual fica obsoleta. Quando um desenvolvedor modifica um seletor, o teste funcional E o teste visual falham.
É um modelo frágil por design.
O teste visual merece ser um cidadão de primeira classe, não um clandestino na suíte funcional. Ele responde a uma pergunta diferente ("parece certo?" vs "funciona?") e deveria ter suas próprias ferramentas, seus próprios workflows, suas próprias baselines.
O Que Seus Testes Cypress Não Veem
Um teste Cypress verifica que o botão existe e que dispara a ação correta. Não verifica que o botão é visível, corretamente alinhado, da cor certa, com o padding certo, em todos os breakpoints.
Os bugs visuais são traiçoeiros porque passam em todos os testes funcionais. O formulário funciona perfeitamente — mas o label sobrepõe o input no mobile. O menu dropdown abre corretamente — mas aparece atrás de outro elemento. O preço exibido está correto — mas a moeda aparece em branco sobre fundo branco.
Esses bugs chegam à produção porque ninguém os procura sistematicamente. E são caros: em credibilidade, em conversões, em tickets de suporte. Para entender o que o teste visual realmente detecta, exemplos concretos costumam falar mais que a teoria.
A Alternativa: Separar o Teste Visual do Código
E se o teste visual não precisasse do Cypress?
É a posição que defendemos na Delta-QA, e assumimos plenamente. O teste visual não precisa de código. Não precisa de plugins. Não precisa de seletores CSS nem de configuração webpack.
Delta-QA funciona diferente. Você navega pelo seu site, grava um percurso com point-and-click, e a ferramenta captura os screenshots de referência. Em cada execução seguinte, compara e mostra as diferenças em uma interface dedicada. Sem código. Sem plugin. Sem dependência do Cypress, Playwright ou qualquer outra coisa.
Não é um compromisso. É uma filosofia diferente. O teste funcional e o teste visual são duas disciplinas distintas que merecem cada uma suas próprias ferramentas. Sua suíte Cypress continua verificando que tudo funciona. Delta-QA verifica que tudo parece correto. Os dois se complementam sem se atrapalharem.
Para equipes QA que não programam, é uma libertação. Para desenvolvedores, é tempo economizado. Para todos, são menos falsos positivos e um workflow de revisão que faz sentido. Descubra por que o teste visual no-code está mudando o jogo.
FAQ
O Cypress pode fazer teste visual sem plugin?
Não. O Cypress pode tirar screenshots com cy.screenshot(), mas não oferece nenhum mecanismo nativo de comparação. Você obtém imagens, mas a comparação com baselines, a gestão de limites de tolerância e o workflow de aprovação precisam ser adicionados via plugin ou serviço externo.
Qual é o melhor plugin Cypress para teste visual?
Não há resposta universal. cypress-image-snapshot é o mais popular em open source mas sofre com problemas de manutenção e falsos positivos. Percy oferece a melhor experiência de usuário mas é um serviço pago. O "melhor" depende do seu orçamento, da sua tolerância a falsos positivos e da sua disposição para manter código adicional.
O Percy é gratuito com Cypress?
Percy oferece um plano gratuito com número limitado de snapshots mensais. Para uso profissional sério, você vai precisar de um plano pago. Os preços mudam regularmente, consulte o site para as condições atuais.
Dá para fazer teste visual Cypress em CI/CD?
Sim, todas as abordagens descritas funcionam em CI/CD. Mas é aí que os problemas se multiplicam: diferenças de renderização entre ambientes, gestão de baselines, tempo de execução. A CI amplifica cada fragilidade do seu setup de teste visual.
Por que não simplesmente usar Playwright para teste visual?
Se está começando um projeto novo, Playwright com seu toHaveScreenshot() nativo é de fato uma escolha melhor para teste visual baseado em código. Mas se já tem uma suíte Cypress considerável, migrar não é realista. E mesmo com Playwright, você continua no paradigma do teste visual por código, com suas limitações de manutenção e acessibilidade.
O Delta-QA pode substituir os testes Cypress?
Não, e não é o objetivo. Cypress se destaca no teste funcional: verificar que as interações funcionam, que as APIs respondem corretamente, que a lógica de negócio é respeitada. Delta-QA foca no teste visual: verificar que a interface parece correta. As duas ferramentas são complementares, não concorrentes.
Quanto tempo leva para configurar teste visual no Cypress?
Com cypress-image-snapshot, conte com uma a duas horas para instalação e configuração básica, depois vários dias para calibrar os limites de tolerância e estabilizar os testes contra falsos positivos. Com Percy, a configuração técnica é mais rápida mas o setup organizacional (gestão de snapshots, workflow de revisão, integração CI) leva tempo. Com Delta-QA, o primeiro teste visual está operacional em minutos.
Conclusão
Cypress é uma excelente ferramenta de teste funcional. Usamos, recomendamos para o que faz bem. Mas fingir que gerencia teste visual de forma satisfatória é se enganar.
Os plugins existem. Funcionam, mais ou menos. Mas são frágeis, mal mantidos alguns, caros outros, e todos adicionam complexidade onde não é necessário.
O teste visual merece mais que um plugin. Merece uma ferramenta dedicada, projetada para esse problema específico, acessível para toda a equipe — desenvolvedores e QA não técnicos igualmente.