Visual Regression Gates

Diff de screenshot que não dá falso positivo.

Como começar

1. Grave o baseline e amarre ao buildA digital (fingerprint) prende o baseline ao build de onde ele veio — baseline solto é o que faz o gate mentir depois.python scripts/visual_gate.py fingerprint baseline/home.png \ --url https://app.exemplo/home --viewport 1280x720 \ --config baseline/home.masks.json
2. Barre o build novoDiff máximo, número de regiões e o bundle de evidências vão na chamada.python scripts/visual_gate.py compare baseline/home.png actual/home.png \ --meta baseline/home.png.meta.json --masks baseline/home.masks.json \ --max-diff 0.001 --max-regions 1 --bundle artifacts/home
3. Todas as páginas de uma vezVarredura de todas as baselines contra as atuais, o passo que entra no CI.python scripts/visual_gate.py sweep baseline/ actual/ --bundle artifacts/ --json
4. O exit code é o contrato0 PASS, 1 FAIL, 2 STALE, 3 ERROR. Com --json a saída traz o veredito, a porcentagem de diff, quantas regiões mudaram e o bounding box de cada uma.

Quando você vai usar

• Screenshot falha quando nada mudouAnimação, caret ou fonte pegando o frame errado: mascarar a região instável resolve sem afrouxar o threshold do diff inteiro.
• Baseline velho aprovando tela quebradaO fingerprint amarra a baseline ao build que a gerou — baseline órfã falha como stale em vez de passar como verde.
• CI sem PIL nem ImageMagickO gate decodifica PNG na stdlib (zlib + struct): um gate que exige C library em cada runner é um gate que quebra na máquina que importa.
• Revisar o que mudou no PRFailure bundle com o diff e as regiões afetadas, pronto pra anexar na revisão.
• Varrer o app inteiroTodos os viewports numa rodada de CI, com veredito por página em vez de um número só.

O que vem no pacote

• scripts/visual_gate.py — o gate, stdlib pura (zlib + struct), zero dependências
• tests/test_visual_gate.py — 15 testes: os dois sentidos do veredito e o decoder comparado com PIL/ImageMagick
• templates/capture.mjs.txt — captura Playwright com screenshots + rects de máscara — renomeie para capture.mjs
• templates/masks.example.json — formato do arquivo de máscaras
• references/capture-determinism.md — como tornar a captura reproduzível antes de culpar o gate
• references/masks-and-fingerprints.md — estratégia de máscara, formato do fingerprint e do bundle de falha

Precisa de

• Python 3.8+, sem PIL/OpenCV/ImageMagick
• PNGs de qualquer capturador (Playwright ou o seu)
• um mask config por página dinâmica

Onde ela não entra: O gate não lança browser: a captura do template é referência, não dependência. Sem a meta e a máscara junto do PNG, os quatro vereditos não têm como ser honestos.

← todas as skills