browser-tools

ブラウザツール

エージェントによるウェブ自動化のための Chrome DevTools Protocol ツールです。リモートデバッグを有効にして :9222 で実行中の Chrome に接続します。

セットアップ

初回使用前に一度実行します。

cd {baseDir}/browser-tools
npm install

Chrome の起動

{baseDir}/browser-start.js              # Fresh profile
{baseDir}/browser-start.js --profile    # Copy user's profile (cookies, logins)

リモートデバッグを有効にして、:9222 で Chrome を起動します。ユーザーの認証状態を保持するには --profile を使用します。

移動

{baseDir}/browser-nav.js https://example.com
{baseDir}/browser-nav.js https://example.com --new

URL に移動します。現在のタブを再利用せず、新しいタブで開くには --new フラグを使用します。

JavaScript の評価

{baseDir}/browser-eval.js 'document.title'
{baseDir}/browser-eval.js 'document.querySelectorAll("a").length'

アクティブなタブで JavaScript を実行します。コードは非同期コンテキストで実行されます。データの抽出、ページ状態の確認、プログラムによる DOM 操作に使用します。

スクリーンショット

{baseDir}/browser-screenshot.js

現在のビューポートをキャプチャし、一時ファイルのパスを返します。これを使ってページの状態を視覚的に確認したり、UI の変更を検証したりできます。

要素の選択

{baseDir}/browser-pick.js "Click the submit button"

重要：ユーザーがページ上の特定の DOM 要素を選択したい場合に、このツールを使用します。要素をクリックして選択できるインタラクティブなピッカーが起動します。ユーザーは複数の要素を選択し（Cmd/Ctrl+クリック）、完了したら Enter キーを押せます。このツールは、選択した要素の CSS セレクターを返します。

よくある使用例：

• ユーザーが「このボタンをクリックしたい」と言った場合 → このツールを使って選択できるようにします
• ユーザーが「これらの項目からデータを抽出して」と言った場合 → このツールを使って要素を選択できるようにします
• ページ構造が複雑または曖昧で、特定のセレクターが必要な場合

Cookie

{baseDir}/browser-cookies.js

現在のタブのすべての Cookie を、ドメイン、パス、httpOnly、secure フラグを含めて表示します。認証の問題のデバッグや、セッション状態の確認に使用します。

ページコンテンツの抽出

{baseDir}/browser-content.js https://example.com

URL に移動し、読み取り可能なコンテンツを Markdown として抽出します。記事の抽出には Mozilla Readability を、HTML から Markdown への変換には Turndown を使用します。JavaScript を含むページでも動作します（ページの読み込みを待機します）。

使用する場面

• 実際のブラウザーでフロントエンドコードをテストする場合
• JavaScript が必要なページを操作する場合
• ユーザーがページを視覚的に確認したり、操作したりする必要がある場合
• 認証やセッションの問題をデバッグする場合
• JavaScript の実行が必要な動的コンテンツをスクレイピングする場合

---

効率化ガイド

スクリーンショットより DOM の確認

避けてください：ページの状態を確認するためにスクリーンショットを撮ること。代わりに：DOM を直接解析します。

// Get page structure
document.body.innerHTML.slice(0, 5000)

// Find interactive elements
Array.from(document.querySelectorAll('button, input, [role="button"]')).map(e => ({
  id: e.id,
  text: e.textContent.trim(),
  class: e.className
}))

複雑なスクリプトを単一の呼び出しにまとめる

複数の文からなるコードを実行するには、すべてを IIFE で囲みます。

(function() {
  // Multiple operations
  const data = document.querySelector('#target').textContent;
  const buttons = document.querySelectorAll('button');
  
  // Interactions
  buttons[0].click();
  
  // Return results
  return JSON.stringify({ data, buttonCount: buttons.length });
})()

操作の一括実行

避けてください：クリックごとに個別の呼び出しを行うこと。代わりに：まとめて実行します。

(function() {
  const actions = ["btn1", "btn2", "btn3"];
  actions.forEach(id => document.getElementById(id).click());
  return "Done";
})()

入力シーケンス

(function() {
  const text = "HELLO";
  for (const char of text) {
    document.getElementById("key-" + char).click();
  }
  document.getElementById("submit").click();
  return "Submitted: " + text;
})()

アプリやゲームの状態の読み取り

構造化された状態を一度の呼び出しで抽出します。

(function() {
  const state = {
    score: document.querySelector('.score')?.textContent,
    status: document.querySelector('.status')?.className,
    items: Array.from(document.querySelectorAll('.item')).map(el => ({
      text: el.textContent,
      active: el.classList.contains('active')
    }))
  };
  return JSON.stringify(state, null, 2);
})()

更新の待機

操作後に DOM が更新される場合は、bash を使って短い遅延を追加します。

sleep 0.5 && {baseDir}/browser-eval.js '...'

操作の前に調査する

まず、ページの構造を把握します。

(function() {
  return {
    title: document.title,
    forms: document.forms.length,
    buttons: document.querySelectorAll('button').length,
    inputs: document.querySelectorAll('input').length,
    mainContent: document.body.innerHTML.slice(0, 3000)
  };
})()

次に、確認した内容に基づいて特定の要素を対象にします。