chrome-devtools

Chrome DevTools エージェントスキル

実行可能な 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

Windows：

# Option 1: Chocolatey (recommended)
choco install imagemagick

# Option 2: Scoop
scoop install imagemagick

# Option 3: WinGet
winget install ImageMagick.ImageMagick

# Option 4: Manual download from https://imagemagick.org/script/download.php#windows

Fedora/RHEL/CentOS：

sudo dnf install ImageMagick
# or for older versions:
sudo yum install ImageMagick

Arch/Manjaro：

sudo pacman -S imagemagick

インストールを確認する：

# Linux/macOS:
magick -version  # or: convert -version

# Windows:
magick -version
# or: magick.exe -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 Domains Reference - Chrome DevTools Protocolの47のドメイン
• Puppeteer Quick Reference - Puppeteer APIの使用パターンの完全版
• Performance Analysis Guide - 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 Documentation
• Chrome DevTools Protocol
• Scripts README