maestro-bug-video

Maestro Bug Video

Produce un MP4 que una persona que nunca ha visto el bug entienda sin ayuda: una tarjeta de título que nombre el bug, cada paso en lenguaje sencillo, un pie de foto que indique el resultado y un fotograma final congelado. El video solo es evidencia cuando la ejecución que lo respalda demuestra la afirmación, por lo que el resultado de Maestro es parte del entregable.

Dos modos comparten un mismo flujo de trabajo:

Modo	Muestra	Requiere
explain	Una ejecución de la compilación con el bug	Un flujo que reproduzca el bug
compare	La compilación con el bug y la corregida lado a lado	El mismo flujo, más una compilación con la corrección

Precondiciones

• Un flujo de Maestro que reproduzca el bug: falla en la compilación con el bug en el paso que observa el error y pasa en la compilación corregida. Si no existe tal flujo, escríbelo primero; un video de una ejecución que no observa el bug no prueba nada.
• maestro en PATH (uno fijado por el proyecto mediante mise exec -- cuando el proyecto lo fija), ffmpeg y ffprobe con el filtro drawtext. En Android, también adb y Python 3.10 o superior.
• Dispositivos o simuladores que puedan ejecutar la compilación con el bug y, para compare, la compilación corregida.

Flujo de trabajo

Las rutas como scripts/compose-bug-video son relativas al directorio de esta skill; los scripts no están en PATH.

1. Haz legible el flujo. Asigna a cada comando un label: en lenguaje sencillo que indique lo que el usuario hace o ve. Lee references/flow-tips.md antes de editar el flujo; cubre etiquetas, la variante de grabación y la velocidad.

2. Prepara la variante de grabación de la ejecución del bug. Copia el flujo, marca el paso que observa el bug como optional: true y renómbralo como Esperado: <comportamiento correcto> – <lo que ocurre en su lugar>. Un paso fallido terminaría la ejecución antes de que el renderizador termine; el paso opcional aún muestra ⚠ en el video y en el registro.

3. Instala las compilaciones. Compila el estado del bug a partir del commit anterior a la corrección, no revirtiendo archivos manualmente, a menos que la corrección sea una sola línea que restaures de inmediato. Un git worktree en el commit base con su propia salida de compilación mantiene las dos compilaciones separadas. Coloca cada compilación en su propio dispositivo o reinstala entre grabaciones.

4. Graba una ejecución a la vez. Antes de cada grabación, deja el dispositivo en su pantalla de inicio o en la aplicación bajo prueba: hasta que el primer paso del flujo cambie la pantalla, el video muestra lo que el dispositivo mostraba antes. En un simulador de iOS, usa el renderizador de Maestro:

   maestro --device <dispositivo-bug> record --local <variante-bug.yaml> before.mp4
   maestro --device <dispositivo-correccion> record --local <flujo.yaml> after.mp4
   

   Siempre pasa --local: sin él, Maestro sube la grabación a su nube para renderizarla.

   En un dispositivo o emulador Android, usa scripts/record-maestro-run en su lugar. maestro record corta el final de una ejecución en Android: screenrecord escribe fotogramas solo cuando la pantalla cambia, y el renderizador se detiene en el último fotograma, antes de la pantalla final de la ejecución. El script graba la pantalla por sí mismo, ejecuta maestro test, mantiene el último fotograma hasta que la ejecución realmente termina y dibuja los pasos desde el commands.json de Maestro:

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

   El video comienza en el primer paso del flujo, sin el inicio de Maestro. Termina con el código de salida de Maestro. La grabación no tiene límite de tiempo donde el screenrecord del dispositivo lo permita, como en Android 17; las versiones más antiguas detienen la grabación después de 180 segundos.

   Un flujo que escriba un secreto, como la contraseña de una cuenta de prueba desde ${MAESTRO_PASSWORD}, necesita un label: en ese inputText: maestro record imprime el texto resuelto en su lista de pasos, por lo que un paso sin etiqueta muestra el secreto en el video. record-maestro-run nunca muestra valores resueltos y mantiene los registros de Maestro, que registran el texto escrito, en un directorio temporal que elimina.

   Ejecuta las grabaciones de forma secuencial; dos procesos de Maestro iniciados por separado compiten por el mismo puerto del controlador y ambas ejecuciones se rompen. Antes de comenzar, verifica que ninguna ejecución anterior siga activa (pgrep -fl maestro) y detén las sobrantes que hayas iniciado.

5. Confirma que las ejecuciones demuestren la afirmación. La grabación del bug debe mostrar que todos los pasos de configuración pasaron y que el paso del bug advirtió (✅ y ⚠ del renderizador de Maestro; marcadores verdes y ámbar de record-maestro-run) con el bug visible en la pantalla; la grabación corregida debe mostrar que todos los pasos pasaron. Si alguno difiere, el video sería engañoso: detente y arregla el flujo o la compilación.

6. Compón el video con scripts/compose-bug-video:

   scripts/compose-bug-video explain --video before.mp4 \
     --title "<App> · <Pantalla>" --subtitle "Bug: <una oración que diría un usuario>" \
     --steps "<los pasos en una línea>" --caption "<lo que el espectador debe notar>" --out bug.mp4
   
   scripts/compose-bug-video compare --before before.mp4 --after after.mp4 \
     --title "<App> · <Pantalla>" --subtitle "Bug: <una oración>" \
     --steps "Los mismos pasos en ambos lados: <pasos>" \
     --caption "Izquierda: <lo que sale mal>.   Derecha: <lo que hace la corrección>." --out before-after.mp4
   

   Escribe la tarjeta de título y el pie de foto para alguien fuera del equipo: nombra la pantalla y el síntoma visible, no el código. Las etiquetas de los banners por defecto son "ANTES · app actual" y "DESPUÉS · con la corrección" (--before-label, --after-label); --hold establece la pausa del fotograma final.

7. Verifica el resultado antes de entregarlo. Extrae el fotograma del título y el último fotograma (ffmpeg -ss 1 -i out.mp4 -frames:v 1 title.png, ffmpeg -sseof -1 -i out.mp4 -frames:v 1 end.png) y míralos: el texto debe ser completo y legible, y el último fotograma debe mostrar el bug, o el bug junto a la corrección.

Finalización

Reporta la ruta del video, su duración, qué compilaciones o commits muestra cada lado y el resultado de Maestro para cada ejecución. La salida permanece local; publicarlo o adjuntarlo es decisión del usuario.