Teste Baseado em Evidências

Registre prova anotada de comportamento e anexe-a ao PR e à issue do tracker.

A gravação é a captura de você testando o aplicativo via uso do computador: inicie o gravador, então dirija o aplicativo você mesmo — clique, digite, navegue — por cada alvo de teste. Cada ação no vídeo é o teste sendo executado ao vivo; a gravação não tem valor como evidência a menos que mostre essa sessão interativa. Se o ambiente não tiver ferramentas de uso do computador, mas existir uma GUI, dirija o aplicativo com cua-driver (veja abaixo) — ainda é sua sessão ao vivo.

O gravador incluído, scripts/evidence.py, captura a tela com FFmpeg no Linux, macOS e Windows, carimba cada anotação que você adiciona durante o teste, grava-as no vídeo ao parar e verifica o resultado com ffprobe. Ele escreve evidence.mp4, report.md e manifest.json na pasta da sessão.

Entradas

Alvos de teste (obrigatório): Os comportamentos/fluxos a verificar, expressos como declarações testáveis.
PR / issue (opcional): Onde publicar a evidência. Se omitido, entregue apenas ao solicitante.

O gravador

EVIDENCE abaixo significa o caminho para scripts/evidence.py dentro da pasta desta skill (onde quer que a skill esteja instalada, por exemplo ~/.claude/skills/evidence-driven-testing/scripts/evidence.py). Precisa apenas de Python 3 e FFmpeg.

Verifique primeiro: python3 $EVIDENCE doctor — verifica ffmpeg, ffprobe, libx264 e o filtro ass (ready), então qual fonte de captura de tela funciona nesta máquina (capture_ready e a fonte auto escolherá). Sai com código diferente de zero apenas quando a cadeia de ferramentas está ausente; leia capture_ready antes de gravar.

Plataformas (--source auto escolhe a primeira disponível):

SO	Fonte	Necessita
Linux X11 / XWayland	`x11` (x11grab)	`DISPLAY` definido
Linux Wayland	`wayland` (wf-recorder)	`WAYLAND_DISPLAY` definido, `wf-recorder` no PATH, e um compositor confirmado para suportar wlr-screencopy — ou um wlroots conhecido (Sway, Hyprland, river, Wayfire, labwc, dwl, niri) ou verificado via `wayland-info`. GNOME e KDE Wayland não são capturáveis desta forma; `doctor` informa. Use `x11` através do XWayland para aplicativos X11, ou um gravador alternativo. `--source wayland` ainda força isso
macOS	`avfoundation`	Permissão de Gravação de Tela concedida ao terminal / aplicativo host do agente; `doctor` lista os índices de tela para `--screen-index`
Windows	`gdigrab`	qualquer build ffmpeg padrão; `powershell` para verificações de processo

A captura é da tela inteira por padrão; --geometry WxH e --offset X,Y recortam uma região no x11, wayland e gdigrab. XWayland vê apenas janelas X11, então prefira a fonte wayland quando o aplicativo em teste for nativo do Wayland.

Captura bruta à prova de falhas: a gravação bruta é MPEG-TS (raw.ts), então, se o gravador for morto à força ou travar, o que foi capturado ainda pode ser verificado e renderizado. stop remuxa ou recodifica em um evidence.mp4 padrão.
Como a parada funciona: no Linux, o gravador é sinalizado através de um pidfd. No macOS e Windows, start inicia um pequeno processo supervisor que possui o filho ffmpeg, e stop pede a ele (via stop.request na pasta da sessão) para interromper, então terminar, então matar; ele escreve recorder-exit.json quando termina. Nunca um PID simples é sinalizado, então um PID reciclado não pode ser atingido. Se o supervisor morrer enquanto o gravador ainda está rodando, stop recusa e informa qual PID parar manualmente. Se ele morreu antes mesmo de gravar qual processo iniciou, stop fica bloqueado até que você tenha verificado se há um gravador perdido e executado novamente com --accept-untracked-recorder; o relatório então carrega essa ressalva.
Gravadores alternativos quando doctor não relata fonte de captura (por exemplo Wayland sem wf-recorder): cua-driver recording start <dir> / stop (veja a seção cua-driver), ou o gravador do SO (macOS: screencapture -v out.mov). Nestes caminhos não há sobreposição de anotações, então mantenha o protocolo de anotação como arquivos — um assertions.md listando cada setup / test_start / assertion com seu resultado e o carimbo de data/hora aproximado do vídeo, exatamente como no caminho sem headless.
Nunca apresente --source test (o gerador de padrões sintéticos) como evidência de UI. Ele existe para testar a cadeia de ferramentas; o tests/test_evidence.py do repositório o utiliza.

