chrome-debug

リモートデバッグプロトコルによる Chrome のデバッグとブラウザー操作

概要

Chrome DevTools Protocol（CDP）を使うと、mcporter を介してブラウザーをリモートで自動化およびデバッグできます。

主な機能：

• エージェントとの会話と並行した、ブラウザーのライブデバッグ
• フォーム入力と操作の自動テスト
• スクリーンショットによる視覚的なフィードバック
• コンソールログとネットワークリクエストの検査
• ページのコンテキストでの JavaScript の実行

前提条件 [CRITICAL]

Chrome DevTools を使用する前に、以下を確認してください。

1. Chrome/Chromium がリモートデバッグを有効にして起動している
2. ブラウザーがポート 9222（デフォルト）で待ち受けている
3. 次のコマンドで接続をテストする

mise x node@20 -- mcporter call chrome-devtools.list_pages

失敗した場合：

• Chrome を起動します：google-chrome --remote-debugging-port=9222
• ポート 9222 を使用しているほかのプロセスがないことを確認します
• ブラウザーのセットアップについて人に助けを求めます

利用可能なツール

ツール	用途
list_pages	開いているすべてのページ／タブを一覧表示する
select_page	操作するページ／タブを選択する
new_page	新しいブラウザーページ／タブを作成する
close_page	ブラウザーページ／タブを閉じる
navigate_page	URL への移動、戻る、進む、または再読み込みを行う
take_snapshot	検査用の DOM スナップショットを取得する（UID を返す）
take_screenshot	現在のページのスクリーンショットを撮影する
click	ページ上の要素をクリックする
fill	入力フィールドにテキストを入力する
hover	要素にカーソルを合わせる
press_key	キーボードキー（Enter、Tab、Escape など）を押す
evaluate_script	ページのコンテキストで JavaScript コードを実行する
wait_for	要素、ページ遷移、または条件を待つ
list_console_messages	すべてのコンソールメッセージ（ログ、エラー、警告）を取得する
list_network_requests	ページが行ったすべてのネットワークリクエストを取得する
emulate	デバイス設定（ネットワーク、CPU のスロットリング）をエミュレートする
resize_page	ブラウザーのビューポートのサイズを変更する
performance_start_trace	パフォーマンストレースを開始する
performance_stop_trace	パフォーマンストレースを停止し、結果を取得する

ヒント

ツールの一覧をすべて表示するには、mcporter list chrome-devtools --json | jq -r '.tools[] | [.name, .description] | @tsv' | column -t -s $'\t' を実行してください。

基本概念

1. ページ選択モデル

• Chrome DevTools は複数のページ／タブを操作します
• list_pages を使って、開いているすべてのページを確認します
• select_page を使って、操作するページを選択します
• 以降のすべてのコマンドは、選択したページに対して実行されます

2. UID ベースの要素モデル [CRITICAL]

• CSS セレクターを使って要素を直接操作することはできません
• まず take_snapshot を呼び出し、UID を含むアクセシビリティツリーを取得する必要があります
• UID は要素を識別する一時的な ID です（例：「5」、「12」、「42」）
• UID はページ遷移時に無効になります。ページ遷移後に新しいスナップショットを取得してください

3. JSON 引数が必要

• すべての mcporter コマンドで、JSON オブジェクトを指定した --args が必要です
• プロパティ名はキャメルケースです（例：filePath、fullPage、pageIdx）
• --file-path や --full-page のような個別のフラグは使用しないでください

4. 関数ベースのスクリプト評価

• evaluate_script には、プレーンなコードではなく関数宣言が必要です
• 戻り値は JSON にシリアライズ可能でなければなりません
• UID を使い、args 配列を介して要素の引数を渡せます

クイックリファレンス

bash で使いやすい形式の必須コマンド：

# List and select page
mise x node@20 -- mcporter call chrome-devtools.list_pages
mise x node@20 -- mcporter call chrome-devtools.select_page --args '{"pageIdx":0}'

# Take snapshot to get UIDs
mise x node@20 -- mcporter call chrome-devtools.take_snapshot

# Take screenshot
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

# Take full-page screenshot
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./full.png","fullPage":true}'

# Navigate to URL
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"url","url":"http://localhost:3000"}'

# Navigate back/forward/reload
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"back"}'
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"reload"}'

# Click element (requires UID from snapshot)
mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"12"}'

# Fill input field
mise x node@20 -- mcporter call chrome-devtools.fill --args '{"uid":"5","value":"[email protected]"}'

# Hover element
mise x node@20 -- mcporter call chrome-devtools.hover --args '{"uid":"8"}'

# Press key
mise x node@20 -- mcporter call chrome-devtools.press_key --args '{"key":"Enter"}'

# Run JavaScript
mise x node@20 -- mcporter call chrome-devtools.evaluate_script --args '{"function":"() => { return document.title }"}'

# Run JS with element argument
mise x node@20 -- mcporter call chrome-devtools.evaluate_script --args '{"function":"(el) => { return el.innerText }","args":[{"uid":"12"}]}'

