AmElmo/proofshot

Verificação visual de funcionalidades de UI. Use após construir ou modificar qualquer componente, página ou recurso visual. Inicia uma sessão de verificação com gravação de vídeo e captura de erros. Em seguida, você controla o navegador para testar e, por fim, para gerar um pacote de artefatos de prova para o ser humano.

O que é proofshot?

ProofShot é uma ferramenta CLI open-source e agnóstica a agentes que permite a verificação visual de componentes de interface do usuário em um navegador real. Ela oferece gravação de vídeo, captura de tela e um relatório de erros, sem dependência de fornecedor. O fluxo de trabalho é composto por três etapas principais: iniciar uma sessão de verificação (que abre o navegador e grava), conduzir os testes no navegador com comandos como `proofshot exec`, e interromper a sessão para gerar um pacote de artefatos de prova. A ferramenta também pode postar automaticamente as provas (capturas de tela e vídeo) em pull requests no GitHub, facilitando a revisão humana. ProofShot é ideal para desenvolvedores e agentes de IA que precisam verificar alterações visuais em aplicações web, garantindo que as modificações não introduzam regressões ou erros visuais.

Funciona com~Claude Code~Codex CLI~Cursor✓OpenCode

npx skills add https://github.com/AmElmo/proofshot/tree/HEAD/skills/opencode

Documentação

ProofShot - Fluxo de Trabalho de Verificação Visual

ProofShot é uma CLI de código aberto e agnóstica a agentes que permite verificar seu próprio trabalho em um navegador real - prova em vídeo, capturas de tela e relatórios de erro, sem dependência de fornecedor.

Quando usar

Use ProofShot após:

Construir um novo recurso ou página de UI
Modificar componentes de UI existentes
Corrigir um bug visual
Qualquer alteração que afete o que o usuário vê

O fluxo de trabalho (siga sempre estas 3 etapas)

Etapa 1: Iniciar a sessão

proofshot start --run "seu-comando-de-desenvolvimento" --port PORTA --description "o que você está prestes a verificar"

Isso abre um navegador e começa a gravar. Se a porta já estiver em uso, o proofshot encerrará o processo existente automaticamente.

Sempre use --run para que o proofshot inicie e capture a saída do seu servidor de desenvolvimento (os logs do servidor aparecem no relatório de prova). Só omita --run se o servidor foi explicitamente iniciado pelo usuário ou por outro processo - sem ele, nenhum log do servidor é capturado.

Se uma sessão anterior não foi interrompida corretamente, adicione --force para sobrescrevê-la.

Etapa 2: Conduzir o navegador e testar

Use proofshot exec para navegar, interagir e verificar:

proofshot exec snapshot -i                                    # Ver elementos interativos
proofshot exec open http://localhost:PORTA/pagina             # Navegar para uma página
proofshot exec click @e3                                      # Clicar em um botão
proofshot exec fill @e2 "[email protected]"                  # Preencher um campo de formulário
proofshot exec screenshot passo-NOME.png                      # Capturar momentos importantes

Tire capturas de tela em momentos importantes - elas se tornam a prova visual. Verifique o que você espera ver lendo a saída do snapshot.

Etapa 3: Parar e gerar o pacote de prova

proofshot stop

Isso interrompe a gravação, coleta erros do console + servidor, e gera um SUMMARY.md com vídeo, capturas de tela e relatório de erros.

Etapa 4 (opcional): Postar prova no PR

proofshot pr              # Detecta o PR automaticamente a partir da branch atual
proofshot pr 42           # Segmentar um número de PR específico

Isso envia capturas de tela e vídeo para o GitHub e publica um comentário formatado no PR. Por padrão, usa a API oficial de conteúdo do GitHub em uma branch proofshot-artifacts. Use --upload-provider github-web-attachments se você quiser especificamente URLs de anexos do GitHub.

Dicas

Sempre inclua uma --description significativa para que o ser humano saiba o que foi testado
Tire capturas de tela ANTES e DEPOIS das ações principais (ex.: antes do envio do formulário, após o redirecionamento)
Se encontrar erros durante a verificação, corrija-os e reexecute o fluxo de trabalho
Use proofshot pr após interromper para anexar a prova diretamente ao pull request