Instruções

1. Prepare a tela

Maximize a janela do navegador/aplicativo; feche popups, notificações e painéis extras.
Navegue até o estado inicial (logado, página correta) ANTES de gravar, a menos que o setup em si esteja em teste.
Anote a revisão exata em teste: git rev-parse HEAD e git branch --show-current (ou a URL de implantação) — o gravador os carimba no relatório.

2. Inicie a gravação

Comece a gravação de tela antes da primeira ação significativa:
```
python3 $EVIDENCE start \
  --output .artifacts/<nome-da-tarefa> \
  --title "<o que está sendo verificado>" \
  --commit "$(git rev-parse HEAD)" --branch "$(git branch --show-current)" \
  --environment "<SO / navegador / tela / implantação>"
```
Ele imprime JSON com um caminho session e a source escolhida; mantenha o caminho (SESSION=...) para cada comando posterior. A fonte é detectada automaticamente e a tela inteira é capturada; passe --source, --geometry, --offset, --display/--xauthority (X11), --screen-index (macOS) ou --output-name (Wayland) apenas quando doctor ou a situação exigir.

Adicione uma anotação setup descrevendo o contexto inicial:

python3 $EVIDENCE annotate "$SESSION" --type setup \
  --message "Logado, navegando para a página de conectores"

3. Teste via uso do computador, anotando enquanto avança

Realize cada interação através do uso do computador no aplicativo ao vivo — a gravação captura sua sessão, então o teste e a evidência são o mesmo ato. Trabalhe em um ritmo assistível: deixe a UI estabilizar após cada ação para que as mudanças de estado fiquem visíveis no vídeo.

No início de cada teste nomeado, adicione uma anotação test_start no estilo Jest:

python3 $EVIDENCE annotate "$SESSION" --type test_start \
  --message "Deve executar a ferramenta diretamente quando a permissão é 'always'"

Após cada verificação, adicione uma anotação assertion com --result passed, failed ou untested:

python3 $EVIDENCE annotate "$SESSION" --type assertion --result passed \
  --message "Ferramenta executada sem prompt de permissão"

Regras para assertivas:
- Uma assertiva por mudança de estado significativa — consolide, não anote por rótulo de UI.
- Use assertivas "Precondition: ..." para estabelecer o estado inicial.
- Mantenha abaixo de 80 caracteres, alto sinal (o gravador rejeita mensagens mais longas).
- Se um teste não puder ser executado (pré-requisito ausente, janela de autenticação expirada), marque como untested com o motivo — nunca pule silenciosamente.
- O carimbo de data/hora registra quando você afirmou, não se era verdade — olhe para a tela antes de escolher passed.

4. Pare e revise

Pare a gravação após a assertiva final:
```
python3 $EVIDENCE stop "$SESSION"
```
Isso para a captura (graciosamente, para que o gravador descarregue; escalando apenas se ignorar a solicitação), grava as anotações em evidence.mp4, verifica o resultado e escreve report.md e manifest.json ao lado. Imprime "verified": true em caso de sucesso; se a renderização falhar, a sessão é marcada como finalization_failed — corrija a causa relatada e execute stop novamente (uma repetição não sinaliza o gravador duas vezes). Se o processo do gravador não puder mais ser sinalizado com segurança (morreu, ou seu PID agora pertence a outro processo), a sessão é marcada como recorder_lost. Executar stop novamente finaliza o vídeo que foi capturado, mas apenas depois que esse processo do gravador for confirmado como encerrado — se ainda estiver ativo, pare-o primeiro, ou o vídeo seria renderizado enquanto ainda está sendo escrito.
Confirme que a gravação capturou os momentos-chave antes de compartilhar: extraia um quadro em cada carimbo de data/hora de assertiva (ffmpeg -ss <t> -i evidence.mp4 -frames:v 1 frame.png) e verifique se o estado e o rótulo estão visíveis.
Preencha a seção de Riscos e Limitações do report.md; nunca deixe o espaço reservado.

5. Publique a evidência

