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
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 manterHANDTEST_ROOTentre comandos: defina-o no mesmo comando.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.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.- 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. Depoisboard --antes <png> --depois <png> --titulo ... --legenda ... --saida <pasta>/<id>_<topico>_ANTES_DEPOIS.png. - 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:
archivea 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 emcheck), 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,archivea pasta, e volte para a etapa 3. A repetição criará os mesmos nomes de arquivo novamente; a captura antiga vai paraprevious/. Quandoinitescrever o novo README.md, copie as linhas que ainda valem deprevious/<stamp>_README.md;pairreescreve 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.