Communitygithub.com

hand-test

Teste manual de uma alteração que as pessoas veem, ouvem ou sentem. ANTES e DEPOIS são reproduzidos lado a lado em um único vídeo e um único quadro, o agente os verifica e a alteração aguarda a aprovação de uma pessoa. Use quando o usuário solicitar um teste manual, um vídeo antes/depois, prova visual para um PR, um relatório de release do que mudou para os usuários, ou disser "mostre-me o que mudou".

O que é hand-test?

O skill hand-test é um agente especializado em criar evidências visuais e auditivas de mudanças em software, permitindo que revisores humanos aprovem alterações com confiança. Ele automatiza a comparação lado a lado de estados ANTES e DEPOIS de uma modificação, gerando um vídeo sincronizado e um quadro comparativo (board). Suporta qualquer plataforma onde scripts de automação possam ser executados (UI, comportamento, som, timing) e é particularmente útil para PRs que envolvem mudanças perceptíveis por usuários finais. O skill segue um fluxo de 7 etapas: classificar a mudança, planejar a captura, gravar ambos os lados, montar as evidências, auto-revisar, entregar para aprovação humana e registrar o veredito. A documentação completa (SKILL.md) detalha comandos para ferramentas como `scripts/handtest.py`, que depende de `ffmpeg` e `ffprobe`, e requisitos como manter o estado do dispositivo e da árvore de trabalho inalterados entre as gravações.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GhostRoboticsLab/skills/tree/HEAD/skills/engineering/hand-test

Perguntar na sua IA favorita

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

Documentação

Teste manual

Testes provam o que o código faz. Um teste manual prova que uma pessoa recebeu o que foi pretendido. Para cada alteração que uma pessoa pode ver, ouvir ou sentir, você produz evidências que um estranho pode julgar em um minuto, a frio: um vídeo e um quadro, ANTES (emblema vermelho) ao lado de DEPOIS (emblema verde), no mesmo lugar e com a mesma ação, de modo que apenas a alteração diferencie. A alteração permanece sem merge até que o aprovador(a) diga OK.

Os fatos do projeto estão em docs/agents/hand-test.md no repositório do usuário: como obter o ANTES, como dirigir e capturar esta superfície, as regras do dispositivo, onde as evidências vão, quem aprova, e o que OK e Não OK fazem. Se esse arquivo estiver faltando, siga SETUP.md primeiro.

A ferramenta é scripts/handtest.py. Execute como uv run <pasta deste skill>/scripts/handtest.py <comando>; --help em qualquer comando lista suas flags. Ela precisa de ffmpeg e ffprobe no PATH; o uv traz o Pillow. Sem uv, crie um ambiente virtual fora do repositório (python3 -m venv <dir> && <dir>/bin/pip install pillow) e execute a ferramenta com <dir>/bin/python.

1. Classifique a alteração

Coloque uma seção ## Teste manual no corpo do PR (ou onde a alteração for descrita):

  • sim: <o que procurar> para qualquer coisa que uma pessoa veja, ouça ou sinta: UI, comportamento, tempo, som, texto, design.
  • não: <por que nada é visto, ouvido ou sentido> para ferramentas, build, testes, documentação, ou uma refatoração com a mesma saída.

Em caso de dúvida, é sim.

Concluído quando: a seção estiver lá. Um não encerra o skill.

2. Planeje a captura

Nomeie o momento: o único passo onde a alteração se mostra. Quando a alteração está na tela desde o primeiro quadro (uma cor, um rótulo, um layout), o momento é a chegada da tela, ou o primeiro passo após ela.

Escreva os passos como um script que dirige o aplicativo real, idêntico para ambos os lados (comandos por superfície em CAPTURE.md):

  • Entrada real através da própria UI do aplicativo: um atalho de teste pula o código que uma pessoa acessa.
  • Encontre elementos pelo rótulo ou função, nunca por coordenadas: o layout se movendo é frequentemente a própria alteração.
  • Aguarde o estado real (um rótulo mostrado, uma requisição concluída) antes do momento, nunca um temporizador fixo. Mantenha um tempo fixo após ele.
  • Mesmo dispositivo, tamanho de janela, idioma, dados e estado inicial em ambos os lados.
  • Restaure tudo em um finally.

O ANTES vem do estado antigo real: o build do commit base, ou a alteração desligada em tempo de execução. Nenhuma alteração de arquivo salva para ele.

Se a alteração for uma questão de espaço, tempo ou sensação que ninguém resolveu antes do build (quão grande, quão rápido, como deveria parecer), pare e informe o usuário. Isso pertence a um esboço interativo antes do build; um teste manual verifica uma decisão, não a toma.

Concluído quando: o script roda a seco (nada gravado) no ANTES e no DEPOIS, encontra todos os elementos (ou atinge todos os estados, onde apenas imagens estáticas podem ser capturadas), e deixa o dispositivo e a árvore de trabalho como estavam, com o checksum da árvore igual antes e depois.

