Teste Visual Next.js: O Guia Completo para Proteger Suas Apps React SSR
Pontos-chave
- Next.js multiplica os modos de renderização (SSR, SSG, ISR, App Router) e cada um pode produzir um resultado visual diferente para a mesma página
- A hidratação do React é uma fonte importante de regressões visuais invisíveis aos testes funcionais clássicos
- As abordagens baseadas em Storybook não testam a renderização real das suas páginas Next.js em condições de produção
- Uma ferramenta de teste visual framework-agnostic que captura o resultado final no navegador é a única garantia confiável contra regressões visuais no Next.js
O teste visual, segundo a definição do ISTQB (International Software Testing Qualifications Board), designa «a verificação de que a interface de utilizador de um software é exibida em conformidade com as especificações visuais esperadas, comparando capturas de ecrã de referência com o estado atual da aplicação» (ISTQB Glossary, Visual Testing).
Quando você aplica esta disciplina a uma aplicação Next.js, as coisas se complicam consideravelmente. Next.js não é uma simples aplicação React. É um framework que propõe pelo menos quatro modos de renderização diferentes — às vezes na mesma página. E cada modo de renderização pode produzir um resultado visual sutilmente diferente, por razões que seus testes unitários e testes de integração nunca detectarão.
Segundo o State of JS 2024, Next.js é utilizado por 58% dos desenvolvedores React em produção. A Stack Overflow Developer Survey 2024 o posiciona como o framework web mais utilizado atrás do próprio React. Não é um nicho: é o padrão de facto para aplicações React profissionais. E, no entanto, a maioria das equipes que usam Next.js não tem nenhuma estratégia de teste visual adaptada às suas especificidades.
Este artigo vai corrigir isso.
Por que o Next.js torna o teste visual mais importante, não menos
Há um argumento que se ouve frequentemente nas equipes de desenvolvimento: «O Next.js gerencia a renderização para nós, não precisamos verificar visualmente cada página.» É exatamente o contrário da realidade.
Next.js torna o teste visual mais crítico precisamente porque multiplica os caminhos de renderização. Quando você tinha uma simples SPA React com Create React App, a renderização era previsível: tudo acontecia no lado do cliente, no navegador. O resultado visual era determinístico. Com Next.js, a mesma página pode ser renderizada no lado do servidor na primeira requisição, depois hidratada no lado do cliente, depois parcialmente re-renderizada durante uma navegação no lado do cliente. Cada uma dessas etapas pode introduzir uma diferença visual.
O problema da hidratação
A hidratação é o processo pelo qual o React pega o HTML gerado no lado do servidor e o «reativa» no lado do cliente, anexando os event listeners e sincronizando o DOM virtual. Em teoria, o resultado visual deveria ser idêntico antes e depois da hidratação. Na prática, raramente é 100%.
As causas são múltiplas. Os estilos calculados no lado do servidor não levam em conta o tamanho real da janela do navegador. Os componentes que dependem de window ou document exibem um fallback no lado do servidor e seu conteúdo real no lado do cliente. As fontes web nem sempre estão disponíveis no momento da renderização do servidor, causando um flash de texto não estilizado (FOUT) após a hidratação. As animações CSS iniciam no momento da hidratação, não no carregamento da página.
Resultado: existe uma diferença visual entre o que o servidor envia e o que o usuário vê após a hidratação. Essa diferença é frequentemente sutil — um deslocamento de alguns pixels, um texto que reflui, uma imagem que salta. Mas é real e degrada a experiência do usuário.
Nenhum teste unitário pode detectar esse problema. Um teste de integração que verifica a presença de elementos no DOM também não o verá. Apenas um teste visual, que captura uma imagem da página renderizada em um navegador real após a hidratação completa, pode confirmar que o resultado final corresponde ao que você espera.
Os quatro modos de renderização e suas armadilhas visuais
Next.js propõe quatro grandes estratégias de renderização, e cada uma tem suas armadilhas específicas do ponto de vista visual.
A renderização estática (SSG) gera o HTML no momento do build. É a mais previsível, mas atenção: se seus dados mudam entre dois builds, suas páginas estáticas exibem dados desatualizados. Um teste visual que compara a página antes e depois de um rebuild pode revelar mudanças de conteúdo inesperadas — uma imagem de produto atualizada, um preço modificado, um texto traduzido diferentemente.
A renderização do lado do servidor (SSR) gera o HTML a cada requisição. Aqui, o conteúdo é dinâmico por natureza. A mesma URL pode produzir uma renderização visual diferente dependendo da hora, do usuário conectado, dos dados no banco. O teste visual deve lidar com essa variabilidade, o que exige uma estratégia de mocking ou estabilização de dados.
A Regeneração Estática Incremental (ISR) é um híbrido: a página é estática mas se regenera periodicamente em segundo plano. A armadilha visual é a transição entre a versão antiga e a nova. Durante uma breve janela, alguns usuários veem a página antiga, outros a nova. Se seu layout mudou, essa transição pode ser visualmente inconsistente.
O App Router, introduzido no Next.js 13, adiciona os Server Components, o streaming e os layouts aninhados. Os Server Components nunca são executados no lado do cliente. Os Client Components passam pela hidratação. Uma mesma página mistura ambos. O resultado é uma renderização progressiva onde o conteúdo aparece em pedaços — e cada pedaço pode introduzir um deslocamento visual.
As abordagens para testar visualmente uma app Next.js
Agora que você entende por que o teste visual é crítico para Next.js, vamos ver as opções concretas disponíveis.
Playwright: a força bruta
Playwright, desenvolvido pela Microsoft, é o framework de automação de navegadores mais completo em 2026. Suporta Chromium, Firefox e WebKit, oferece uma API poderosa para navegação e inclui funcionalidade nativa de comparação de screenshots.
Para o teste visual de Next.js, Playwright tem uma vantagem importante: testa a página real, em um navegador real, com a renderização completa (SSR + hidratação + CSS + fontes). Você captura o que o usuário realmente vê.
Mas Playwright também tem limitações significativas para o teste visual.
Primeiro, é uma ferramenta de desenvolvedor. Exige escrever e manter scripts de teste. Para cada página, cada viewport, cada estado, você precisa escrever um cenário que navegue até a página, espere o carregamento completo e capture um screenshot. Em uma aplicação de 100 páginas com três viewports e vários estados, a dívida de manutenção explode.
Segundo, a comparação de screenshots do Playwright é básica. Funciona pixel a pixel com um limiar de tolerância configurável. Não entende o conteúdo. Um texto que mudou e uma imagem que se moveu dois pixels são tratados da mesma forma. Os falsos positivos são frequentes, especialmente com a renderização de fontes que varia por SO e antialiasing.
Terceiro, a infraestrutura de baselines é sua responsabilidade. Você armazena os screenshots de referência em seu repositório Git (o que o torna consideravelmente mais pesado) ou em um serviço externo que deve gerenciar por conta própria.
Playwright é uma ferramenta excelente para equipes que têm desenvolvedores dedicados ao testing e querem controle total. Mas para a maioria das equipes, é uma abordagem muito custosa em manutenção para um teste visual sistemático.
Chromatic via Storybook: a ilusão do componente isolado
Chromatic, criado pelos mantenedores do Storybook, é um serviço cloud de teste visual que captura screenshots dos seus componentes Storybook e os compara entre builds.
A abordagem tem um apelo evidente: se você já tem um Storybook, Chromatic se conecta diretamente. A configuração é rápida. A interface de revisão é agradável.
Mas para aplicações Next.js, Chromatic tem um problema fundamental: não testa suas páginas Next.js. Testa seus componentes isolados no Storybook. Porém, as regressões visuais mais perigosas no Next.js não vêm dos componentes individuais — vêm da interação entre componentes, do layout global da página, da renderização SSR, da hidratação, dos layouts aninhados do App Router.
Um botão que se exibe perfeitamente no Storybook pode quebrar o layout da sua página quando colocado em um contêiner flex com outros elementos. Um componente de navegação que passa todos os testes do Chromatic pode provocar um cumulative layout shift (CLS) de 0.3 quando carregado via SSR com uma fonte web. Chromatic nunca verá esses problemas porque nunca vê a página completa.
Chromatic é uma boa ferramenta para design systems. Para testar visualmente uma aplicação Next.js em condições reais, falta a peça essencial: o contexto da página.
Delta-QA: o teste visual da página real, sem código
Delta-QA adota uma abordagem radicalmente diferente. Em vez de testar componentes isolados ou escrever scripts de automação, Delta-QA captura screenshots de suas páginas reais — aquelas que seus usuários veem — e os compara entre duas versões da sua aplicação.
O benefício para Next.js é imediato. Delta-QA não precisa saber que sua aplicação usa Next.js, React, o App Router ou o Pages Router. Captura o resultado final da renderização no navegador, após SSR, após hidratação, após o carregamento das fontes, após a execução do JavaScript cliente. O que compara é exatamente o que seu usuário vê.
Esta abordagem resolve os três problemas que identificamos. As diferenças de hidratação são capturadas, porque o screenshot é tirado após a hidratação completa. As interações entre componentes e layouts são visíveis, porque a página inteira é capturada, não componentes isolados. E a manutenção é mínima, porque não há scripts de teste para escrever nem stories de Storybook para manter.
Delta-QA funciona em no-code: você configura as URLs a monitorar, os viewports a capturar, e a ferramenta faz o resto. Para uma aplicação Next.js de 50 páginas com três viewports, você tem 150 capturas visuais automáticas a cada implantação, sem escrever uma única linha de teste.
Os desafios específicos do Next.js e como gerenciá-los
Mesmo com a ferramenta certa, o teste visual no Next.js requer gerenciar certas especificidades.
O conteúdo dinâmico
Se sua página Next.js exibe um contador de visitantes em tempo real, um timestamp ou dados que mudam a cada requisição, cada screenshot será diferente do anterior — sem que haja regressão visual. Este é o problema do conteúdo dinâmico, e é amplificado pelo SSR e ISR.
A solução é estabilizar o conteúdo antes da captura. Delta-QA permite definir zonas de exclusão em suas páginas: você indica as regiões que contêm conteúdo variável, e a ferramenta as ignora durante a comparação. É mais pragmático do que fazer mock de todas as fontes de dados, e funciona independentemente da complexidade da sua arquitetura de renderização.
As fontes e o FOUT
O Flash of Unstyled Text é um clássico do Next.js. A página é renderizada no lado do servidor com uma fonte do sistema, depois a fonte web carrega e o texto reflui. Se seu screenshot for capturado durante esse flash, não refletirá o estado final da página.
A solução técnica é aguardar o carregamento completo das fontes antes de capturar. A API document.fonts.ready permite garantir isso. Delta-QA integra essa espera nativamente para garantir que o screenshot reflita o estado estável da página.
As animações e transições
Componentes animados — carrosséis, fade-in no scroll, skeleton loaders — introduzem não-determinismo nas capturas visuais. Duas capturas da mesma página podem diferir simplesmente porque a animação estava em um estágio diferente.
A boa prática é desativar as animações CSS e JavaScript no ambiente de teste visual. Delta-QA propõe esta opção nativamente. Para as animações CSS, injeta uma folha de estilo que força animation-duration: 0s e transition-duration: 0s. Para as animações JavaScript, você pode definir um parâmetro que sua aplicação detecte para curto-circuitar as animações.
Os layouts aninhados do App Router
O App Router do Next.js introduz os layouts aninhados: cada segmento de rota pode ter seu próprio layout que envolve os segmentos filhos. É poderoso para a arquitetura da aplicação, mas é um terreno fértil para regressões visuais sutis.
Uma mudança em um layout pai afeta todas as páginas filhas. Uma modificação de padding no layout raiz pode deslocar o conteúdo de dezenas de páginas. Sem teste visual sistemático, você só descobre esse tipo de regressão em produção, quando um usuário reporta que «algo se moveu».
O teste visual cobre essa superfície automaticamente. Se você captura 50 páginas e um layout pai muda, todas as 50 capturas mostrarão a diferença. Você vê imediatamente a extensão do impacto antes de implantar.
Integrar o teste visual no seu pipeline CI/CD Next.js
O teste visual só tem valor se estiver automatizado no seu pipeline de implantação. Veja como estruturar essa integração para Next.js.
O fluxo ideal
O fluxo recomendado segue estas etapas. Você faz push do seu código para um branch. Seu CI builda a aplicação Next.js e a implanta em um ambiente de preview (Vercel, Netlify, ou sua própria infraestrutura). Delta-QA captura os screenshots do ambiente de preview e os compara com as baselines de produção. Os resultados aparecem diretamente no seu merge request ou pull request. Sua equipe revisa as diferenças visuais e aprova ou rejeita as mudanças.
Este fluxo é particularmente natural com Next.js e Vercel, que cria automaticamente um ambiente de preview para cada branch. Delta-QA se conecta a esta URL de preview para capturar os screenshots, o que significa que você testa sua aplicação em condições quase idênticas à produção.
Os ambientes de preview e o SSR
Um ponto de atenção específico do Next.js: suas páginas SSR no ambiente de preview não necessariamente têm acesso aos mesmos dados que em produção. Se sua página inicial exibe os «10 produtos mais populares» via SSR, o ambiente de preview pode mostrar dados diferentes, gerando diferenças visuais legítimas.
A solução é definir claramente quais páginas são «determinísticas» (conteúdo estável entre ambientes) e quais são «variáveis» (conteúdo dependente dos dados). As páginas determinísticas se beneficiam de uma comparação pixel-precisa. As páginas variáveis usam zonas de exclusão ou comparação estrutural que verifica o layout sem se preocupar com o conteúdo exato.
As métricas a acompanhar
Como saber se sua estratégia de teste visual para Next.js funciona? Aqui estão os indicadores a monitorar.
A taxa de regressões visuais detectadas antes da produção mede a eficácia da sua rede de segurança. O objetivo é tender a 100% — nenhuma regressão visual deveria chegar à produção.
A taxa de falsos positivos mede a pertinência das suas capturas. Se mais de 20% das diferenças visuais detectadas são falsos positivos (conteúdo dinâmico, renderização não determinística), sua configuração precisa ser refinada.
O tempo médio de revisão mede o impacto na velocidade de desenvolvimento. Se sua equipe gasta mais de 15 minutos por merge request examinando diferenças visuais, você está capturando muito ruído e pouco sinal.
O número de páginas cobertas em relação ao total de páginas mede a completude da cobertura. O objetivo é 100% das páginas críticas — aquelas que seus usuários veem com mais frequência.
FAQ
O teste visual substitui os testes unitários e os testes de integração para Next.js?
Não, o teste visual complementa as outras formas de teste, não as substitui. Os testes unitários verificam a lógica dos seus componentes. Os testes de integração verificam que os componentes funcionam juntos. O teste visual verifica que o resultado final — o que o usuário vê — corresponde ao que você espera. Os três são necessários para uma cobertura completa. O teste visual é particularmente insubstituível para Next.js porque os problemas de hidratação e layout são invisíveis para as outras duas abordagens.
Como lidar com os Server Components do Next.js no teste visual?
Os Server Components não apresentam dificuldade específica para o teste visual, e essa é justamente sua vantagem. Como o teste visual captura o resultado final no navegador, é agnóstico quanto a se um componente foi renderizado no lado do servidor ou do cliente. Esta é a diferença-chave em relação a uma abordagem como Chromatic, que exige renderizar cada componente em um ambiente específico. Delta-QA vê a página como o usuário a vê, independentemente da arquitetura de renderização subjacente.
Quantos viewports devo testar para uma aplicação Next.js?
No mínimo três: mobile (375px), tablet (768px) e desktop (1440px). Para uma aplicação Next.js usando layouts responsivos complexos, adicione um quarto breakpoint intermediário se seu design muda significativamente entre tablet e desktop. O importante não é testar cada largura de tela possível, mas cobrir os breakpoints onde seu layout muda estruturalmente. Os layouts aninhados do App Router podem se comportar diferentemente em cada breakpoint, tornando a cobertura responsiva ainda mais crítica do que com uma SPA clássica.
O teste visual desacelera meu pipeline CI/CD de Next.js?
Com Delta-QA, a captura e a comparação são executadas em paralelo com o resto do seu pipeline. Para uma aplicação de 50 páginas com três viewports, conte entre dois e cinco minutos para todo o processo de captura e comparação. É insignificante comparado ao tempo de build de uma aplicação Next.js (frequentemente de cinco a dez minutos para projetos de tamanho médio) e ao tempo economizado ao evitar os vai e vem de correção pós-implantação. Se você implanta no Vercel, a captura começa assim que o ambiente de preview está pronto, sem etapa adicional no seu pipeline.
Posso usar o teste visual com a funcionalidade de draft mode do Next.js?
Sim, e é até recomendado. O draft mode do Next.js permite pré-visualizar conteúdo não publicado de um CMS headless. O teste visual pode capturar as páginas em draft mode para verificar que o conteúdo não publicado não quebra o layout antes da publicação. É particularmente útil para sites editoriais e e-commerce onde o conteúdo é criado por equipes não técnicas que não têm visibilidade sobre o impacto de suas modificações na renderização.
O Delta-QA funciona com os Middleware do Next.js (redirecionamentos, rewrites, A/B testing)?
Sim. Os Middleware do Next.js são executados ao nível do servidor Edge, antes da renderização da página. Delta-QA captura o resultado final após todos os Middleware terem sido executados. Se um Middleware redireciona para outra página ou modifica os headers, o screenshot reflete o resultado dessa lógica. Para A/B testing, você pode configurar Delta-QA para capturar as duas variantes passando os cookies ou headers apropriados, permitindo validar visualmente cada variante da sua experimentação.
Conclusão: Next.js exige um teste visual adaptado à sua complexidade
Next.js é um framework poderoso que revolucionou o desenvolvimento React. Mas esse poder tem um custo em complexidade de renderização que a maioria das equipes subestima. SSR, ISR, App Router, Server Components, streaming, layouts aninhados — cada funcionalidade adiciona um caminho de renderização que pode produzir um resultado visual inesperado.
O teste visual não é um luxo para aplicações Next.js. É uma necessidade. E a ferramenta que você escolher para este teste visual deve ser capaz de capturar o resultado real da sua aplicação — não componentes isolados em um ambiente artificial.
Delta-QA foi projetado exatamente para isso: capturar suas páginas reais, em um navegador real, após a renderização completa, e alertá-lo quando algo muda visualmente. Sem código, sem manutenção de scripts, sem stories de Storybook para sincronizar.
Se você desenvolve com Next.js e ainda não tem uma estratégia de teste visual, está voando às cegas. É hora de corrigir isso.