chrome-devtools

Chrome DevTools Agent Skill

実行可能な Puppeteer スクリプトによるブラウザー自動化です。すべてのスクリプトは、解析しやすいように JSON を出力します。

クイックスタート

重要：スクリプトを実行する前に、必ず pwd を確認してください。

インストール

ステップ 1：システムの依存関係をインストールする（Linux/WSL のみ）

Linux/WSL では、Chrome にシステムライブラリが必要です。まずインストールしてください。

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
./install-deps.sh  # Auto-detects OS and installs required libs

対応環境：Ubuntu、Debian、Fedora、RHEL、CentOS、Arch、Manjaro

macOS/Windows：依存関係は Chrome にバンドルされているため、この手順は省略してください。

ステップ 2：Node の依存関係をインストールする

npm install  # Installs puppeteer, debug, yargs

ステップ 3：ImageMagick をインストールする（任意、推奨）

ImageMagick を使用すると、ファイルサイズが 5MB 未満になるようにスクリーンショットを自動圧縮できます。

macOS：

brew install imagemagick

Ubuntu/Debian/WSL：

sudo apt-get install imagemagick

確認：

magick -version  # or: convert -version

ImageMagick がない場合、5MB を超えるスクリーンショットは圧縮されません（Gemini/Claude で読み込めない場合があります）。

テスト

node navigate.js --url https://example.com
# Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}

利用可能なスクリプト

すべてのスクリプトは .claude/skills/chrome-devtools/scripts/ にあります。

重要：スクリプトを実行する前に、必ず pwd を確認してください。

スクリプトの使い方

• ./scripts/README.md

コア自動化

• navigate.js - URL に移動します
• screenshot.js - スクリーンショットを撮影します（ページ全体または要素）
• click.js - 要素をクリックします
• fill.js - フォームフィールドに入力します
• evaluate.js - ページのコンテキストで JavaScript を実行します

分析とモニタリング

• snapshot.js - インタラクティブ要素をメタデータとともに抽出します
• console.js - コンソールのメッセージやエラーをモニタリングします
• network.js - HTTP リクエスト／レスポンスを追跡します
• performance.js - Core Web Vitals を測定し、トレースを記録します

使用パターン

単一コマンド

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
node screenshot.js --url https://example.com --output ./docs/screenshots/page.png

重要：スクリーンショットは必ず ./docs/screenshots ディレクトリに保存してください。

画像の自動圧縮

Gemini API と Claude Code（どちらも上限は 5MB）との互換性を確保するため、スクリーンショットが 5MB を超える場合は自動的に圧縮されます。内部では ImageMagick を使用します。

# Default: auto-compress if >5MB
node screenshot.js --url https://example.com --output page.png

# Custom size threshold (e.g., 3MB)
node screenshot.js --url https://example.com --output page.png --max-size 3

# Disable compression
node screenshot.js --url https://example.com --output page.png --no-compress

圧縮の動作：

• PNG：90% にリサイズし、品質を 85 に設定します（それでも大きすぎる場合は 75% にリサイズし、品質を 70 に設定します）
• JPEG：品質を 80 に設定し、プログレッシブエンコーディングを適用します（それでも大きすぎる場合は品質を 60 に設定します）
• その他の形式：圧縮して JPEG に変換します
• ImageMagick のインストールが必要です（imagemagick スキルを参照）

出力には圧縮情報が含まれます：

{
  "success": true,
  "output": "/path/to/page.png",
  "compressed": true,
  "originalSize": 8388608,
  "size": 3145728,
  "compressionRatio": "62.50%",
  "url": "https://example.com"
}

コマンドの連結（ブラウザーを再利用）

# Keep browser open with --close false
node navigate.js --url https://example.com/login --close false
node fill.js --selector "#email" --value "[email protected]" --close false
node fill.js --selector "#password" --value "secret" --close false
node click.js --selector "button[type=submit]"

JSON 出力の解析

# Extract specific fields with jq
node performance.js --url https://example.com | jq '.vitals.LCP'

# Save to file
node network.js --url https://example.com --output /tmp/requests.json

実行プロトコル

作業ディレクトリの確認

スクリプトを実行する前に：

1. pwd で現在の作業ディレクトリを確認します
2. .claude/skills/chrome-devtools/scripts/ ディレクトリにいることを確認します
3. ディレクトリが違う場合は、正しい場所に cd します
4. すべての出力ファイルに絶対パスを使用します

例：

pwd  # Should show: .../chrome-devtools/scripts
# If wrong:
cd .claude/skills/chrome-devtools/scripts

出力の検証

スクリーンショット／キャプチャ操作の実行後に：

1. ls -lh <output-path> でファイルが作成されたことを確認します
2. Read ツールでスクリーンショットを読み込み、内容を確認します
3. JSON 出力で success:true を確認します
4. ファイルサイズと圧縮の状態を報告します

例：

node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # Verify file exists
# Then use Read tool to visually inspect

5. 作業ディレクトリをプロジェクトルートに戻します。

エラーからの復旧

スクリプトが失敗した場合：