3. Grave ambos os lados

Grave ANTES, depois DEPOIS, com o mesmo script. Siga as regras de dispositivo do projeto: toque apenas no aplicativo sob teste, não desinstale nada, não altere nenhuma configuração do sistema, e envie entrada apenas enquanto o aplicativo sob teste estiver em primeiro plano.

Concluído quando: duas gravações brutas existem, cada uma mostra o momento, e o checksum da árvore de trabalho ainda corresponde.

4. Monte as evidências

  1. init --out "$HANDTEST_ROOT/<grupo>" --id <N> --topico <kebab-case> --titulo "<palavras simples>" --base <sha> --head <sha> --ok "<...>" --nao-ok "<...>". O grupo, OK e Não OK vêm do arquivo do projeto. Seu shell pode não manter HANDTEST_ROOT entre comandos: defina-o no mesmo comando.
  2. find-change <bruto> --de <s> --ate <s> em cada gravação ao redor do momento. O tempo de sincronização é o quadro onde a imagem muda, não o tempo registrado de uma etapa.
  3. pair --antes <bruto> --depois <bruto> --sync-antes <s> --sync-depois <s> --titulo ... --oque ... --legenda ... --saida <pasta>/<id>_<topico>.mp4. Ela preenche os tempos do vídeo em README.md e PACKAGE.md, e imprime onde o momento cai no vídeo.
  4. Uma imagem estática por lado, um instante após o momento, a partir das gravações brutas: stills <bruto> --em <s> --saida <scratch>/antes, o mesmo para DEPOIS. Ela imprime cada arquivo. Depois board --antes <png> --depois <png> --titulo ... --legenda ... --saida <pasta>/<id>_<topico>_ANTES_DEPOIS.png.
  5. Preencha cada marca <preencher: ...>. As regras para as palavras e os números estão em EVIDENCE.md.

Concluído quando: check <pasta> imprime "pronto para uma pessoa".

5. Passagem do revisor

Antes de qualquer pessoa ver, revise você mesmo como um estranho faria. Extraia imagens estáticas do vídeo duas vezes: stills <video> --cada 1 --saida <scratch>, depois stills <video> --em <t-0.5> <t> <t+0.5> --saida <scratch>, onde t é o tempo do momento no vídeo, não em uma gravação bruta (pair imprimiu; handtest.json o armazena como video.change_at). Olhe para cada imagem e para o quadro.

  • Cada uma deve mostrar o que sua legenda diz para olhar. Coberto, vazio, estado errado, idioma errado, uma sobreposição sobre a alteração: archive a pasta e grave novamente a partir da etapa 3. Grave novamente em vez de explicar uma imagem ruim no README.
  • Um número deve concordar com a imagem. Quando eles discordam, o número está errado: descubra por quê.
  • Um teste verde com uma imagem errada é uma constatação. Relate ao usuário como um bug.

Concluído quando: cada imagem e o quadro mostram o que as legendas afirmam, e cada número no README corresponde à imagem.

6. Entregue

Coloque a pasta onde as evidências do projeto vão. Publique PACKAGE.md onde o arquivo do projeto diz, nomeando apenas o caminho relativo da pasta, nunca uma conta ou um caminho absoluto. Complete a linha sim do PR com esse caminho e quem está esperando (o formulário está sob "A seção do PR" em EVIDENCE.md). Pergunte ao aprovador(a). A alteração permanece sem merge (um PR de rascunho onde há PRs) enquanto o teste manual estiver aberto.

Concluído quando: o pacote é publicado, a linha do PR nomeia a pasta, o aprovador(a) é perguntado(a), e nada da alteração foi mesclado.

7. Registre o veredito

O veredito é do aprovador(a). Nunca registre um OK que eles não deram.

  • OK: verdict <pasta> --ok --por "<quem>" (recusa uma pasta que falhe em check), depois faça o que o arquivo do projeto diz que OK faz (geralmente: marcar o PR como pronto).
  • Não OK: verdict <pasta> --nao-ok --por "<quem>" --nota "<o que disseram>". Corrija no mesmo branch, archive a pasta, e volte para a etapa 3. A repetição criará os mesmos nomes de arquivo novamente; a captura antiga vai para previous/. Quando init escrever o novo README.md, copie as linhas que ainda valem de previous/<stamp>_README.md; pair reescreve os tempos.

Concluído quando: handtest.json contém o veredito da pessoa e o rastreador corresponde a ele.

Uma release

Mantenha cada pasta de teste manual sob uma pasta de grupo por release, depois execute report <grupo> --titulo "<release>". Ela escreve REPORT.md e um index.html autocontido, testes manuais pendentes primeiro. Veja EVIDENCE.md.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas