test-browser

ブラウザテストスキル

agent-browser CLI を使用して、PR またはブランチの変更によって影響を受けるページのエンドツーエンドブラウザテストを実行します。

ブラウザ自動化には agent-browser のみを使用

このワークフローでは、agent-browser CLI のみを使用します。代替のブラウザ自動化システム、ブラウザ MCP 統合、組み込みのブラウザー操作ツールは使用しないでください。プラットフォームにブラウザー操作方法が複数ある場合は、必ず agent-browser を選択してください。

ページを開く、要素をクリックする、フォームに入力する、スクリーンショットを撮る、レンダリングされたコンテンツをスクレイピングする場合は、agent-browser を使用します。

プラットフォーム固有のヒント：

• Claude Code では、Chrome MCP ツール（mcp__claude-in-chrome__*）を使用しないでください。
• Codex では、無関係なブラウジングツールで代用しないでください。

前提条件

• ローカル開発サーバーが実行中であること（例：bin/dev、rails server、npm run dev）
• agent-browser CLI がインストールされていること（セットアップについては下記を参照）
• テストする変更がある Git リポジトリ

セットアップ

agent-browser がインストールされているか確認します：

command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"

インストールされていない場合は、ユーザーに次のように伝えます：「agent-browser がインストールされていません。必要な依存関係をインストールするには /ce-setup を実行してください。」その後、停止します。このスキルは agent-browser がないと機能しません。

ワークフロー

1. インストールを確認する

開始前に、agent-browser が利用可能であることを確認します：

command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED"

インストールされていない場合は、ユーザーに次のように伝えます：「agent-browser がインストールされていません。必要な依存関係をインストールするには /ce-setup を実行してください。」その後、停止します。

2. ブラウザモードを尋ねる

ヘッドありまたはヘッドレスのどちらで実行するかをユーザーに尋ねます（プラットフォームの質問ツールを使用します。例：Claude Code の AskUserQuestion、Codex の request_user_input、Gemini の ask_user。または選択肢を提示して返信を待ちます）：

Do you want to watch the browser tests run?

1. Headed (watch) - Opens visible browser window so you can see tests run
2. Headless (faster) - Runs in background, faster but invisible

選択内容を保存し、ユーザーがオプション 1 を選択した場合は --headed フラグを使用します。

3. テスト範囲を決定する

PR 番号が指定されている場合：

gh pr view [number] --json files -q '.files[].path'

current または空の場合：

git diff --name-only main...HEAD

ブランチ名が指定されている場合：

git diff --name-only main...[branch]

4. ファイルをルートに対応付ける

変更されたファイルをテスト可能なルートに対応付けます：