1. エラーメッセージでセレクターの問題を確認します
2. snapshot.js を使用して正しいセレクターを見つけます
3. CSS セレクターが失敗した場合は、XPath セレクターを試します
4. 要素が表示され、操作可能であることを確認します

例：

# CSS selector fails
node click.js --url https://example.com --selector ".btn-submit"
# Error: waiting for selector ".btn-submit" failed

# Discover correct selector
node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

# Try XPath
node click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"

よくある間違い

❌ 作業ディレクトリが間違っている → 出力ファイルが誤った場所に保存されます
❌ 出力の検証を省略する → 気づかないまま失敗します
❌ テストせずに複雑な CSS セレクターを使う → セレクターエラーが発生します
❌ 要素の表示状態を確認しない → タイムアウトエラーが発生します

✅ スクリプトを実行する前に、必ず pwd を確認します
✅ スクリーンショットを撮影した後は、必ず出力を検証します
✅ snapshot.js を使用してセレクターを見つけます
✅ まず簡単なコマンドでセレクターをテストします

よくあるワークフロー

ウェブスクレイピング

node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent,
    link: el.querySelector('a')?.href
  }))
" | jq '.result'

パフォーマンステスト

PERF=$(node performance.js --url https://example.com)
LCP=$(echo $PERF | jq '.vitals.LCP')
if (( $(echo "$LCP < 2500" | bc -l) )); then
  echo "✓ LCP passed: ${LCP}ms"
else
  echo "✗ LCP failed: ${LCP}ms"
fi

フォームの自動化

node fill.js --url https://example.com --selector "#search" --value "query" --close false
node click.js --selector "button[type=submit]"

エラーのモニタリング

node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'

スクリプトのオプション

すべてのスクリプトで、以下のオプションを使用できます。

• --headless false - ブラウザーウィンドウを表示します
• --close false - 後続の処理で使えるよう、ブラウザーを開いたままにします
• --timeout 30000 - タイムアウトを設定します（ミリ秒）
• --wait-until networkidle2 - 待機方法を指定します

オプションの詳細については、./scripts/README.md を参照してください。

出力形式

すべてのスクリプトは、標準出力に JSON を出力します。

{
  "success": true,
  "url": "https://example.com",
  ... // script-specific data
}

エラーは標準エラー出力に出力されます。

{
  "success": false,
  "error": "Error message"
}

要素の検索

snapshot.js を使用して、セレクターを確認してください。

node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'

トラブルシューティング

よくあるエラー

"Cannot find package 'puppeteer'"

• scripts ディレクトリで npm install を実行します

"error while loading shared libraries: libnss3.so"（Linux/WSL）

• システム依存関係が不足しています
• 解決方法：scripts ディレクトリで ./install-deps.sh を実行します
• 手動でインストールする場合：sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1

"Failed to launch the browser process"

• システム依存関係がインストールされていることを確認します（Linux/WSL）
• Chrome がダウンロードされていることを確認します：ls ~/.cache/puppeteer
• npm rebuild を実行してから、npm install を試します

Chrome が見つからない

• Puppeteer は npm install の実行時に Chrome を自動ダウンロードします
• ダウンロードに失敗した場合は、手動で次のコマンドを実行します：npx puppeteer browsers install chrome

スクリプトの問題

要素が見つからない

• まずスナップショットを取得し、正しいセレクターを確認します：node snapshot.js --url <url>

スクリプトが停止しない

• タイムアウトを延長します：--timeout 60000
• 待機方法を変更します：--wait-until load または --wait-until domcontentloaded

スクリーンショットが真っ白

• ページの読み込みを待ちます：--wait-until networkidle2
• タイムアウトを延長します：--timeout 30000

スクリプトの実行が拒否される

• 実行可能にします：chmod +x *.sh

スクリーンショットのサイズが大きすぎる（>5MB）

• 自動圧縮するには ImageMagick をインストールします
• しきい値を手動で下げます：--max-size 3
• PNG ではなく JPEG 形式を使用します：--format jpeg --quality 80
• ページ全体ではなく、特定の要素をキャプチャします：--selector .main-content

圧縮が機能しない

• ImageMagick がインストールされていることを確認します：magick -version または convert -version
• 出力 JSON で実際に圧縮されたことを確認します："compressed": true
• ページが非常に大きい場合は、--selector を使用して必要な範囲だけをキャプチャします

リファレンスドキュメント

詳細なガイドは ./references/ にあります。

• CDP ドメインのリファレンス - Chrome DevTools Protocol の 47 個のドメイン
• Puppeteer クイックリファレンス - Puppeteer API の完全なパターン集
• パフォーマンス分析ガイド - Core Web Vitals の最適化

高度な使い方

カスタムスクリプト

共有ライブラリを使ってカスタムスクリプトを作成します。

import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
// Your automation logic

CDP への直接アクセス

const client = await page.createCDPSession();
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });

高度なパターンと API の全容については、リファレンスドキュメントを参照してください。

外部リソース

• Puppeteer ドキュメント
• Chrome DevTools Protocol
• スクリプトの README