report.md é o relatório: o que foi testado, ambiente + commit exato, passa/falha por teste, riscos e limitações. Estenda-o em vez de reescrever do zero.
Publique o vídeo + resumo como um comentário no PR (incorpore na descrição do PR se for seu PR). gh pr comment não pode anexar um vídeo local — faça upload de evidence.mp4 através da caixa de comentários do PR em um navegador autenticado, ou faça upload para um host e forneça o link (por exemplo, os adaptadores de upload before-and-after). Reabra o comentário e confirme que o vídeo é reproduzido antes de afirmar que foi publicado.
Anexe o mesmo vídeo à issue do tracker (Linear/Jira) com um resultado de uma linha.
Envie o relatório + gravação ao solicitante.

Diretrizes de Segurança

O vídeo deve mostrar a sessão de teste real sendo conduzida ao vivo. Nunca apresente reprodução programada, clipes montados ou filmagens sintéticas como uma gravação; se o ambiente não tiver ferramentas de uso do computador, mas existir uma GUI, dirija via cua-driver; sem GUI alguma, use o caminho sem headless.
Nunca grave uma janela meio coberta ou lado a lado — maximize primeiro.
Nunca grave uma tela mostrando segredos, tokens, dados de clientes ou detalhes de pagamento; se um fluxo exigir, marque como untested e explique o motivo.
Ao verificar uma correção, mostre ou faça referência à falha antiga junto com o novo sucesso.
Sempre declare o commit/branch/implantação exato testado.

Sem ferramentas de uso do computador? Dirija com cua-driver (GUI disponível)

Quando uma tela existe, mas o agente não tem capacidade de uso do computador integrada, use cua-driver (macOS / Windows / Linux) como atuador. Ainda é você testando o aplicativo ao vivo — a regra de gravação permanece inalterada; apenas o mecanismo de entrada difere.

Verifique a configuração com cua-driver doctor antes de gravar. Se uma skill cua-driver estiver instalada, leia-a e siga seu protocolo — o invariante de captura de tela antes da ação é obrigatório.
Loop por interação: launch_app → get_window_state (árvore de acessibilidade + captura de tela) → aja via element_token (click, type_text, press_key) → verify_state para a pós-condição esperada. Cada verificação verify_state mapeia 1:1 para uma anotação assertion.
Onde doctor relatar capture_ready: yes, continue usando o gravador incluído acima para o vídeo e as anotações; o cua-driver fornece apenas a entrada.
Caso contrário, cua-driver recording start <output-dir> / cua-driver recording stop é o gravador (o diretório de saída é obrigatório e o daemon deve estar em execução: cua-driver serve). A captura de vídeo está ativada por padrão e é finalizada em <output-dir>/recording.mp4 na parada — mas no Windows/Linux ele chama o ffmpeg, então um ffmpeg ausente ou tela ausente resulta apenas nas pastas de trajetória por turno (capturas de tela antes/depois, action.json, click.png), sem vídeo. Após parar, verifique se recording.mp4 existe antes de citá-lo; se estiver ausente, corrija o gravador ou apresente as capturas de tela antes/depois por turno como capturas numeradas de acordo com o protocolo sem headless.
Se nenhuma sobreposição de anotações estiver disponível neste caminho, mantenha o protocolo como arquivos: um assertions.md listando cada test_start / assertion com seu resultado, exatamente como no caminho sem headless.

Caminho sem headless (nenhuma GUI disponível)

Quando o agente não tem uma área de trabalho para gravar, mantenha a mesma disciplina de assertiva; troque o gravador por captura programada:

Salve tudo em .artifacts/<nome-da-tarefa>/ (adicione ao .gitignore — a evidência é enviada, nunca commitada). Mantenha o script de captura junto com as capturas para que a execução seja reproduzível.
Capturas de tela: o CLI before-and-after (@vercel/before-and-after) captura URLs ou elementos e seus pares alimentam diretamente os embeds do PR. Em contêineres/VMs onde o Chrome falha com "No usable sandbox", defina AGENT_BROWSER_ARGS="--no-sandbox".

Vídeo / fluxos de várias etapas: um script Playbridge avulso, executado sem adicionar playwright às dependências do projeto:

npx --yes --package=playwright node record.mjs

(Simples npx playwright node record.mjs falha — node não é um comando CLI do Playwright; --package=playwright é o que coloca o módulo no caminho.) record.mjs mínimo:

import { chromium } from "playwright";
const browser = await chromium.launch();
const context = await browser.newContext({
  recordVideo: { dir: ".artifacts/<nome-da-tarefa>/" },
});
const page = await context.newPage();
await page.goto("http://localhost:3000/caminho-em-teste");
// ...dirija o fluxo, uma mudança de estado significativa por etapa...
await context.close(); // finaliza o .webm
await browser.close();

