Maestro Bug Video

Was macht Maestro Bug Video?

Erstelle ein MP4, das eine Person, die den Bug noch nie gesehen hat, ohne Hilfe versteht: eine Titelkarte, die den Bug benennt, jeder Schritt in einfacher Sprache, eine Bildunterschrift, die das Ergebnis angibt, und ein gehaltener letzter Frame. Das Video ist nur dann ein Beweis, wenn der dahinterliegende Lauf die Behauptung belegt, daher ist das Maestro-Ergebnis Teil des Ergebnisses.

Zwei Modi teilen sich einen Workflow:

Modus	Zeigt	Erfordert
explain	Ein Lauf des Bug-Builds	Einen Flow, der den Bug reproduziert
compare	Den Bug-Build und den gefixten Build nebeneinander	Den gleichen Flow, plus einen Build mit dem Fix

Voraussetzungen

• Ein Maestro-Flow, der den Bug reproduziert: Er schlägt im Bug-Build bei dem Schritt fehl, der den Bug beobachtet, und besteht im gefixten Build. Falls ein solcher Flow nicht existiert, schreibe ihn zuerst; ein Video eines Laufs, der den Bug nicht beobachtet, beweist nichts.
• maestro im PATH (ein projektgebundenes via mise exec --, wenn das Projekt es bindet), ffmpeg und ffprobe mit dem drawtext-Filter. Auf Android außerdem adb und Python 3.10 oder neuer.
• Geräte oder Simulatoren, die den Bug-Build ausführen können, und für compare auch den gefixten Build.

Workflow

Pfade wie scripts/compose-bug-video sind relativ zum Verzeichnis dieses Skills; die Skripte befinden sich nicht im PATH.

1. Mach den Flow lesbar. Gib jedem Befehl eine label: in einfacher Sprache, die angibt, was der Benutzer tut oder sieht. Lies references/flow-tips.md, bevor du den Flow bearbeitest; es behandelt Labels, die Aufzeichnungsvariante und Geschwindigkeit.

2. Bereite die Aufzeichnungsvariante des Bug-Laufs vor. Kopiere den Flow, markiere den Schritt, der den Bug beobachtet, als optional: true, und nenne ihn um in Erwartet: <korrektes Verhalten> – <was stattdessen passiert>. Ein fehlschlagender Schritt würde den Lauf beenden, bevor der Renderer fertig ist; der optionale Schritt zeigt trotzdem ⚠ im Video und im Log.

3. Installiere die Builds. Baue den Bug-Zustand aus dem Commit vor dem Fix, nicht durch manuelles Rückgängigmachen von Dateien, es sei denn, der Fix ist eine einzelne Zeile, die du sofort wiederherstellst. Ein git worktree im Basis-Commit mit eigener Build-Ausgabe hält die beiden Builds getrennt. Setze jeden Build auf ein eigenes Gerät oder installiere zwischen den Aufnahmen neu.

