Chrome Debug

概要

このスキルは、Chrome DevTools Protocol (CDP)を使用した自動Chrome ブラウザ制御により、Webアプリケーションのデバッグを実現します。chromectl.py を使用してChrome インスタンスの起動、ページの検査、コンソール出力の監視、JavaScriptの実行、スクリーンショットの取得をすべてコマンドラインから行えます。

このスキルは協調的デバッグ(開発者とClaudeが一緒に作業する可視Chrome ウィンドウ)と自動デバッグ(スクリーンショット/コンソール取得用のヘッドレスバックグラウンドプロセス)の両方をサポートしています。

このスキルを使用する場合

以下の場合にこのスキルを使用します:

• Webアプリケーションの問題をデバッグするか、ページエラーを調査する
• ブラウザコンソルでエラー、警告、またはログメッセージを検査する
• ページのスクリーンショットを取得して視覚的な問題を特定する
• 開発中のページの動作をリアルタイムで監視する
• ページ検査やテストワークフローを自動化する
• JavaScriptエラーまたは予期しないページ動作を診断する

このスキルを使用しない場合:

• 一般的なWeb閲覧または情報収集(WebFetchを使用してください)
• HTML/CSSファイルの直接編集(これはランタイム検査のみです)
• 高度なユーザーインタラクションが必要なテスト(適切なテストフレームワークを使用してください)

重要: ヘッドフル vs ヘッドレスモード

協調的デバッグか自動化が必要かを常に考慮してください:

ヘッドフルモード(デフォルト - --headless フラグなし)

scripts/chromectl.py start

使用する場合:

• 開発者がブラウザを見て操作できる協調的デバッグ
• 手動検査が必要な視覚的な問題の調査
• 開発者入力が必要な複雑なワークフロー
• リアルタイムトラブルシューティングセッション

メリット:

• 開発者が手動で操作しながらClaudeがコンソール/状態を監視できる
• 開発者とClaudeの両者に視覚的フィードバックがある
• UI/レイアウトの問題を一緒に診断しやすい

ヘッドレスモード(--headless フラグ)

scripts/chromectl.py start --headless

使用する場合:

• スクリーンショットの自動取得
• ユーザーインタラクションなしでコンソール監視する
• 複数ページのバッチ処理
• CI/CDまたはスクリプト化されたテストシナリオ

メリット:

• 視覚的なウィンドウがなく、バックグラウンドで実行
• より高速で軽量
• 自動化に適している

デフォルトの選択: 自動化が明示的に必要でない限り、協調的デバッグにはヘッドフルモードを使用してください。

デバッグワークフロー

ワークフロー1: 協調的Webアプリケーションデバッグ

開発者がエラーや予期しない動作を報告し、一緒に作業する場合に使用します。

# 1. 可視ウィンドウでChromedを起動
scripts/chromectl.py start

# 2. 問題のあるページを開く
TARGET=$(scripts/chromectl.py open https://myapp.com/problem-page | jq -r .id)

# 3. バックグラウンドでコンソル監視を開始
scripts/chromectl.py console-tail --id $TARGET --for 60 &

# 4. 初期スクリーンショットを取得
scripts/chromectl.py screenshot --id $TARGET -o initial-state.png

# 5. evalを使用してページ状態を検査
scripts/chromectl.py eval --id $TARGET -e "document.readyState"
scripts/chromectl.py eval --id $TARGET -e "({
  title: document.title,
  errors: window.onerror ? 'Error handler present' : 'No error handler',
  scripts: document.scripts.length
})"

# 6. 開発者がページと対話でき、Claudeがコンソール出力を監視します
# Claudeがコンソール出力のエラーを監視しながら、開発者がクリック/ナビゲート

# 7. 完了時にクリーンアップ
scripts/chromectl.py stop

ワークフロー2: 自動スクリーンショット・コンソールキャプチャ

協調なしで迅速に自動検査する場合に使用します。

# 1. ヘッドレスChromedを起動
scripts/chromectl.py start --headless

# 2. ページを開く
TARGET=$(scripts/chromectl.py open https://example.com | jq -r .id)

# 3. ページロードを待つ
sleep 2

# 4. 全ページスクリーンショットを取得
scripts/chromectl.py screenshot --id $TARGET -o page.png --full-page

# 5. evalでJavaScriptエラーをチェック
scripts/chromectl.py eval --id $TARGET -e "({
  title: document.title,
  url: location.href,
  readyState: document.readyState,
  hasErrors: typeof window.onerror !== 'undefined'
})"

# 6. Chromeを停止
scripts/chromectl.py stop

ワークフロー3: コンソールエラー監視

断続的なエラーを調査したり、ページアクティビティを監視する場合に使用します。

# 1. Chromedを起動(開発者が操作したい場合はヘッドフル)
scripts/chromectl.py start