Corte ou comprima com ffmpeg se o arquivo for grande.

O protocolo de anotação se torna arquivos: numere as capturas na ordem do teste com a assertiva no nome — 01-precondition-signed-in.png, 02-it-saves-on-blur-passed.png — e mantenha um assertions.md na pasta de artefatos listando cada test_start / assertion com seu resultado (passed / failed / untested + motivo).

Alterações não relacionadas à UI ainda precisam de evidência

API / desempenho: uma sonda programada com números medidos — contagens de requisições por fase, latência antes/depois — capturada em probe-output.txt.
Renderização / canvas / shader: quadros renderizados mais assertivas de pixel (valores de diff), revisados visualmente e salvos como PNGs.
Comportamento do agente: o trecho de transcrição relevante mostrando a chamada da ferramenta e a resposta.
Correções de bugs: reproduza e capture a falha antes de escrever a correção — essa captura é a metade "antes" de um par antes/depois.

Higiene de captura

Confirme que o servidor que você está sondando está executando seu código (porta certa, processo certo), especialmente quando vários agentes compartilham uma máquina: lsof -i :<porta> — ou onde lsof não está instalado, ss -ltnp "sport = :<porta>" — nunca confie apenas na barra de título do navegador.
Verifique novamente as permissões de tela no macOS se a gravação começar, mas produzir um arquivo vazio: tccutil reset ScreenCapture do terminal e conceda novamente.
Quando gravar sessões longas (+5 minutos), aumente o buffer do FFmpeg: adicione --ffmpeg-args "-thread_queue_size 512" ao comando start.
Se o report.md final não for gerado (renderização nunca finalizada), verifique se o arquivo evidence.mp4 existe; se sim, ele pode ser extraído sem o relatório. O manifesto JSON ainda contém os metadados da sessão.
Para capturas do Wayland que produzem apenas um cursor estático, confirme que o aplicativo em teste não está rodando via XWayland. Execute xlsclients para listar janelas X11 no Wayland; se o aplicativo aparecer, use --source x11 ou mude para uma fonte nativa Wayland.
Nunca publique um arquivo de vídeo corrompido: ffprobe evidence.mp4 2>&1 | grep -qi error e trate o erro antes de fazer upload.

Anatomia dos arquivos de saída

evidence.mp4 contém o vídeo codificado em h264 com as anotações sobrepostas via legendas ASS. report.md é um relatório estruturado que inclui a lista de testes e resultados. manifest.json contém os metadados da sessão, incluindo origem, commit, branch e timestamps de anotações.

Os comandos doctor e start / stop escrevem em stderr para que o stdout permaneça limpo para redirecionamento de saída JSON. A sessão é uma pasta; seu caminho é a raiz para todos os comandos subsequentes.

Saída de exemplo do doctor

{
  "ready": true,
  "capture_ready": true,
  "source": "x11",
  "ffmpeg": "/usr/bin/ffmpeg",
  "ffprobe": "/usr/bin/ffprobe",
  "python": "/usr/bin/python3"
}

Se ready for false, não é possível gravar. Se capture_ready for false mas ready for true, o gravador está instalado, mas nenhuma fonte de captura está disponível; use o caminho cua-driver ou sem headless.

Solução de problemas

Nenhum vídeo gerado: Execute python3 $EVIDENCE doctor para verificar se todas as ferramentas estão instaladas. Se ffmpeg não for encontrado, instale-o via gerenciador de pacotes.
Fonte incorreta selecionada: Passe --source x11 / wayland / avfoundation / gdigrab explicitamente.
Falha de permissão no macOS: Conceda permissão de Gravação de Tela ao terminal ou aplicativo host do agente em Preferências do Sistema > Privacidade e Segurança.
Tela preta no Wayland: Use --source x11 se o aplicativo rodar via XWayland, ou mude para uma fonte Wayland se wf-recorder estiver disponível e configurado.
Sessão perdida após falha do supervisor: Verifique se a pasta raw.ts existe na sessão e execute stop novamente; se o supervisor foi perdido, use --accept-untracked-recorder após confirmar que o processo ffmpeg ainda não está rodando.
Mensagens de anotação vazias: O gravador rejeita mensagens com mais de 80 caracteres. Revise a saída do comando annotate para obter detalhes do erro.

beraki/my-code-factory-skills

O que é my-code-factory-skills?

Perguntar na sua IA favorita

Documentação