pretty-good-software-org/maestro-bug-video

Maestro Bug Video

Produisez un MP4 qu'une personne n'ayant jamais vu le bogue comprend sans aide : une carte de titre qui nomme le bogue, chaque étape en langage clair, une légende qui indique le résultat, et une dernière image maintenue. La vidéo n'est une preuve que lorsque l'exécution qui la sous-tend prouve l'affirmation, donc le résultat de Maestro fait partie du livrable.

Deux modes partagent un même workflow :

Mode	Montre	Nécessite
explain	Une exécution de la build boguée	Un flux qui reproduit le bogue
compare	La build boguée et la build corrigée côte à côte	Le même flux, plus une build contenant la correction

Prérequis

• Un flux Maestro qui reproduit le bogue : il échoue sur la build boguée à l'étape qui observe le bogue, et réussit sur la build corrigée. Si un tel flux n'existe pas, écrivez-le d'abord ; une vidéo d'une exécution qui n'observe pas le bogue ne prouve rien.
• maestro dans le PATH (un projet épinglé via mise exec -- lorsque le projet l'épingle), ffmpeg et ffprobe avec le filtre drawtext. Sur Android, également adb et Python 3.10 ou plus récent.
• Appareils ou simulateurs capables d'exécuter la build boguée et, pour compare, la build corrigée.

Workflow

Les chemins comme scripts/compose-bug-video sont relatifs au répertoire de ce skill ; les scripts ne sont pas dans le PATH.

1. Rendre le flux lisible. Donnez à chaque commande un label: en langage clair qui indique ce que l'utilisateur fait ou voit. Lisez references/flow-tips.md avant de modifier le flux ; cela couvre les labels, la variante d'enregistrement et la vitesse.

2. Préparer la variante d'enregistrement de l'exécution du bogue. Copiez le flux, marquez l'étape qui observe le bogue optional: true, et renommez-la en Attendu : <comportement correct> – <ce qui se passe à la place>. Une étape en échec mettrait fin à l'exécution avant la fin du rendu ; l'étape facultative affiche toujours ⚠ dans la vidéo et dans le journal.

3. Installer les builds. Construisez l'état bogué à partir du commit avant la correction, pas en annulant manuellement des fichiers, sauf si la correction est une seule ligne que vous restaurez immédiatement. Un git worktree sur le commit de base avec son propre résultat de build garde les deux builds séparées. Mettez chaque build sur son propre appareil ou réinstallez entre les enregistrements.

4. Enregistrer une exécution à la fois. Avant chaque enregistrement, laissez l'appareil sur son écran d'accueil ou sur l'application testée : jusqu'à ce que la première étape du flux change l'écran, la vidéo montre ce que l'appareil affichait avant. Sur un simulateur iOS, utilisez le rendu de Maestro :

   maestro --device <appareil-bogue> record --local <variante-bogue.yaml> before.mp4
   maestro --device <appareil-correction> record --local <flux.yaml> after.mp4
   

   Passez toujours --local : sans cela, Maestro télécharge l'enregistrement vers son cloud pour le rendu.

   Sur un appareil ou émulateur Android, utilisez scripts/record-maestro-run à la place. maestro record coupe la fin d'une exécution Android : screenrecord écrit des images uniquement lorsque l'écran change, et le rendu s'arrête à la dernière image, avant l'écran final de l'exécution. Le script enregistre l'écran lui-même, exécute maestro test, maintient la dernière image jusqu'à ce que l'exécution soit vraiment terminée, et dessine les étapes à partir de commands.json de Maestro :

   scripts/record-maestro-run --device <appareil-bogue> --flow <variante-bogue.yaml> --out before.mp4
   scripts/record-maestro-run --device <appareil-correction> --flow <flux.yaml> --out after.mp4 --maestro "mise exec -- maestro"
   

   La vidéo commence à la première étape du flux, sans le démarrage de Maestro. Elle se termine avec le code de sortie de Maestro. L'enregistrement n'a pas de limite de temps là où le screenrecord de l'appareil le permet, comme sur Android 17 ; les versions plus anciennes arrêtent l'enregistrement après 180 secondes.

   Un flux qui saisit un secret, comme le mot de passe d'un compte de test depuis ${MAESTRO_PASSWORD}, a besoin d'un label: sur cet inputText : maestro record imprime le texte résolu dans sa liste d'étapes, donc une étape sans label montre le secret dans la vidéo. record-maestro-run ne montre jamais les valeurs résolues et conserve les journaux de Maestro, qui enregistrent le texte tapé, dans un répertoire temporaire qu'il supprime.

   Lancez les enregistrements séquentiellement ; deux processus Maestro démarrés séparément se disputent le même port de pilote et les deux exécutions échouent. Avant de commencer, vérifiez qu'aucune exécution antérieure n'est encore active (pgrep -fl maestro) et arrêtez les résidus que vous avez démarrés.

5. Confirmer que les exécutions prouvent l'affirmation. L'enregistrement du bogue doit montrer chaque étape de configuration réussie et l'étape du bogue avertie (✅ et ⚠ du rendu de Maestro ; marqueurs vert et ambre de record-maestro-run) avec le bogue visible à l'écran ; l'enregistrement corrigé doit montrer chaque étape réussie. Si l'un diffère, la vidéo induirait en erreur : arrêtez et corrigez le flux ou la build.

6. Composer la vidéo avec scripts/compose-bug-video :

   scripts/compose-bug-video explain --video before.mp4 \
     --title "<App> · <Écran>" --subtitle "Bogue : <une phrase qu'un utilisateur dirait>" \
     --steps "<les étapes en une ligne>" --caption "<ce que le spectateur doit remarquer>" --out bug.mp4
   
   scripts/compose-bug-video compare --before before.mp4 --after after.mp4 \
     --title "<App> · <Écran>" --subtitle "Bogue : <une phrase>" \
     --steps "Mêmes étapes des deux côtés : <étapes>" \
     --caption "Gauche : <ce qui ne va pas>.   Droite : <ce que la correction fait>." --out before-after.mp4
   

   Écrivez la carte de titre et la légende pour quelqu'un en dehors de l'équipe : nommez l'écran et le symptôme visible, pas le code. Les labels des bannières par défaut sont "AVANT · application actuelle" et "APRÈS · avec la correction" (--before-label, --after-label) ; --hold définit la pause de la dernière image.

7. Vérifier le résultat avant de le remettre. Extrayez l'image du titre et la dernière image (ffmpeg -ss 1 -i out.mp4 -frames:v 1 title.png, ffmpeg -sseof -1 -i out.mp4 -frames:v 1 end.png) et regardez-les : le texte doit être complet et lisible, et la dernière image doit montrer le bogue, ou le bogue à côté de la correction.

Fin

Rapportez le chemin de la vidéo, sa durée, quelles builds ou commits chaque côté montre, et le résultat Maestro pour chaque exécution. Le résultat reste local ; sa publication ou son attachement est la décision de l'utilisateur.