visual-verify

Use um navegador headless real (Playwright: Chromium ou WebKit para iPhone; executa na imagem Docker do Playwright quando o Docker está instalado) para capturar a tela de um aplicativo web em execução em um viewport de dispositivo escolhido, examinar o resultado e confirmar se algo realmente renderiza/funciona — ou produzir uma imagem composta lado a lado ANTES/DEPOIS para uma mudança visual.

O que é visual-verify?

Este skill capacita agentes de IA a realizarem verificações visuais automatizadas de aplicações web em tempo real, utilizando Playwright para controlar navegadores headless. Ele suporta dois modos principais: o modo 'Verificar', que captura screenshots do estado atual da aplicação para que o agente as analise e confirme a correta renderização de funcionalidades, e o modo 'Antes/Depois', que alterna uma mudança visual para gerar uma imagem composta lado a lado. Além disso, oferece um modo 'Toque' para emular dispositivos móveis (iOS/Android), testando interações como toques, arrastos e o tamanho dos alvos de toque. O sistema é útil para desenvolvedores que precisam validar responsividade, corrigir problemas de layout e verificar mudanças visuais, fornecendo evidências visuais diretas e reduzindo o risco de regressões. Ele funciona em qualquer projeto web, seja local ou remoto, e opera através de scripts Node.js no diretório `scripts/`, sem depender de MCP. O agente tira screenshots, analisa-os e fornece um julgamento verificado, garantindo que a aplicação se comporte conforme o esperado em diferentes viewports.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/conorjwryan/skills/tree/main/visual-verify

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

legenda

Documentação

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, ![legenda](/caminho/abs/para/imagem.png), 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 --eval e --report separadamente.
  • --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

  1. 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.
  2. Capture o estado a ser verificado, alcançando-o com --click / --eval / --scroll-bottom se necessário:
    node "$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
    
    Varra algumas larguras, ou remova --mobile e use ex.: --width 1280 --height 800 para desktop, conforme necessário.
  3. 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.
  4. 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

  1. Confirme o escopo e o(s) viewport(s). mkdir -p visual-checks. Escolha o prefixo <mudança> compartilhado.
  2. Capture DEPOIS — a árvore de trabalho já tem a mudança:
    node "$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
    
    Para desktop, remova --mobile, use ex.: --width 1280 --height 800, e o sufixo -desktop-after.png.
  3. 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> (ou git checkout <pai> -- <arquivo>) → captura → git checkout -- <arquivo> Aguarde o servidor de desenvolvimento recarregar a quente entre a alternância e a captura (--wait).
  4. 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"
    
  5. Leia o composto, confirme se ele mostra o que você alega, então mostre-o em sua resposta.
  6. Restaure a alternância ANTES. Nunca confirme ou implante com a mudança ANTES temporária ainda aplicada — verifique novamente git status / git diff antes de terminar.

Verificações de toque móvel

…

[truncado para tradução]

Habilidades Relacionadas