4. Nimm einen Lauf nach dem anderen auf. Lasse das Gerät vor jeder Aufnahme auf dem Startbildschirm oder in der getesteten App: Bis der erste Schritt des Flows den Bildschirm ändert, zeigt das Video, was das Gerät zuvor gezeigt hat. Verwende auf einem iOS-Simulator Maestros Renderer:

   maestro --device <bug-geraet> record --local <bug-variante.yaml> before.mp4
   maestro --device <fix-geraet> record --local <flow.yaml> after.mp4
   

   Übergib immer --local: Ohne diesen Parameter lädt Maestro die Aufnahme zur Verarbeitung in die Cloud hoch.

   Verwende auf einem Android-Gerät oder Emulator stattdessen scripts/record-maestro-run. maestro record schneidet das Ende eines Android-Laufs ab: screenrecord schreibt nur dann Frames, wenn sich der Bildschirm ändert, und der Renderer stoppt beim letzten Frame, bevor der endgültige Bildschirm des Laufs erreicht ist. Das Skript zeichnet den Bildschirm selbst auf, führt maestro test aus, hält den letzten Frame, bis der Lauf wirklich beendet ist, und zeichnet die Schritte aus Maestros commands.json ein:

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

   Das Video beginnt mit dem ersten Schritt des Flows, ohne Maestros Startphase. Es endet mit Maestros Exit-Code. Die Aufnahme hat keine Zeitbegrenzung, wenn das Geräte-screenrecord dies zulässt, wie bei Android 17; ältere Versionen beenden die Aufnahme nach 180 Sekunden.

   Ein Flow, der ein Geheimnis eingibt, wie z.B. ein Passwort eines Testkontos aus ${MAESTRO_PASSWORD}, benötigt ein label: für dieses inputText: maestro record gibt den aufgelösten Text in seiner Schrittliste aus, daher zeigt ein nicht beschrifteter Schritt das Geheimnis im Video. record-maestro-run zeigt niemals aufgelöste Werte an und bewahrt Maestros Logs, die getippten Text aufzeichnen, in einem temporären Verzeichnis auf, das es löscht.

   Führe Aufnahmen nacheinander durch; zwei gleichzeitig gestartete Maestro-Prozesse konkurrieren um denselben Treiber-Port, und beide Läufe brechen ab. Überprüfe vor dem Start, dass kein früherer Lauf noch aktiv ist (pgrep -fl maestro) und stoppe übrig gebliebene, die du gestartet hast.

5. Bestätige, dass die Läufe die Behauptung belegen. Die Bug-Aufnahme muss zeigen, dass alle Einrichtungsschritte bestanden wurden und der Bug-Schritt gewarnt wurde (✅ und ⚠ von Maestros Renderer; grüne und gelbe Marker von record-maestro-run), wobei der Bug auf dem Bildschirm sichtbar ist; die Fix-Aufnahme muss zeigen, dass alle Schritte bestanden wurden. Weicht eines ab, würde das Video irreführen: Stoppe und korrigiere den Flow oder den Build.

6. Erstelle das Video mit scripts/compose-bug-video:

   scripts/compose-bug-video explain --video before.mp4 \
     --title "<App> · <Bildschirm>" --subtitle "Bug: <ein Satz, den ein Benutzer sagen würde>" \
     --steps "<die Schritte in einer Zeile>" --caption "<was der Betrachter beachten sollte>" --out bug.mp4
   
   scripts/compose-bug-video compare --before before.mp4 --after after.mp4 \
     --title "<App> · <Bildschirm>" --subtitle "Bug: <ein Satz>" \
     --steps "Gleiche Schritte auf beiden Seiten: <Schritte>" \
     --caption "Links: <was schiefgeht>.   Rechts: <was der Fix bewirkt>." --out before-after.mp4
   

   Schreibe die Titelkarte und Bildunterschrift für jemanden außerhalb des Teams: Nenne den Bildschirm und das sichtbare Symptom, nicht den Code. Die Banner-Beschriftungen standardmäßig auf "VORHER · aktuelle App" und "NACHHER · mit dem Fix" (--before-label, --after-label); --hold legt die Pause des letzten Frames fest.

7. Überprüfe das Ergebnis, bevor du es übergibst. Extrahiere den Titel-Frame und den letzten Frame (ffmpeg -ss 1 -i out.mp4 -frames:v 1 title.png, ffmpeg -sseof -1 -i out.mp4 -frames:v 1 end.png) und betrachte sie: Der Text muss vollständig und lesbar sein, und der letzte Frame muss den Bug zeigen, oder den Bug neben dem Fix.

Abschluss

Melde den Videopfad, seine Länge, welche Builds oder Commits jede Seite zeigt und das Maestro-Ergebnis für jeden Lauf. Die Ausgabe bleibt lokal; das Veröffentlichen oder Anhängen ist die Entscheidung des Benutzers.