agent-browser-visual

ビジュアルエビデンスと回帰 — 実行プロトコル

内部テンプレート。 エントリーポイント：agent-browser スキル。

---

絶対に行わないこと

NEVER compare screenshots before `wait --load networkidle` — animation frames cause false diffs
NEVER use default diff threshold for pixel-perfect checks — set --threshold 0.05 or lower
NEVER skip baseline update after intentional UI changes — stale baseline = false positives forever
NEVER start `network har start` after navigation — HAR must begin before the requests you want to capture
NEVER start `record start` before opening the page — start after `open` + `wait` to preserve auth state

---

ユースケースの判断ツリー

目的	コマンド
ビジュアル回帰を検出する（デプロイ前後）	diff screenshot --baseline
ステージングと本番環境を並べて比較する	diff url
DOM 構造の変更を検出する	diff snapshot
共有可能なデモ／バグ報告用の動画を作成する	record start → 操作 → record stop
ドキュメント／チケット用の注釈付きスクリーンショットを作成する	screenshot --annotate
パフォーマンス調査／デバッグ用にネットワークトレース全体を取得する	network har start → 操作 → network har stop

---

ビジュアル回帰のワークフロー

# Step 1: Capture baseline (run once before changes)
agent-browser open <url>
agent-browser wait --load networkidle
agent-browser screenshot --full baseline.png

# Step 2: After changes, compare
agent-browser open <url>
agent-browser wait --load networkidle
agent-browser diff screenshot --baseline baseline.png --output diff.png --threshold 0.1

# Step 3: Scope to specific element (reduces noise from unrelated areas)
agent-browser diff screenshot --baseline baseline.png -s "#main-content"

# Step 4: Compare two environments (snapshot + optionally screenshots)
agent-browser diff url https://staging.example.com https://prod.example.com
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot --full

しきい値の目安：

• 0.1（デフォルト）— アンチエイリアスや軽微な描画の違いを許容します
• 0.05 — 微妙な色／フォントの変化を検出します
• 0.01 — ピクセル単位で完全に一致させます（描画の違いに敏感です）
• 0.2 — 動的コンテンツ領域向けの許容モードです

---

動画録画のワークフロー

# Best practice: open page first, then start recording (preserves auth state)
agent-browser open <url>
agent-browser wait --load networkidle
agent-browser snapshot -i            # explore first, plan your actions
agent-browser record start ./demo.webm
# ... perform actions ...
agent-browser record stop

# Record from a fresh URL
agent-browser record start ./onboarding.webm https://app.example.com/signup

# Restart (stop current recording, start new — useful for retakes)
agent-browser record restart ./take2.webm

WebM を GIF に変換するには：ffmpeg -i demo.webm -vf "fps=10,scale=800:-1:flags=lanczos" demo.gif

---

注釈付きスクリーンショット

agent-browser screenshot --annotate step1.png

出力：番号付きラベルを重ねたスクリーンショットと、各番号を要素名に対応付ける凡例です。

最適な用途：バグ報告、ドキュメント、技術に詳しくないレビュアーとの状況共有。注釈ラベルは、カーソルのオーバーレイよりもスクリーンショットの圧縮後に見やすく残ります。

---

HAR の記録（ネットワークトレース全体）

# Must start BEFORE navigation to capture all requests
agent-browser network har start ./trace.har
agent-browser open <url>
agent-browser wait --load networkidle
# ... perform actions you want to trace ...
agent-browser network har stop

# View: open in browser DevTools → Network tab → Import HAR
# Or: https://har.tech (online analyzer)

用途：ページの遅延の診断、API 呼び出しの検証、サードパーティーリクエストの監査です。

---

DOM スナップショットの差分

# Compare current DOM vs last snapshot in this session
agent-browser diff snapshot

# Compare against a saved snapshot file
agent-browser diff snapshot --baseline before.txt

# Scope to a specific section
agent-browser diff snapshot -s ".sidebar" -c

# Combined: compact + depth-limited scope
agent-browser diff snapshot -s "#app" -c -d 4

用途：コード変更によって DOM 構造が気付かないうちに変わっていないかの確認、または UI コンポーネントが環境間で同一にレンダリングされるかの確認です。

---

復旧パターン

失敗	復旧方法
差分に常に変更が表示される（アニメーション／読み込み）	wait --load networkidle を実行し、CSS トランジションには wait 500 を追加します
差分が敏感すぎる（アンチエイリアスのノイズ）	--threshold 0.2 に引き上げます
差分で実際の回帰を検出できない	--threshold 0.05 に引き下げます
動画ファイルが大きすぎる	録画対象を短いフローに絞ります。静的なエビデンスには screenshot --full を使用します
HAR に初期のリクエストが含まれない	記録を再開します。network har start は open より前に呼び出す必要があります
record で認証状態が失われる	必ず先に open と wait を実行し、その後に record start を実行します（URL 引数なし）

---

注意点

間違い	修正方法
ページが安定する前にスクリーンショットを撮影する	キャプチャの前に wait --load networkidle を実行します
意図的なデザイン変更後にベースラインを更新しない	古いベースラインを削除し、再キャプチャします：screenshot --full baseline.png
--baseline なしで diff screenshot を実行する	--baseline <file> が必要です
XHR 呼び出しがすでに発生した後に HAR の記録を開始する	network har start は open または reload より前に実行する必要があります
ページを開く前に record start を実行すると認証が失われる	先にページを開いて待機し、その後、録画を開始します