Testes de instantâneos de HTML

O teste de instantâneo registra a saída renderizada de um componente ou página na primeira execução e, nas execuções seguintes, compara a nova saída com o instantâneo salvo. Qualquer alteração na saída HTML faz o teste falhar até que o instantâneo seja atualizado intencionalmente.

O comparador toMatchSnapshot() do Jest serializa um valor (incluindo JSX renderizado como HTML) e o compara com um arquivo salvo. npx jest -u atualiza os instantâneos quando ocorrem alterações intencionais. Os testes funcionam como uma rede contra regressões causadas por alterações acidentais na renderização.

O Storybook Test Runner executa cada história e registra sua saída como instantâneo por meio do axe (acessibilidade) e da serialização do DOM. Em conjunto com o Chromatic, ele adiciona regressão visual — diferenças em nível de pixel além das diferenças do DOM.

Percy e Chromatic registram páginas renderizadas como imagens e evidenciam diferenças visuais. Eles detectam regressões de CSS que os instantâneos do DOM não identificam (uma troca de fonte, um ajuste de margem ou uma mudança de cor). Combine instantâneos do DOM (baratos e rápidos) com instantâneos visuais (caros e abrangentes).

Instantâneos que mudam "com facilidade demais" tornam-se ruído. Evite incluir valores instáveis nos instantâneos (datas, IDs e chaves aleatórias). Use os comparadores de propriedades do Jest (expect.any(String)) para campos que variam legitimamente entre as execuções. Mantenha os instantâneos pequenos e focados.

As diferenças nos arquivos de instantâneos dos PRs são material prioritário de revisão. Os revisores verificam se as alterações do DOM são intencionais e desejáveis — detectando efeitos em cascata acidentais causados por uma alteração "simples" de CSS. Trate as diferenças dos instantâneos como qualquer outra diferença.

Capturar renderizações enormes de páginas de nível superior é frágil — cada pequena alteração se propaga para uma diferença gigantesca. Faça capturas no nível do componente: cada botão, cada cartão, cada FormField. A renderização no nível da página merece, em vez disso, testes de regressão visual.

Escolha como serializar: HTML completo, DOM simplificado, somente propriedades ou árvore de acessibilidade. Cada formato detecta regressões diferentes. Para componentes de interface, o HTML completo é o mais abrangente; para lógica orientada por propriedades, usar somente propriedades é mais barato e raramente gera falsos positivos.

A causa mais comum é uma refatoração que produz HTML equivalente, mas com estrutura diferente. Inspecione a diferença: se a alteração for intencional e boa, atualize a captura. Se for inesperada, corrija o código subjacente. Nunca execute jest -u às cegas, sem fazer uma inspeção.

As ferramentas de regressão visual fazem a renderização em vários navegadores e relatam diferenças específicas de cada navegador. Use isso para detectar CSS que é renderizado de forma diferente no Safari e no Chrome — algo comum em novos recursos de layout durante a fase inicial de adoção. Sem capturas entre navegadores, essas regressões só são detectadas pela QA manual.

Os testes de captura são necessários, mas não suficientes. Eles detectam alterações não intencionais na renderização, mas não erros de lógica, como clicar no botão e a ação correta não acontecer. Combine-os com testes de unidade para o comportamento e testes de ponta a ponta para os fluxos do usuário — cada camada detecta falhas diferentes.

Os testes de captura são rápidos — eles comparam strings e arquivos. Os testes de regressão visual são mais lentos, pois renderizam pixels, comparam imagens e geralmente fazem isso em vários navegadores. Execute as capturas em cada compilação de CI; execute a regressão visual em cada PR, mas talvez não em cada confirmação, dependendo do orçamento de CI.

Os testes de captura registram o HTML renderizado na primeira execução e sinalizam qualquer alteração nas execuções seguintes. Use Jest toMatchSnapshot para o DOM dos componentes, Storybook Test Runner para histórias e Percy/Chromatic para regressão visual no nível dos pixels. Faça capturas no nível do componente, não no nível da página, exclua valores instáveis e analise cuidadosamente as diferenças nas PRs. Combine-os com testes de unidade e de ponta a ponta para obter cobertura completa.