ファイルパターン	ルート
app/views/users/*	/users、/users/:id、/users/new
app/controllers/settings_controller.rb	/settings
app/javascript/controllers/*_controller.js	該当の Stimulus コントローラーを使用するページ
app/components/*_component.rb	該当のコンポーネントをレンダリングするページ
app/views/layouts/*	すべてのページ（最低限、ホームページをテスト）
app/assets/stylesheets/*	主要ページでのビジュアルリグレッション
app/helpers/*_helper.rb	該当のヘルパーを使用するページ
src/app/* (Next.js)	対応するルート
src/components/*	該当のコンポーネントを使用するページ

この対応付けに基づいて、テストする URL の一覧を作成します。

5. 開発サーバーのポートを検出する

次の優先順位で開発サーバーのポートを決定します：

1. 明示的な引数 — ユーザーが --port 5000 を渡した場合は、その値を直接使用します
2. プロジェクトの指示 — AGENTS.md、CLAUDE.md、またはその他の指示ファイルでポートに関する記述を確認します
3. package.json — dev/start スクリプトに --port フラグがあるか確認します
4. 環境ファイル — .env、.env.local、.env.development で PORT= を確認します
5. デフォルト — 該当しない場合は 3000 を使用します

PORT="${EXPLICIT_PORT:-}"
if [ -z "$PORT" ]; then
  PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' AGENTS.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
  if [ -z "$PORT" ]; then
    PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' CLAUDE.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
  fi
fi
if [ -z "$PORT" ]; then
  PORT=$(grep -Eo '\-\-port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
fi
if [ -z "$PORT" ]; then
  PORT=$(grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2)
fi
PORT="${PORT:-3000}"
echo "Using dev server port: $PORT"

6. サーバーが実行中であることを確認する

agent-browser open http://localhost:${PORT}
agent-browser snapshot -i

サーバーが実行されていない場合は、ユーザーに次のように伝えます：

Server not running on port ${PORT}

Please start your development server:
- Rails: `bin/dev` or `rails server`
- Node/Next.js: `npm run dev`
- Custom port: run this skill again with `--port <your-port>`

Then re-run this skill.

7. 影響を受ける各ページをテストする

影響を受けるルートごとに：

ページに移動してスナップショットを取得：

agent-browser open "http://localhost:${PORT}/[route]"
agent-browser snapshot -i

ヘッドありモードの場合：

agent-browser --headed open "http://localhost:${PORT}/[route]"
agent-browser --headed snapshot -i

主要な要素を確認：

• agent-browser snapshot -i を使用して、ref 付きのインタラクティブ要素を取得します
• ページタイトル／見出しが表示されていること
• 主要コンテンツがレンダリングされていること
• エラーメッセージが表示されていないこと
• フォームに想定されるフィールドがあること

重要な操作をテスト：

agent-browser click @e1
agent-browser snapshot -i

スクリーンショットを撮影：

agent-browser screenshot page-name.png
agent-browser screenshot --full page-name-full.png

8. 人による確認（必要な場合）

テストで外部とのやり取りが必要なフローに触れる場合は、人による入力を求めて一時停止してください。

フローの種類	確認する内容
OAuth	「[provider] でサインインして、動作することを確認してください」
メール	「受信トレイでテストメールを確認し、届いていることを確認してください」
支払い	「サンドボックスモードでテスト購入を完了してください」
SMS	「SMS コードを受信したことを確認してください」
外部 API	「[service] との連携が動作していることを確認してください」

ユーザーに質問してください（プラットフォームの質問ツールを使うか、番号付きの選択肢を提示して回答を待ちます）。

Human Verification Needed

This test touches [flow type]. Please:
1. [Action to take]
2. [What to verify]

Did it work correctly?
1. Yes - continue testing
2. No - describe the issue

9. 失敗への対処

テストが失敗した場合：

1. 失敗を記録します。

   • エラー状態のスクリーンショットを撮ります：agent-browser screenshot error.png
   • 正確な再現手順を記録します

2. 次の対応をユーザーに尋ねます。

   Test Failed: [route]
   
   Issue: [description]
   Console errors: [if any]
   
   How to proceed?
   1. Fix now - I'll help debug and fix
   2. Create todo - Add a todo for later (using the todo-create skill)
   3. Skip - Continue testing other pages
   

3. **「今すぐ修正」の場合：**調査し、修正を提案して適用し、失敗したテストを再実行します

4. 「ToDo を作成」の場合：todo-create スキルを読み込み、優先度 p1、説明 browser-test-{description} で ToDo を作成し、続行します

5. **「スキップ」の場合：**スキップとして記録し、続行します

10. テスト概要

すべてのテストが完了したら、概要を提示します。

## Browser Test Results

**Test Scope:** PR #[number] / [branch name]
**Server:** http://localhost:${PORT}

### Pages Tested: [count]

| Route | Status | Notes |
|-------|--------|-------|
| `/users` | Pass | |
| `/settings` | Pass | |
| `/dashboard` | Fail | Console error: [msg] |
| `/checkout` | Skip | Requires payment credentials |

### Console Errors: [count]
- [List any errors found]

### Human Verifications: [count]
- OAuth flow: Confirmed
- Email delivery: Confirmed

### Failures: [count]
- `/dashboard` - [issue description]

### Created Todos: [count]
- `005-pending-p1-browser-test-dashboard-error.md`

### Result: [PASS / FAIL / PARTIAL]

使用例

# Test current branch changes (auto-detects port)
/test-browser

# Test specific PR
/test-browser 847

# Test specific branch
/test-browser feature/new-dashboard

# Test on a specific port
/test-browser --port 5000

agent-browser CLI リファレンス

すべてのコマンドを確認するには、agent-browser --help を実行してください。

主なコマンド：

# Navigation
agent-browser open <url>           # Navigate to URL
agent-browser back                 # Go back
agent-browser close                # Close browser

# Snapshots (get element refs)
agent-browser snapshot -i          # Interactive elements with refs (@e1, @e2, etc.)
agent-browser snapshot -i --json   # JSON output

# Interactions (use refs from snapshot)
agent-browser click @e1            # Click element
agent-browser fill @e1 "text"      # Fill input
agent-browser type @e1 "text"      # Type without clearing
agent-browser press Enter          # Press key

# Screenshots
agent-browser screenshot out.png       # Viewport screenshot
agent-browser screenshot --full out.png # Full page screenshot

# Headed mode (visible browser)
agent-browser --headed open <url>      # Open with visible browser
agent-browser --headed click @e1       # Click in visible browser

# Wait
agent-browser wait @e1             # Wait for element
agent-browser wait 2000            # Wait milliseconds