maestro-bug-video

Maestro Bug Video

Produza um MP4 que uma pessoa que nunca viu o bug entenda sem ajuda: um cartão de título que nomeia o bug, cada passo em linguagem simples, uma legenda que indique o resultado e um quadro final congelado. O vídeo é apenas evidência quando a execução por trás dele prova a afirmação, portanto o resultado do Maestro faz parte da entrega.

Dois modos compartilham um mesmo fluxo de trabalho:

Modo	Mostra	Requer
explain	Uma execução do build com bug	Um fluxo que reproduza o bug
compare	O build com bug e o build corrigido lado a lado	O mesmo fluxo, mais um build contendo a correção

Pré-requisitos

• Um fluxo Maestro que reproduza o bug: ele falha no build com bug no passo que observa o bug e passa no build corrigido. Se tal fluxo não existir, escreva-o primeiro; um vídeo de uma execução que não observa o bug não prova nada.
• maestro no PATH (um com versão fixada via mise exec -- quando o projeto a fixar), ffmpeg e ffprobe com o filtro drawtext. No Android, também adb e Python 3.10 ou mais novo.
• Dispositivos ou simuladores que possam executar o build com bug e, para compare, o build corrigido.

Fluxo de Trabalho

Caminhos como scripts/compose-bug-video são relativos ao diretório desta skill; os scripts não estão no PATH.

1. Torne o fluxo legível. Dê a cada comando um label: em linguagem simples que diga o que o usuário faz ou vê. Leia references/flow-tips.md antes de editar o fluxo; ele cobre labels, a variante de gravação e velocidade.

2. Prepare a variante de gravação da execução do bug. Copie o fluxo, marque o passo que observa o bug como optional: true e renomeie-o para Esperado: <comportamento correto> – <o que acontece em vez disso>. Um passo com falha encerraria a execução antes de o renderizador terminar; o passo opcional ainda mostra ⚠ no vídeo e no log.

3. Instale os builds. Compile o estado do bug a partir do commit anterior à correção, não revertendo arquivos manualmente, a menos que a correção seja uma única linha que você restaure imediatamente. Uma git worktree no commit base com sua própria saída de build mantém os dois builds separados. Coloque cada build em seu próprio dispositivo ou reinstale entre as gravações.

4. Grave uma execução de cada vez. Antes de cada gravação, deixe o dispositivo na tela inicial ou no aplicativo em teste: até que o primeiro passo do fluxo mude a tela, o vídeo mostra o que o dispositivo exibia antes. Em um simulador iOS, use o renderizador do Maestro:

   maestro --device <dispositivo-bug> record --local <variante-bug.yaml> before.mp4
   maestro --device <dispositivo-correcao> record --local <fluxo.yaml> after.mp4
   

   Sempre passe --local: sem ele, o Maestro envia a gravação para sua nuvem para renderização.

   Em um dispositivo ou emulador Android, use scripts/record-maestro-run em vez disso. maestro record corta o final de uma execução Android: screenrecord grava quadros apenas quando a tela muda, e o renderizador para no último quadro, antes da tela final da execução. O script grava a tela por conta própria, executa maestro test, mantém o último quadro até a execução realmente terminar e desenha os passos a partir do commands.json do Maestro:

   scripts/record-maestro-run --device <dispositivo-bug> --flow <variante-bug.yaml> --out before.mp4
   scripts/record-maestro-run --device <dispositivo-correcao> --flow <fluxo.yaml> --out after.mp4 --maestro "mise exec -- maestro"
   

   O vídeo começa no primeiro passo do fluxo, sem a inicialização do Maestro. Ele sai com o código de saída do Maestro. A gravação não tem limite de tempo onde o screenrecord do dispositivo permitir, como no Android 17; versões mais antigas param a gravação após 180 segundos.

   Um fluxo que digita um segredo, como a senha de uma conta de teste de ${MAESTRO_PASSWORD}, precisa de um label: nesse inputText: maestro record imprime o texto resolvido em sua lista de passos, então um passo sem label mostra o segredo no vídeo. record-maestro-run nunca mostra valores resolvidos e mantém os logs do Maestro, que registram texto digitado, em um diretório temporário que ele exclui.

   Execute as gravações sequencialmente; dois processos Maestro iniciados separadamente competem pela mesma porta do driver e ambas as execuções quebram. Antes de começar, verifique se nenhuma execução anterior ainda está ativa (pgrep -fl maestro) e pare os resquícios que você iniciou.

5. Confirme se as execuções provam a afirmação. A gravação do bug deve mostrar cada passo de configuração passado e o passo do bug como aviso (✅ e ⚠ do renderizador do Maestro; marcadores verdes e âmbar do record-maestro-run) com o bug visível na tela; a gravação corrigida deve mostrar todos os passos passados. Se algum diferir, o vídeo enganaria: pare e corrija o fluxo ou o build.

6. Componha o vídeo com scripts/compose-bug-video:

   scripts/compose-bug-video explain --video before.mp4 \
     --title "<App> · <Tela>" --subtitle "Bug: <uma frase que um usuário diria>" \
     --steps "<os passos em uma linha>" --caption "<o que o espectador deve notar>" --out bug.mp4
   
   scripts/compose-bug-video compare --before before.mp4 --after after.mp4 \
     --title "<App> · <Tela>" --subtitle "Bug: <uma frase>" \
     --steps "Mesmos passos em ambos os lados: <passos>" \
     --caption "Esquerda: <o que dá errado>.   Direita: <o que a correção faz>." --out before-after.mp4
   

   Escreva o cartão de título e a legenda para alguém de fora da equipe: nomeie a tela e o sintoma visível, não o código. Os rótulos dos banners padrão são "ANTES · aplicativo atual" e "DEPOIS · com a correção" (--before-label, --after-label); --hold define a pausa do quadro final.

7. Verifique o resultado antes de entregá-lo. Extraia o quadro do título e o último quadro (ffmpeg -ss 1 -i saida.mp4 -frames:v 1 titulo.png, ffmpeg -sseof -1 -i saida.mp4 -frames:v 1 fim.png) e olhe para eles: o texto deve estar completo e legível, e o último quadro deve mostrar o bug, ou o bug ao lado da correção.

Conclusão

Informe o caminho do vídeo, sua duração, quais builds ou commits cada lado mostra e o resultado do Maestro para cada execução. A saída permanece local; publicar ou anexá-la é decisão do usuário.