# 2. ターゲットページを開く
TARGET=$(scripts/chromectl.py open https://myapp.com | jq -r .id)

# 3. 長期間のコンソル監視を開始
scripts/chromectl.py console-tail --id $TARGET --for 120 > console-output.log &
TAIL_PID=$!

# 4. コンソル監視中にアクションをトリガー、または開発者が操作
# 開発者はボタンをクリックしたり、ナビゲートしたりでき、Claudeが監視

# 5. 監視完了を待つ
wait $TAIL_PID

# 6. console-output.logでエラー/警告を分析
grep -E '"console": "(error|warning)"' console-output.log

# 7. クリーンアップ
scripts/chromectl.py stop

ワークフロー4: 複数ページ比較

複数ページまたは環境全体で動作を比較する場合に使用します。

# 1. Chromedを起動
scripts/chromectl.py start --headless

# 2. 複数ページを開く
PROD=$(scripts/chromectl.py open https://app.com/page | jq -r .id)
STAGING=$(scripts/chromectl.py open https://staging.app.com/page | jq -r .id)

# 3. ロード完了を待つ
sleep 3

# 4. スクリーンショットを取得
scripts/chromectl.py screenshot --id $PROD -o prod.png
scripts/chromectl.py screenshot --id $STAGING -o staging.png

# 5. ページ状態を比較
scripts/chromectl.py eval --id $PROD -e "document.querySelector('h1').innerText"
scripts/chromectl.py eval --id $STAGING -e "document.querySelector('h1').innerText"

# 6. クリーンアップ
scripts/chromectl.py stop

デバッグ用JavaScript評価

evalコマンドは主にClaudeが暗黙的にページ状態を検査・デバッグするために使用します。以下のために使用します:

ページ状態を検査:

# ページがロードされたかチェック
eval --id $ID -e "document.readyState"

# ページタイトルとURLを取得
eval --id $ID -e "({title: document.title, url: location.href})"

# グローバル変数をチェック
eval --id $ID -e "typeof myAppVariable"

# DOMエレメントを検査
eval --id $ID -e "document.querySelector('#error-message')?.innerText"

JavaScript関数をデバッグ:

# 関数が存在するかチェック
eval --id $ID -e "typeof myFunction"

# 関数を呼び出して結果を検査
eval --id $ID -e "myFunction(testData)"

# オブジェクトプロパティを検査
eval --id $ID -e "window.myApp.config"

ページアクション(デバッグ用)をトリガー:

# エレメントをクリックしてエラーを再現
eval --id $ID -e "document.querySelector('button#submit').click()"

# ページ下部までスクロール
eval --id $ID -e "window.scrollTo(0, document.body.scrollHeight)"

# フォームフィールドに入力
eval --id $ID -e "document.querySelector('input#email').value = 'test@example.com'"

注: 評価はPromiseを自動的にサポートしているため、非同期操作がシームレスに動作します。

重要なリマインダー

終了時は必ずChromedを停止してください

scripts/chromectl.py stop

重要: ヘッドレスChrome インスタンスは見えない状態で実行され、通常のChromedの起動を妨げることができます。デバッグセッションの終了時に必ずstopを実行してください。

Console-Tail は新しいメッセージのみをキャプチャ

console-tailコマンドは、コマンド開始後に発生するコンソルメッセージのみをキャプチャします。過去のメッセージは表示されません。

効果的なコンソル監視パターン:

# 監視を最初に開始
scripts/chromectl.py console-tail --id $TARGET --for 30 &

# その後、コンソル出力を生成するアクションをトリガー
scripts/chromectl.py eval --id $TARGET -e "myFunction()"

複数のChrome インスタンス

異なるポートで複数のデバッグインスタンスを実行できます:

# インスタンス1
scripts/chromectl.py start --port 9222

# インスタンス2(異なるポートとプロファイル)
scripts/chromectl.py start --port 9223 --user-data-dir ~/chromectl-debug2

# インスタンス2を使用
scripts/chromectl.py --port 9223 list

ターゲットIDを抽出

ターゲットIDは eval, screenshot, console-tail コマンドに必要です:

# openコマンドからIDを抽出
TARGET=$(scripts/chromectl.py open https://example.com | jq -r .id)

# またはすべてのターゲットをリスト化して手動選択
scripts/chromectl.py list

リソース

scripts/chromectl.py

メインのChromeデバッグユーティリティです。uv(aiohttp)を使用した依存関係管理を行う自己完結型Pythonスクリプトです。DevTools Protocolを介してChromedと通信します。

スキルディレクトリから実行:

scripts/chromectl.py <command> [options]

references/chromectl-reference.md

すべてのオプション、例、トラブルシューティングガイダンスを含む完全なコマンドリファレンスです。以下の場合に参照してください:

• 詳細なコマンド構文
• 高度な使用パターン
• 接続の問題のトラブルシューティング
• CDPの技術詳細

クイックリファレンス

一般的なコマンドパターン:

# デバッグセッションを開始
scripts/chromectl.py start                    # 可視ウィンドウ(協調的)
scripts/chromectl.py start --headless         # バックグラウンド(自動化)

# ターゲットIDを取得
TARGET=$(scripts/chromectl.py open URL | jq -r .id)

# コンソルを監視
scripts/chromectl.py console-tail --id $TARGET --for 30

# スクリーンショットを取得
scripts/chromectl.py screenshot --id $TARGET -o file.png

# ページ状態を検査
scripts/chromectl.py eval --id $TARGET -e "expression"

# 必ずクリーンアップ
scripts/chromectl.py stop

トラブルシューティング:

# Chromedが実行中か確認
lsof -i :9222

# すべてのターゲットをリスト
scripts/chromectl.py list

# CDP接続をテスト
curl http://localhost:9222/json