Visual verify
Versão: 1.1.0. Versões anteriores a 1.0.0 não são rastreadas neste repositório.
Observe o aplicativo real em execução em um navegador headless e relate honestamente o que você vê. Dois modos:
- Verificar (padrão) — captura uma (ou algumas) screenshots do estado atual e leia-as você mesmo para confirmar que uma funcionalidade renderiza, que uma correção funcionou ou que o layout está correto em uma determinada largura.
- Antes/Depois — para uma mudança visual, alterne a mudança entre desligado e ligado e produza uma única imagem composta lado a lado rotulada ANTES/DEPOIS.
- Toque (iOS / Android) — emule um telefone, toque e arraste com um dedo e audite o tamanho dos alvos de toque. Veja Verificações de toque móvel abaixo.
Escolha o modo com base no que o usuário pediu. "Isso parece certo / está funcionando / mostre-me na largura do celular" → verificar. "Antes e depois / isso corrigiu visualmente" → antes/depois.
Quando o usuário pedir, faça
Quando o usuário pedir para você verificar visualmente algo (ou fazer uma captura de tela / verificar a aparência), esse pedido é sua autorização — execute a verificação completa você mesmo: capture, leia a(s) imagem(ns) e diga claramente se está correto. Não apenas ofereça e pare.
Não execute isso sem ser solicitado por iniciativa própria após cada mudança — isso aciona um navegador e lê imagens, o que consome tokens. Após uma mudança visual não solicitada, você pode oferecer ("quer um composto antes/depois — celular, desktop ou ambos?") e deixar o usuário decidir.
Mostre o que você verificou — toda vez
O usuário deve poder ver o resultado sem abrir arquivos. Na resposta que relata o trabalho, mostre a imagem depois para cada funcionalidade que você verificou — uma imagem por funcionalidade, então três coisas verificadas significam pelo menos três imagens. Coloque cada imagem ao lado de uma legenda de uma linha dizendo o que ela mostra e se está correta (ex.: "Confirmação de exclusão, largura de celular — foco em Cancelar").
- Mostre imagens inline com Markdown e um caminho absoluto,
, onde o cliente as renderiza. Caso contrário, anexe-as (ex.: SendUserFile). Sempre forneça também o caminho. - Escolha a imagem mais clara: corte ou apare a funcionalidade onde a página completa a esconderia.
- Para um antes/depois, mostre o composto.
- Se algo não puder ser mostrado honestamente (UI do sistema, área segura), diga isso em vez de mostrar uma imagem enganosa.
Sempre olhe o que você capturou
A captura de tela não é o resultado final — seu julgamento verificado que é. Leia cada imagem que você capturar antes de relatar, e antes de enviar um composto, para confirmar que ela realmente mostra o que você alega. Se não mostrar o que você esperava, investigue; não relate sucesso com uma captura não lida.
Escolha o viewport correto — isso é importante
Um bug de responsividade muitas vezes só se reproduz em uma largura específica. Corresponda ao dispositivo do usuário. Se ele enviou uma captura de tela, derive a largura CSS:
css_width = largura_pixel_da_captura / devicePixelRatio
iPhones modernos têm DPR 3 (ex.: uma captura de tela de 1320px de largura ⇒ 440 px CSS; classe Pro Max).
Android comum tem DPR ~2,6–3. Quando estiver em dúvida, varra algumas larguras (ex.: 320, 360, 390, 440) —
o script de captura torna isso barato. Passe --mobile para emulação de toque/móvel. Para uma mudança de design
geral que se aplica a todas as larguras, verifique tanto desktop quanto mobile.
Os scripts (execute com Bash; não há MCP)
Não procure por uma ferramenta browser_* / Playwright MCP — ela não está instalada. Tudo é executado através
de scripts Node.js simples. Resolva o diretório absoluto que contém este SKILL.md instalado,
então defina VISUAL_VERIFY_DIR para esse diretório no seu shell. Pode ser uma instalação de projeto
ou uma instalação global; use a cópia cujas instruções você está lendo, não um caminho global fixo.
Mantenha o diretório de trabalho na raiz do projeto do aplicativo. Reutilize esta variável em cada
comando de shell (ou defina-a novamente se o estado do shell não for preservado):
VISUAL_VERIFY_DIR="/caminho/absoluto/para/o/instalado/visual-verify"
Os scripts incluídos são:
"$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" # captura uma URL → png
"$VISUAL_VERIFY_DIR/scripts/composite.mjs" # dois pngs → antes/depois rotulado
"$VISUAL_VERIFY_DIR/scripts/touch.mjs" # toque no celular: tocar, arrastar, auditoria de alvo
Configuração de tempo de execução e navegador. Este skill possui uma dependência Playwright exata e um arquivo de bloqueio. Ele nunca resolve um pacote Playwright global ou de projeto. Execute o instalador explicitamente após instalar ou atualizar o skill; verificações normais nunca baixam pacotes, imagens ou navegadores. Use Node.js 20+, npm e Bash. Não instale pacotes de sistema do host para este skill.
Onde o navegador é executado. Com o Docker disponível, cada inicialização inicia seu próprio contêiner a partir da imagem Playwright exata correspondente, já instalada. O Docker aloca uma porta de loopback única; o auxiliar verifica sua identidade de contêiner e se conecta a esse endpoint. As dependências Node instaladas do skill são montadas como somente leitura, para que o servidor não precise baixar pacotes. O Playwright encaminha solicitações de loopback para o cliente, permitindo URLs de aplicativos locais sem rede do host. O fechamento normal, falha na inicialização e encerramento tratado limpam apenas o contêiner dessa execução. Uma finalização forçada ou falha do host pode deixar um contêiner rotulado; inspecione a propriedade antes de uma limpeza explícita. Nenhum contêiner pré-existente é substituído ou interrompido. A rede do Docker Desktop/macOS ainda requer validação separada; não afirme isso a partir de uma verificação Linux.
Sem o Docker, o auxiliar usa binários de navegador local instalados. Defina VISUAL_VERIFY_DOCKER=0
para forçar o modo local; a API de inicialização também aceita um backend explícito. A saída JSON nomeia o
backend e a versão reais.
Inicializador compatível para scripts de projeto
// Resolva esta importação relativa ao diretório do skill instalado.
const { launchBrowser } = await import("<skill-instalado>/scripts/load-playwright.mjs");
const { browser, where } = await launchBrowser("chromium", {
backend: "auto", // auto, docker, local
timeout: 30000,
launchOptions: { headless: true },
});
try {
// Use browser.newContext() , etc. Relate `where` com a evidência.
} finally {
await browser.close();
}
launchOptions vão para o launch local ou para a solicitação de inicialização do navegador do servidor Docker fixo. O servidor Playwright completo ativa o encaminhamento de loopback do cliente solicitado; o Docker é o proprietário do servidor
host e porta; caminhos executáveis específicos do host e outras opções específicas da máquina são de
responsabilidade do chamador. As exportações existentes loadChromium() e loadBrowser(name) permanecem
como APIs de compatibilidade apenas local: elas não iniciam o Docker nem reparam navegadores ausentes.
Migre os chamadores deliberadamente, em vez de assumir que a configuração altera seu comportamento.
As inicializações do Docker usam um contêiner de servidor novo, com nome único, para cada chamada. O Docker aloca atomicamente uma porta de loopback; o cliente valida os metadados do contêiner e se conecta ao seu caminho WebSocket relatado. O Playwright encaminha o tráfego de loopback do cliente, preservando o acesso a aplicativos dev locais sem rede do host. Os contêineres são removidos no fechamento, falha na inicialização e encerramento tratado. Isso troca a reutilização do servidor quente pelo isolamento de endpoint; contêineres de porta compartilhada mais antigos são deixados em paz. Uma finalização forçada ou falha do Docker pode deixar um órfão. Inspecione a saída do doctor e verifique a propriedade do contêiner exato antes de removê-lo explicitamente; nunca pare todos os processos/contêineres correspondentes. O comportamento do Docker entre plataformas ainda requer validação independente.
screenshot.mjs flags: --url --out [--width 390] [--height 844] [--dpr 2] [--mobile] [--wait 2000] [--click "Texto ou seletor"] [--scroll-bottom "sel"] [--eval "js"] [--clip x,y,w,h] [--full]. --click é repetível e corresponde primeiro ao nome acessível de um botão,
depois a um seletor CSS — use-o para alcançar um estado por trás de uma aba/menu/diálogo.
Instalação única (por máquina)
bash "$VISUAL_VERIFY_DIR/scripts/install.sh"
Instala a dependência bloqueada no próprio node_modules deste skill. A configuração padrão auto
puxa a imagem Docker correspondente se o Docker estiver disponível; caso contrário, instala o Chromium local.
Passe docker ou local para o instalador para selecionar explicitamente. O WebKit local não é instalado
por este comando. Nenhum pacote npm global ou pacote de sistema é alterado.
Inspecione os pré-requisitos sem iniciar navegadores, puxar imagens ou alterar contêineres:
node "$VISUAL_VERIFY_DIR/scripts/doctor.mjs"
O Doctor relata a versão do skill/tempo de execução, caminho do tempo de execução, presença do executável local, disponibilidade da imagem Docker e contêineres/endpoints ativos do Visual Verify (incluindo nomes legados). Seu status de saída verifica os pré-requisitos do Chromium para o backend padrão selecionado; ele não prova a inicialização do navegador ou a disponibilidade do WebKit. Instalar arquivos e iniciar um navegador com sucesso são evidências separadas.
Verifique com:
node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
--url https://example.com --out /tmp/_vv_check.png --width 390 --height 844
Inspecione a imagem e o JSON do backend para confirmar que esta verificação de fumaça funcionou.
Aguarde o estado que está sendo verificado
Os comandos de captura de tela e toque suportam estas opções pós-ação:
--ready-selector "<seletor>": aguarda até que o primeiro elemento correspondente esteja visível.--ready-js "<expressão>": pesquisa até que uma expressão da página (incluindo uma promise) seja verdadeira.--ready-timeout 10000: tempo limite de prontidão positivo em milissegundos; compartilhado pelas esperas de seletor e predicado. Também limita a avaliação de--evale--reportseparadamente.--settle 0: atraso não negativo opcional após a prontidão para animação.
Essas condições são executadas após todos os cliques/toques, rolagem, avaliação e arrasto, antes da auditoria
e captura. Ambas as condições, quando fornecidas, devem ser atendidas. Uma falha sai com código diferente de zero e não
grava uma nova captura de tela de sucesso (um arquivo de saída existente não é removido). Escolha caminhos de saída
únicos. --wait mantém seu atraso de pré-ação legado; atrasos fixos de clique/arrasto permanecem como
estabilizações de compatibilidade, não como evidência de prontidão. Indique o que a condição selecionada prova.
node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
--url "<url-do-app-local>" --out visual-checks/search-desktop.png \
--click "Search" --ready-selector "[data-search-results]" \
--ready-js "document.querySelectorAll('[data-result]').length > 0"
Use uma condição específica para o novo estado esperado, não um elemento obsoleto já na página. Para etapas intermediárias que exigem resultados assíncronos, use a API de inicialização e os localizadores Playwright com asserções entre as ações. Se estiver aguardando uma resposta, registre a espera antes de acionar sua solicitação e então afirme o estado renderizado; uma resposta sozinha não prova a renderização. Não trate atrasos arbitrários ou network-idle como garantias de conclusão para aplicativos com debounce.
Local de saída
Grave as imagens geradas em uma pasta visual-checks/ ignorada pelo gitignore na raiz do repositório (mkdir -p visual-checks). Se você não estiver em um repositório, ou não quiser adicionar arquivos a ele, use um diretório temporário.
Referencie os caminhos estáveis ao enviar arquivos para o usuário.
Dê a cada imagem de uma execução um prefixo <mudança> compartilhado descrevendo o que é mostrado (ex.:
import-export-tab, header-nav) — não genérico before.png/after.png — para que uma olhada no
diretório diga a qual execução um arquivo pertence:
visual-checks/<mudança>-<viewport>.png # modo verificar: uma única captura
visual-checks/<mudança>-<viewport>-before.png # modo antes/depois
visual-checks/<mudança>-<viewport>-after.png
visual-checks/<mudança>-<viewport>-before-after.png # o composto
onde <viewport> é mobile ou desktop.
Fluxo de trabalho — modo verificar
- Certifique-se de que o aplicativo está em execução e você tem sua URL (inicie-o da maneira que este projeto executa — veja
Executando o aplicativo abaixo).
mkdir -p visual-checks. - Capture o estado a ser verificado, alcançando-o com
--click/--eval/--scroll-bottomse necessário:Varra algumas larguras, ou removanode "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \ --url "<url do app em execução>" --out visual-checks/<mudança>-mobile.png \ --width 440 --height 800 --mobile --wait 2000--mobilee use ex.:--width 1280 --height 800para desktop, conforme necessário. - Leia cada imagem e relate claramente se está correta. Se estiver verificando uma correção, confirme se a coisa quebrada realmente sumiu; se for uma funcionalidade, confirme se ela realmente renderiza.
- Mostre a(s) captura(s) relevante(s) em sua resposta — uma por funcionalidade (veja Mostre o que você verificou).
Fluxo de trabalho — modo antes/depois
- Confirme o escopo e o(s) viewport(s).
mkdir -p visual-checks. Escolha o prefixo<mudança>compartilhado. - Capture DEPOIS — a árvore de trabalho já tem a mudança:
Para desktop, removanode "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \ --url "<url do app em execução>" --out visual-checks/<mudança>-mobile-after.png \ --width 440 --height 800 --mobile --wait 2000--mobile, use ex.:--width 1280 --height 800, e o sufixo-desktop-after.png. - Capture ANTES — desfaça temporariamente apenas a mudança visual, captura para
<mudança>-<viewport>-before.png, depois restaure. Prefira git para que você não possa esquecer de restaurar:- Mudança não confirmada:
git stash push -- <arquivo>→ captura →git stash pop - Mudança confirmada:
git show HEAD~1:<caminho> > <caminho>(ougit checkout <pai> -- <arquivo>) → captura →git checkout -- <arquivo>Aguarde o servidor de desenvolvimento recarregar a quente entre a alternância e a captura (--wait).
- Mudança não confirmada:
- Composição — mesmo prefixo, sufixo
-before-after.png:node "$VISUAL_VERIFY_DIR/scripts/composite.mjs" \ --before visual-checks/<mudança>-mobile-before.png --after visual-checks/<mudança>-mobile-after.png \ --out visual-checks/<mudança>-mobile-before-after.png \ --title "Header em 440px (largura do iPhone)" \ --before-label "ANTES — título espremido" \ --after-label "DEPOIS — título em largura total" - Leia o composto, confirme se ele mostra o que você alega, então mostre-o em sua resposta.
- Restaure a alternância ANTES. Nunca confirme ou implante com a mudança ANTES temporária ainda
aplicada — verifique novamente
git status/git diffantes de terminar.
Verificações de toque móvel
…
[truncado para tradução]
