Maestro バグ動画
バグを一度も見たことがない人でも、助けなしに理解できる MP4 を生成します。バグの名前を示すタイトルカード、平易な言葉での各ステップ、結果を述べるキャプション、そして最後のフレームを保持します。動画は、その背後にある実行が主張を証明する場合にのみ証拠となるため、Maestro の結果も成果物に含まれます。
2つのモードが1つのワークフローを共有します:
| モード | 表示内容 | 必要なもの |
|---|---|---|
explain | バグビルドの1回の実行 | バグを再現するフロー |
compare | バグビルドと修正ビルドを並べて表示 | 同じフローに加え、修正を含むビルド |
前提条件
- バグを再現する Maestro フロー: バグビルドではバグを観測するステップで失敗し、修正ビルドでは成功するもの。そのようなフローが存在しない場合は、まず作成してください。バグを観測しない実行の動画は何も証明しません。
maestroが PATH 上にあること（プロジェクトで固定している場合はmise exec --経由）、ffmpegとffprobeがdrawtextフィルタ付きで利用可能であること。Android の場合は、さらにadbと Python 3.10 以降が必要です。- バグビルドを実行できるデバイスまたはシミュレーター、および
compareモード用の修正ビルドを実行できるデバイスまたはシミュレーター。
ワークフロー
scripts/compose-bug-video などのパスは、このスキルのディレクトリからの相対パスです。スクリプトは PATH 上にありません。
-
フローを読みやすくする。 すべてのコマンドに、ユーザーが何をするか、何を見るかを示す平易な言語の
label:を付けます。フローを編集する前にreferences/flow-tips.mdを読んでください。ラベル、録画用バリアント、速度について説明しています。 -
バグ実行の録画用バリアントを準備する。 フローをコピーし、バグを観測するステップを
optional: trueにマークし、ラベルを期待される動作: <正しい動作> – <実際に発生すること>に変更します。失敗するステップがあると、レンダラーが終了する前に実行が終了してしまいます。オプションのステップは動画とログに ⚠ を表示します。 -
ビルドをインストールする。 バグ状態のビルドは、修正前のコミットから行います。ファイルを手動で元に戻すのではなく（修正がすぐに元に戻せる1行の場合は除く）、ベースコミットに
git worktreeを作成し、独自のビルド出力を持つようにして2つのビルドを分離します。各ビルドを別々のデバイスに配置するか、録画の間に再インストールします。 -
1回の実行を録画する。 各録画の前に、デバイスをホーム画面またはテスト中のアプリの画面にしておきます。フローの最初のステップが画面を変更するまで、動画にはその前にデバイスに表示されていたものが表示されます。 iOS シミュレーターでは、Maestro のレンダラーを使用します:
maestro --device <bug-device> record --local <bug-variant.yaml> before.mp4 maestro --device <fix-device> record --local <flow.yaml> after.mp4必ず
--localを指定してください。指定しないと、Maestro は録画をクラウドにアップロードしてレンダリングします。Android デバイスまたはエミュレーターでは、代わりに
scripts/record-maestro-runを使用します。maestro recordは Android の実行の終わりをカットします。screenrecordは画面が変更されたときのみフレームを書き込み、レンダラーは実行の最後の画面の前に最後のフレームで停止します。このスクリプトは、画面を自ら録画し、maestro testを実行し、実行が実際に終了するまで最後のフレームを保持し、Maestro のcommands.jsonからステップを描画します:scripts/record-maestro-run --device <bug-device> --flow <bug-variant.yaml> --out before.mp4 scripts/record-maestro-run --device <fix-device> --flow <flow.yaml> --out after.mp4 --maestro "mise exec -- maestro"動画は Maestro の起動なしに、フローの最初のステップから始まります。Maestro の終了コードで終了します。 録画に時間制限はありません（デバイスの
screenrecordが許可する場合。Android 17 以降では無制限ですが、古いバージョンでは 180 秒で録画が停止します）。${MAESTRO_PASSWORD}などのシークレットを入力するフローでは、そのinputTextにlabel:が必要です。maestro recordは解決されたテキストをステップリストに表示するため、ラベルのないステップは動画にシークレットを表示してしまいます。record-maestro-runは解決された値を表示せず、入力されたテキストを記録する Maestro のログは、削除される一時ディレクトリに保持します。録画は順次実行してください。別々に開始された2つの Maestro プロセスは同じドライバーポートを競合し、両方の実行が壊れます。開始する前に、以前の実行がまだ生きていないことを確認し（
pgrep -fl maestro）、自分が開始した残存プロセスを停止してください。 -
実行が主張を証明することを確認する。 バグの録画では、すべてのセットアップステップが成功し、バグステップが警告されたこと（Maestro のレンダラーでは ✅ と ⚠、
record-maestro-runでは緑と琥珀のマーカー）が示され、画面上にバグが表示されている必要があります。修正の録画では、すべてのステップが成功している必要があります。どちらかが異なる場合、動画は誤解を招くため、停止してフローまたはビルドを修正してください。 -
動画を合成する
scripts/compose-bug-videoを使用:scripts/compose-bug-video explain --video before.mp4 \ --title "<アプリ名> · <画面名>" --subtitle "バグ: <ユーザーが言いそうな一文>" \ --steps "<1行でのステップ>" --caption "<視聴者が注目すべき点>" --out bug.mp4 scripts/compose-bug-video compare --before before.mp4 --after after.mp4 \ --title "<アプリ名> · <画面名>" --subtitle "バグ: <一文>" \ --steps "両側で同じステップ: <ステップ>" \ --caption "左: <問題の内容>。 右: <修正の効果>。" --out before-after.mp4タイトルカードとキャプションは、チーム外の人のために書いてください。画面名と目に見える症状をコードではなく記述します。バナーのラベルはデフォルトで「BEFORE · current app」と「AFTER · with the fix」になります（
--before-label、--after-labelで変更可能）。--holdで最終フレームの一時停止時間を設定します。 -
結果を引き渡す前に確認する。 タイトルフレームと最終フレームを抽出し（
ffmpeg -ss 1 -i out.mp4 -frames:v 1 title.png、ffmpeg -sseof -1 -i out.mp4 -frames:v 1 end.png）、テキストが完全で読みやすく、最終フレームにバグ、またはバグと修正が表示されていることを確認します。
完了
動画のパス、長さ、各サイドが示すビルドまたはコミット、および各実行の Maestro の結果を報告します。出力はローカルに留まります。公開や添付はユーザーの判断に委ねられます。