# List console messages
mise x node@20 -- mcporter call chrome-devtools.list_console_messages

# List only errors
mise x node@20 -- mcporter call chrome-devtools.list_console_messages --args '{"types":["error"]}'

# List network requests
mise x node@20 -- mcporter call chrome-devtools.list_network_requests

# Filter network by type
mise x node@20 -- mcporter call chrome-devtools.list_network_requests --args '{"types":["fetch","xhr"]}'

# Wait for text to appear
mise x node@20 -- mcporter call chrome-devtools.wait_for --args '{"text":"Success"}'

# Emulate network conditions
mise x node@20 -- mcporter call chrome-devtools.emulate --args '{"networkConditions":"Slow 3G"}'

よくあるワークフロー

基本的な要素操作

# 1. Select page and take snapshot
mise x node@20 -- mcporter call chrome-devtools.list_pages
mise x node@20 -- mcporter call chrome-devtools.select_page --args '{"pageIdx":0}'
SNAPSHOT=$(mise x node@20 -- mcporter call chrome-devtools.take_snapshot)
echo "$SNAPSHOT"

# 2. Find element UID in snapshot output
# Example: uid=12 input type="email"

# 3. Interact with element using its UID
mise x node@20 -- mcporter call chrome-devtools.fill --args '{"uid":"12","value":"[email protected]"}'
mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"15"}'

スクリーンショットのワークフロー

# Take viewport screenshot
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

# Take full-page screenshot
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./full.png","fullPage":true}'

# Screenshot specific element
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"uid":"20","filePath":"./button.png"}'

JavaScript エラーのデバッグ

# Check console for errors
mise x node@20 -- mcporter call chrome-devtools.list_console_messages --args '{"types":["error","warn"]}'

# Check network requests
mise x node@20 -- mcporter call chrome-devtools.list_network_requests --args '{"types":["fetch","xhr"]}'

パフォーマンステストの実行

# Execute JavaScript to get performance metrics
mise x node@20 -- mcporter call chrome-devtools.evaluate_script \
  --args '{"function":"() => { const perf = performance.getEntriesByType(\"navigation\")[0]; return { loadTime: perf.loadEventEnd - perf.fetchStart, domInteractive: perf.domInteractive - perf.fetchStart }; }"}'

重要な注意事項

UID を使ったワークフローは必須です

# ❌ WRONG - CSS selectors don't work
mise x node@20 -- mcporter call chrome-devtools.click --selector "#login-button"

# ✅ CORRECT - Use UIDs from snapshot
mise x node@20 -- mcporter call chrome-devtools.take_snapshot  # Get UIDs first
mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"12"}'

UID はページ遷移時に期限切れになります

# After navigation, UIDs are invalid
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"url","url":"..."}'

# Take fresh snapshot to get new UIDs
mise x node@20 -- mcporter call chrome-devtools.take_snapshot

必ず JSON とともに --args を使用してください

# ❌ WRONG - Individual flags don't work
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --file-path "./screen.png"

# ✅ CORRECT - Use --args with JSON
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

トラブルシューティング（クイックガイド）

エラー	解決策
"Element not found" / "Invalid UID"	新しいスナップショットを取得します：take_snapshot
"No page selected"	ページを選択します：select_page --args '{"pageIdx":0}'
"Connection refused"	Chrome を起動します：google-chrome --remote-debugging-port=9222
スクリーンショットが作成されない	ディレクトリが存在することを確認し、--args 形式を使用します
UID が機能しない	UID はページ遷移後に期限切れになります。新しいスナップショットを取得してください

追加リソース

必要に応じて、これらのリファレンスを遅延読み込みしてください：

リファレンス	使用する場面
要素の操作	UID の使用、要素のクリックやホバー、測定を行う場合
フォーム入力	フォームへの入力、データの送信、キーボード入力の処理を行う場合
スクリーンショット	スクリーンショットの撮影、ビジュアルテスト、状態の記録を行う場合
パフォーマンス	ページのパフォーマンスやネットワークのタイミングを測定したり、条件をエミュレートしたりする場合
デバッグ	コンソールエラー、ネットワーク障害、スクリプトの評価を調査する場合
ナビゲーション	ページ間の移動、タブの管理、ビューポートの処理を行う場合
トラブルシューティング	エラーや予期しない動作に遭遇した場合

重要

必要なときだけリファレンスを読み込んでください - すべてのファイルを最初から読まないでください。現在のタスクに合った特定のリファレンスを読んでください。

実際の効果

Chrome DevTools Protocol を統合すると、次のことが可能になります：

• エージェントとの会話と並行した、ブラウザーのリアルタイムデバッグ
• フォーム入力と操作テストの自動化
• アプリケーションの動作に関する視覚的なフィードバック
• コンソールログからの即時のエラー診断
• スクリーンショットに基づく検証ワークフロー

この統合がない場合、ウェブアプリケーションのデバッグには、ブラウザーとエージェントの間で頻繁にコンテキストを切り替える必要があります。