UI Test — Agentic UI Testing Skill

実ブラウザで UI 変更をテストします。あなたの仕事は 問題を見つけることであり、それが機能することを確認することではありません。

3 つのワークフロー:

• 差分駆動型 — git diff を分析し、変更した部分のみテスト
• 探索的テスト — アプリを操作し、開発者が考えなかったバグを検出
• 並列実行 — 複数の Browserbase ブラウザで独立したテストグループを分散実行

テストの仕組み

メインエージェントが 調整役 となり、テスト戦略を計画し、サブエージェントに委任し、結果をマージします。サブエージェントが実際のブラウザテストを実行します。

計画: 複数の観点から検討して実行

3 つの計画ラウンドすべてを自分自身で完了し、サブエージェントを起動する前に出力する必要があります。 計画はあなたの応答内で実施されます。サブエージェントに委任されません。実行段階をスキップしないでください。

ラウンド 1 — 機能: コアユーザーフローは何ですか? 何が機能すべきですか? 各テストを以下のように記述してください: 操作 → 期待される結果。

ラウンド 2 — 敵対的テスト: ラウンド 1 を再度読んでください。何を見落としましたか? 異なるユーザータイプ/ロール、エラーパス、空状態、レースコンディション、エッジケース入力 (空、大量、特殊文字、連続クリック) について考えてください。

ラウンド 3 — カバレッジギャップ: ラウンド 1-2 を再度読んでください。アクセシビリティ (axe-core、キーボードのみ)、モバイルビューポート、コンソールエラー、アプリ全体との視覚的一貫性についてはどうですか?

重複排除: 3 つのラウンドすべてを 1 つのテスト番号付きリストにマージします。重複を削除します。各テストをグループ (例: グループ A、グループ B) に割り当てます。

その後実行 — グループごとに 1 つのサブエージェントを起動します。各サブエージェントは、実行する特定のテストリストのみを受け取ります。それ以上でもそれ以下でもありません。サブエージェントは探索や計画を行いません。割り当てられたテストを実行し、結果をレポートします。

サブエージェントを呼び出す前に、応答に 3 つのラウンド、マージされた計画、グループ割り当てを出力します。

作業分割の原則

• サブエージェントは割り当てられたテストを実行し、自由な探索は行いません。 メインエージェントは各サブエージェントに具体的なテスト番号付きリストを提供します。サブエージェントは計画、探索、またはテストの決定を行いません。リストを実行して停止します。
• ボトルネックは最も遅いエージェント です。作業を分割して、単一のエージェントが不均衡な割合を持たないようにしてください。多くの小さなエージェント > 少数の大きなエージェント。
• 努力を変更のスコープに合わせる — 単一のコンポーネント修正には多くのエージェントや多くのステップは不要です。ページ全体の再設計には必要です。差分のスコープが計画を駆動します。
• 失敗で早期停止しない — 割り当てられたテスト内でできるだけ多くのバグを見つけます。

サブエージェントにステップ予算を与える

メインエージェントは、すべてのサブエージェントプロンプトに明示的な browse ステップ制限を含める必要があります。 サブエージェントは自己制限しません。指定されない限り、完了するまで実行し続けます。

大まかなヒューリスティックとして: ~25 ステップで数個のターゲットされたチェック、~40 ステップでページ全体の機能 + 敵対的 + a11y、~75 ステップで複数ページまたは広いカテゴリ。実際に必要なテストに基づいて調整してください — これらは開始点であり、ルールではありません。

大まかなヒューリスティックとして: ~25 ステップで数個のターゲットされたチェック、~40 ステップでページ全体の機能 + 敵対的 + a11y、~75 ステップで複数ページまたは広いカテゴリ。実際に必要なテストに基づいて調整してください — これらは開始点であり、ルールではありません。

すべてのサブエージェントプロンプトに含める必要があります:

You have a budget of N browse steps (each `browse` command = 1 step). Count your steps as you go. When you reach N, stop immediately and report:
- STEP_PASS/STEP_FAIL for every test you completed
- STEP_SKIP|<test-id>|budget reached for every test you didn't get to

Do not retry or continue after hitting the budget.
Run only these tests: [numbered list from the merged plan]
Do not explore beyond the assigned tests.
Do NOT generate an HTML report or write any files. Return only step markers and your findings as text.

メインエージェントは browse コマンド自体を実行してはいけません (開発サーバーが動いているかを確認する場合を除く)。すべてのテストはサブエージェント内で発生します。

サブエージェントが予算に達した場合、メインエージェントは部分的な結果をそのまま受け入れます。 サブエージェントを再実行したり、再試行したりしないでください。最終レポートにスキップされたテストを含めて、開発者が何がカバーされなかったかを認識できるようにします。

レポート作成

すべてのサブエージェントは以下の形式でレポートして戻ります:

Tests: 8 | Passed: 5 | Failed: 2 | Skipped: 1 | Pages visited: 2

メインエージェントは最終レポートにマージします:

Tests: 20 | Passed: 14 | Failed: 4 | Skipped: 2 | Agents: 3 | Pass rate: 70%

「使用ステップ」を報告しないでください。browse コマンド数は実装の詳細であり、レビュアーにとって有意義な指標ではありません。

テスト哲学

あなたは敵対的テスターです。 あなたの目標は正確性を証明することではなく、バグを見つけることです。

• テストするすべての機能を破ろうとしてください。 「ボタンが存在するか?」だけをチェックしないでください。素早く 2 回クリック、空のフォームを送信、500 文字を貼り付け、フロー途中で Escape キーを押してください。
• 開発者が考えなかったことをテストしてください。 空状態、エラーからの復旧、キーボードのみのナビゲーション、モバイルオーバーフロー。
• すべてのアサーションはエビデンスに基づく必要があります。 スナップショット前後の比較。参照により特定の要素を確認。コンクリートな根拠なく PASS を報告しないでください。
• 十分な詳細を伴って失敗をレポートしてください。 正確な操作、期待したこと、得たこと、推奨修正を含めてください。

アサーションプロトコル

すべてのテストステップは構造化されたアサーションを生成する必要があります。フリーフォーム「これは良さそう」と書かないでください。

ステップマーカー

各テストステップに対して、正確に 1 つのマーカーを出力:

STEP_PASS|<step-id>|<evidence>

または

STEP_FAIL|<step-id>|<expected> → <actual>|<screenshot-path>

• step-id: homepage-cta、form-validation-error、modal-cancel などの短い識別子
• evidence: ステップが成功したことを証明する観察内容 (要素参照、テキスト内容、URL、eval 結果)
• expected → actual: 期待したこと vs 得たこと
• screenshot-path: 保存されたスクリーンショットへのパス (失敗のみ — スクリーンショット取得を参照)

失敗時のスクリーンショット取得

すべての STEP_FAIL には付属のスクリーンショットが必須です。 開発者が何が悪かったかを視覚的に確認できるようにするためです。

テストステップが失敗したとき:

# 1. 失敗を観察した直後にスクリーンショットを取得
browse screenshot --path .context/ui-test-screenshots/<step-id>.png

# --path がサポートされていない場合は、スクリーンショットを取得して手動で保存:
browse screenshot
# browse CLI はスクリーンショットパスを出力します。手動で移動/コピー:
cp /tmp/browse-screenshot-*.png .context/ui-test-screenshots/<step-id>.png

テスト実行の開始時にスクリーンショットディレクトリを設定:

mkdir -p .context/ui-test-screenshots

ルール:

• ファイル名 = step-id (例: double-submit.png、axe-audit.png、modal-focus-trap.png)
• .context/ui-test-screenshots/ に保存 — このディレクトリは gitignore され、開発者と他のエージェントからアクセス可能
• 並列実行の場合、セッション名を含める: <session>-<step-id>.png (例: signup-double-submit.png)
• 失敗の瞬間にスクリーンショットを取得 — 回復後ではなく、破損状態をキャプチャ
• 視覚的/レイアウトバグについては、比較用のベースライン (動作状態) もスクリーンショット: <step-id>-baseline.png

検証方法 (厳密さの順)

1. 決定論的チェック (最強) — browse eval は検査可能な構造化データを返します。例: axe-core 違反数、document.title、フォーム フィールド値、コンソールエラー配列、要素数。
2. スナップショット要素マッチ — 特定の役割とテキストを持つ特定の要素がアクセシビリティツリーに存在します。参照で確認: @0-12 button "Save"。要素がツリーに存在するか、存在しないかのいずれかです。
3. 前後の比較 — アクション前のスナップショット、操作、アクション後のスナップショット。ツリーが期待した方法で変更されたことを検証 (要素が表示、非表示、テキスト変更)。
4. スクリーンショット + 視覚的判断 (最弱) — アクセシビリティツリーがキャプチャできない視覚のみのプロパティ (色、間隔、レイアウト) の場合のみ。常に何を評価しているか具体的に伴わせてください。

前後比較パターン

これがコア検証ループです。すべてのインタラクションに使用:

# 1. BEFORE: 状態をキャプチャ
browse snapshot
# 記録: どの要素が存在するか、テキスト、参照

# 2. ACT: インタラクションを実行
browse click @0-12

# 3. AFTER: 新しい状態をキャプチャ
browse snapshot
# 比較: 何が変わったか? 何が表示されたか? 何が非表示になったか?

# 4. ASSERT: 比較に基づいてマーカーを出力
# ダイアログが表示された場合: STEP_PASS|modal-open|dialog "Confirm" appeared at @0-20
# 何も変わらなかった場合:
browse screenshot --path .context/ui-test-screenshots/modal-open.png
# STEP_FAIL|modal-open|expected dialog to appear → snapshot unchanged|.context/ui-test-screenshots/modal-open.png

セットアップ

which browse || npm install -g @browserbasehq/browse-cli

承認疲れを避ける

このスキルは多くの browse コマンド (スナップショット、クリック、eval) を実行します。各コマンドを承認する必要を避けるため、browse を許可されたコマンドに追加:

.claude/settings.json (プロジェクトレベル) または ~/.claude/settings.json (ユーザーレベル) に両方のパターンを追加:

{
  "permissions": {
    "allow": [
      "Bash(browse:*)",
      "Bash(BROWSE_SESSION=*)"
    ]
  }
}

最初のパターンはプレーン browse コマンドをカバーしています。2 番目は並列セッション (BROWSE_SESSION=signup browse open ...) をカバーしています。承認プロンプトを避けるには両方が必要です。

モード選択

ターゲット	モード	コマンド	認証
localhost / 127.0.0.1	ローカル	browse env local	不要 (デフォルトではクリーンな分離ローカルブラウザ)
デプロイ済み/ステージングサイト	リモート	browse env remote	cookie-sync → --context-id

ルール: ターゲット URL が localhost または 127.0.0.1 を含む場合、常に browse env local を使用してください。

ローカルモード (localhost のデフォルト)

browse env local
browse open http://localhost:3000

browse env local はデフォルトでクリーンな分離ローカルブラウザを使用し、これは再現可能な localhost QA 実行に最適です。

ローカルモード バリアントは必要な場合のみ使用:

• browse env local --auto-connect — 既存のローカル Chrome を自動検出、フォールバックは分離。テストが既存のローカルログイン/クッキー/状態を明示的に必要とする場合のみ使用。
• browse env local <port|url> — 特定の CDP ターゲットにアタッチ (明示的なローカルブラウザアタッチ)。

リモートモード (cookie-sync 経由でデプロイされたサイト)

# ステップ 1: ローカル Chrome から Browserbase にクッキーを同期
node .claude/skills/cookie-sync/scripts/cookie-sync.mjs --domains your-app.com
# 出力: Context ID: ctx_abc123

# ステップ 2: リモートモードに切り替え
browse env remote
browse open https://staging.your-app.com --context-id ctx_abc123 --persist
browse snapshot
# ... テストを実行 ...
browse stop

Cookie-sync フラグ: --domains、--context、--stealth、--proxy "City,ST,US"

ワークフロー A: 差分駆動型テスト

フェーズ 1: 差分を分析

git diff --name-only HEAD~1          # または: git diff --name-only / git diff --name-only main...HEAD
git diff HEAD~1 -- <file>            # 実際の変更を読む

変更されたファイルを分類:

ファイルパターン	UI への影響	テスト対象
*.tsx、*.jsx、*.vue、*.svelte	コンポーネント	レンダリング、インタラクション、状態、エッジケース
pages/**、app/**、src/routes/**	ルート/ページ	ナビゲーション、ページロード、コンテンツ、404 処理
*.css、*.scss、*.module.css	スタイル	視覚的外観 (スクリーンショット)、レスポンシブ
*form*、*input*、*field*	フォーム	検証、送信、空入力、長入力、特殊文字
*modal*、*dialog*、*dropdown*	インタラクティブ	開く/閉じる、Escape キー、フォーカストラップ、キャンセル vs 確認
*nav*、*menu*、*header*	ナビゲーション	リンク、アクティブ状態、ルーティング、キーボードナビゲーション
UI 以外のファイルのみ	なし	スキップ — 「UI テストは不要」とレポート

フェーズ 2: ファイルを URL にマップ

フレームワークを検出: cat package.json | grep -E '"(next|react|vue|nuxt|svelte|@sveltejs|angular|vite)"'

フレームワーク	デフォルトポート	ファイル → URL パターン
Next.js App Router	3000	app/dashboard/page.tsx → /dashboard
Next.js Pages Router	3000	pages/about.tsx → /about
Vite	5173	ルータ設定を確認
Nuxt	3000	pages/index.vue → /
SvelteKit	5173	src/routes/+page.svelte → /
Angular	4200	ルーティングモジュールを確認

フェーズ 3: 正しいコードが実行されていることを確認

テストを開始する前に、開発サーバーが差分からコードを提供していることを確認 — 古いブランチからではなく。

PR または特定のブランチをテストしている場合:

# 現在チェックアウトされているブランチを確認
git branch --show-current

# PR ブランチでない場合はスイッチ
git fetch origin <branch> && git checkout <branch>

# deps をインストール — ロックファイルがブランチ間で異なる可能性があります
yarn install  # または npm install / pnpm install

開発サーバーが既に別のブランチで実行されている場合、チェックアウト後に再起動してください。

実行中の開発サーバーを検索:

for port in 3000 3001 5173 4200 8080 8000 5000; do
  s=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:$port" 2>/dev/null)
  if [ "$s" != "000" ]; then echo "Dev server on port $port (HTTP $s)"; fi
done

何も見つからない場合: ユーザーに開発サーバーの起動を依頼してください。

実際にレンダリングされることを確認: browse open + browse snapshot 後、アクセシビリティツリーに実際のページコンテンツ (ナビゲーション、見出し、インタラクティブ要素) が含まれていることを確認。単なるエラーオーバーレイや空の body ではなく。Next.js 開発サーバーは HTTP 200 を返しながら、全画面ビルドエラーダイアログを表示できます。スナップショットが空かエラーダイアログに支配されている場合、サーバーは壊れています。テストを開始する前に、ビルドを修正してください。

フェーズ 4: テスト計画を生成

変更された各領域について、ハッピーパスと敵対的テストの両方 を計画:

Test Plan (based on git diff)
=============================
Changed: src/components/SignupForm.tsx (added email validation)

1. [happy] Valid email submits successfully
   URL: http://localhost:3000/signup
   Steps: fill valid email → submit → verify success message appears

2. [adversarial] Invalid email shows error
   Steps: fill "not-an-email" → submit → verify error message appears

3. [adversarial] Empty form submission
   Steps: click submit without filling anything → verify error, no crash

4. [adversarial] XSS in email field
   Steps: fill "<script>alert(1)</script>" → submit → verify sanitized/rejected

5. [adversarial] Rapid double-submit
   Steps: click submit twice quickly → verify no duplicate submission

6. [adversarial] Keyboard-only flow
   Steps: Tab to email → type → Tab to submit → Enter → verify success

フェーズ 5: テストを実行

browse stop 2>/dev/null
mkdir -p .context/ui-test-screenshots
# localhost/デフォルト QA → クリーンで再現可能なローカル実行
browse env local

各テストについて、前後パターン に従う:

# ナビゲート
browse open http://localhost:3000/path
browse wait load

# BEFORE スナップショット
browse snapshot
# 現在の状態を記録: 要素、参照、テキスト

# ACT
browse click @0-ref
# または: browse fill "selector" "value"
# または: browse type "text"
# または: browse press Enter

# AFTER スナップショット
browse snapshot
# BEFORE と比較: 何が変わったか?

# ASSERT マーカーを出力
# STEP_PASS|step-id|evidence  または  STEP_FAIL|step-id|expected → actual

フェーズ 6: 結果をレポート

## UI Test Results

### STEP_PASS|valid-email-submit|status "Thanks!" appeared at @0-42 after submit
- URL: http://localhost:3000/signup
- Before: form with email input @0-3, submit button @0-7
- Action: filled "user@test.com", clicked @0-7
- After: form replaced by status element with "Thanks! We'll be in touch."

### STEP_FAIL|double-submit|expected single submission → form submitted twice|.context/ui-test-screenshots/double-submit.png
- URL: http://localhost:3000/signup
- Before: form with submit button @0-7
- Action: clicked @0-7 twice rapidly
- After: two success toasts appeared, suggesting duplicate submission
- Screenshot: .context/ui-test-screenshots/double-submit.png
- Suggestion: disable submit button after first click, or debounce the handler

---
**Summary: 4/6 passed, 2 failed**
Failed: double-submit, xss-sanitization

Screenshots saved to `.context/ui-test-screenshots/` — open any failed step's screenshot to see the broken state.

完了したら常に browse stop を実行してください。

フェーズ 7: HTML レポートを生成

テキストレポートを作成した後、レビュアーがブラウザで開くことができるスタンドアロン HTML レポートを生成してください。レポートはスクリーンショットをインラインで埋め込む (base64) ため、外部依存関係なしで単一ファイルとして機能します。

理由: テキストレポートはエージェント会話に適していますが、レビュアー (PM、デザイナー、他のエンジニア) は視覚的アーティファクトが必要です。スクリーンショットのインライン埋め込みにより、失敗が直ちに明らかになります。

生成方法

1. references/report-template.html で HTML テンプレートを読む
2. テンプレートプレースホルダを実際のテストデータで置き換えてレポートを構築:

プレースホルダ	値
{{TITLE}}	<title> タグのレポートタイトル (例: "UI Test: PR #1234 — OAuth Settings")
{{TITLE_HTML}}	表示される <h1> のレポートタイトル。PR URL が利用可能な場合、PR 参照を <a> タグでラップしてクリック可能にする (例: UI Test: <a href="https://github.com/org/repo/pull/1234">PR #1234</a> — OAuth Settings)。URL がない場合は {{TITLE}} と同じプレーンテキストを使用。
{{META}}	1 行の文脈: 日付、アプリ URL、ユーザー、ブランチ
{{TOTAL_TESTS}}	合計 STEP_PASS + STEP_FAIL 数
{{AGENT_COUNT}}	実行したサブエージェント数
{{PASS_COUNT}}	STEP_PASS 数
{{FAIL_COUNT}}	STEP_FAIL 数
{{PASS_RATE}}	整数パーセンテージ (例: "92")
{{RATE_CLASS}}	good (≥90%)、warn (70–89%)、bad (<70%)
{{FAILURES_SECTION}}	失敗したテストカードの HTML (以下を参照)
{{PASSES_SECTION}}	成功したテストカードの HTML (以下を参照)

3. 各テスト結果について、<details> カードを生成。失敗したテストは デフォルトで開く ため、レビュアーが直ちに確認できます:

<!-- 失敗したテストカード (デフォルトで開く) -->
<div class="section">
  <h2>Failures <span class="count">{{FAIL_COUNT}}</span></h2>
  <details class="test-card fail" open>
    <summary>
      <span class="badge fail">FAIL</span>
      <span class="step-id">step-id-here</span>
      <span class="evidence">expected → actual</span>
    </summary>
    <div class="body">
      <dl>
        <dt>URL</dt><dd>http://localhost:3000/path</dd>
        <dt>Action</dt><dd>What was done</dt>
        <dt>Expected</dt><dd>What should have happened</dd>
        <dt>Actual</dt><dd>What happened instead</dd>
      </dl>
      <div class="suggestion">Fix: description of suggested fix</div>
      <div class="screenshot">
        <img src="data:image/png;base64,..." alt="Screenshot of failure">
        <div class="caption">step-id.png — captured at moment of failure</div>
      </div>
    </div>
  </details>
</div>

<!-- 成功したテストカード (デフォルトで折畳み) -->
<div class="section">
  <h2>Passed <span class="count">{{PASS_COUNT}}</span></h2>
  <details class="test-card pass">
    <summary>
      <span class="badge pass">PASS</span>
      <span class="step-id">step-id-here</span>
      <span class="evidence">evidence summary</span>
    </summary>
    <div class="body">
      <dl>
        <dt>URL</dt><dd>http://localhost:3000/path</dd>
        <dt>Evidence</dt><dd>What was observed</dd>
      </dl>
    </div>
  </details>
</div>

4. スクリーンショットを base64 としてエンベッド し、HTML を完全に自己完結:

# スクリーンショットを base64 データ URI に変換
base64 -i .context/ui-test-screenshots/step-id.png | tr -d '\n'
# 使用方法: src="data:image/png;base64,<output>"

STEP_FAIL マーカーで参照される各スクリーンショットファイルを読み込み、base64 エンコードし、対応するテストカードに <img src="data:image/png;base64,..."> としてエンベッドします。STEP_PASS については、明示的に取得された場合のみスクリーンショットをエンベッド (例: ベースラインスクリーンショット)。

5. 生成された HTML を .context/ui-test-report.html に書き込む:

# 生成された HTML を書き込む
cat > .context/ui-test-report.html << 'REPORT_EOF'
<!DOCTYPE html>
...generated report...
REPORT_EOF

# レビュアーが開くように
open .context/ui-test-report.html  # macOS
# xdg-open .context/ui-test-report.html  # Linux

6. ユーザーに伝える: Report saved to .context/ui-test-report.html であり、レポートを開くことを提案してください。

ルール:

• 失敗セクションが合格セクションの前 — レビュアーは最初に破損したものに関心があります
• 失敗したカードは open、成功したカードは折畳み
• すべての STEP_FAIL カードには埋め込みスクリーンショットが必須 — スクリーンショットファイルが見つからない場合は、カードに記載
• 各失敗カードに修正提案/推奨が含まれている場合は記載
• レポートはオフラインで機能する必要があります — CDN リンクなし、外部アセットなし
• HTML を 5MB 以下に保つ — スクリーンショットがそれを超える場合、画像品質を下げるか、合格のベースラインスクリーンショットをスキップ

敵対的テストパターン

テストするすべてのインタラクティブ要素にこれらを適用してください。完全なパターンライブラリについては references/adversarial-patterns.md を読む (フォーム、モーダル、ナビゲーション、エラー状態、キーボードアクセシビリティ)。

決定論的チェック

これらは判断ではなく、構造化データを生成します。アサーションの最も強い形式として使用してください。

チェック	何を検出するか	アサーション
axe-core	WCAG 違反	violations.length === 0
コンソールエラー	ランタイム例外、失敗したリクエスト	エラー配列が空
壊れた画像	見つからない/失敗した画像読み込み	naturalWidth === 0 の画像がない
フォームラベル	ラベルのないインプット	すべてのインプットに hasLabel: true がある

正確な browse eval レシピについては references/browser-recipes.md を読む。

ワークフロー B: 探索的テスト

差分なし、計画なし — ただアプリを開いて破ろうとする。ユーザーが「アプリをテストして」「バグを見つけて」「このサイトを QA して」と言った場合に使用。

アプローチ

1. アプリを発見 — package.json を読んでフレームワークを検出し、ルート URL を開いてスナップショットを取得し、何があるかを確認
2. すべてをナビゲート — ナビゲーションリンクをクリック、すべてのアクセス可能なページを訪問、何が存在するかをメモ
3. 見つけたものをテスト — 各ページについて、以下の敵対的パターンを適用 (フォーム、モーダル、ナビゲーション、キーボード、エラー状態)
4. 決定論的チェックを実行 — すべてのページで axe-core、コンソールエラー、壊れた画像、フォームラベルを実行
5. 結果をレポート — STEP_PASS/STEP_FAIL マーカーを使用し、失敗については再現ステップを含める

カバレッジの体系的なことをしようとしないでください。ユーザーがそうするように、アプリを探索するだけですが、物を壊す意図を持っています。エージェントはこれに優れています。自由に動き回すようにしてください。

探索的実行のティップス

• ホームページから始め、ナビゲーションに従い自然に進む
• 404 ページを試す (/does-not-exist) — カスタムか既定か?
• 空状態 (データなしのページ) を探す
• 有効な入力の前にゴミ入力でフォームをテスト
• すべてのページでモバイルビューポート (375px) をチェック — オーバーフロー?
• アプリに認証がある場合、最初に cookie-sync を使用

ワークフロー C: 並列テスト

名前付き browse セッション (BROWSE_SESSION=<name>) を使用して独立したテストグループを並列実行。各セッションは独自のブラウザを取得。ローカルおよびリモートモードの両方で機能。

複数のページやカテゴリをテストし、壁時間を高速化したい場合に使用。

完全なワークフローについては references/parallel-testing.md を読む: セッション設定、エージェントファンアウト、認証用 cookie-sync、結果マージング。

デザイン一貫性

変更された UI がアプリの残りの部分と視覚的に一致しているかを確認。視覚的またはデザインチェックを実行する場合は references/design-consistency.md を読む。

テストカテゴリ

カテゴリ	方法	アサーション型
アクセシビリティ	axe-core + キーボードナビゲーション	決定論的 (違反数)
視覚品質	スクリーンショット + ヒューリスティック評価	視覚的判断 (最弱 — 詳細を記載)
レスポンシブ	ビューポートスイープ + スクリーンショット	視覚的 + 決定論的 (オーバーフロー確認)
コンソールヘルス	コンソールキャプチャ eval	決定論的 (エラー数)
UX ヒューリスティック	スナップショット + Laws of UX + Nielsen's	構造化判断 (特定ヒューリスティックを引用)
エラー状態	空/エラー状態へナビゲート	前後比較
データ表示	テーブル/ダッシュボード上のスナップショット	要素マッチ (列数、フォーマット)
デザイン一貫性	スクリーンショットベースライン + 変更ページ比較	視覚的判断 (特定プロパティを引用)
探索的	自由ナビゲーション + 敵対的テスト	前後比較 + 判断

参照ガイド (必要に応じてロード):

• 敵対的パターン — references/adversarial-patterns.md — フォーム、モーダル、ナビゲーション、キーボード a11y をテストするときにロード
• ブラウザレシピ — references/browser-recipes.md — 決定論的チェック (axe-core、コンソール、画像、フォームラベル) を実行するときにロード
• 探索的テスト — references/exploratory-testing.md — ワークフロー B (差分なし、自由探索) でロード
• UX ヒューリスティック — references/ux-heuristics.md — UX 品質を評価したり、特定ヒューリスティックを引用したりするときにロード
• デザインシステム — references/design-system.example.md — ユーザーがカスタマイズするテンプレート
• デザイン一貫性 — references/design-consistency.md — 視覚的一貫性チェックを実行するときにロード
• 並列テスト — references/parallel-testing.md — ワークフロー C (並列セッション) でロード
• レポートテンプレート — references/report-template.html — フェーズ 7 レポート生成用 HTML テンプレート

実例の正確なコマンドについては、アサーションプロトコルを実際に見たい場合は EXAMPLES.md を読む。

ベストプラクティス

1. 敵対的であれ — 物を壊そうとし、単に機能することを確認しないでください
2. すべてのアサーションはエビデンスが必要 — スナップショット参照、eval 結果、または前後の diff
3. すべてのインタラクションに前後を — スナップショット、操作、スナップショット、比較
4. すべての失敗をスクリーンショット — STEP_FAIL 時に直ちに browse screenshot を実行し、.context/ui-test-screenshots/<step-id>.png に保存
5. 決定論的チェックを最初に — 視覚的判断の前に axe-core、コンソールエラー、フォームラベル
6. localhost については、クリーンなローカルモードから開始 — 再現可能な実行のために最初に browse env local を使用。既存のローカル状態が必要な場合のみ --auto-connect を使用
7. 完了時に常に browse stop — 並列実行については、すべての名前付きセッションを停止
8. 再現ステップを伴って失敗をレポート — 操作、期待、実際、スクリーンショットパス、提案
9. 独立したテストを並列化 — 複数のページやカテゴリをテストしている場合、デプロイされたサイトで名前付きセッションを使用してワークフロー C を使用

トラブルシューティング

• 「No active page」: browse stop を実行し、再試行。ゾンビについて: pkill -f "browse.*daemon"
• 開発サーバーが応答しない: curl http://localhost:<port> — ユーザーに起動を依頼
• browse eval で await が失敗: 代わりに .then() を使用 — browse eval はトップレベル await をサポートしていません
• 要素参照が見つからない: browse snapshot を再度実行 — ページ更新時に参照は変わります
• 空のスナップショット: スナップショット前に browse wait load または browse wait selector ".expected" を実行
• SPA ディープリンク 404: 最初に / へナビゲート、その後クリックして進める
• リモート認証失敗: --context <id> で cookie-sync を再実行し、--stealth を試す
• 並列セッション競合: すべての browse コマンドが BROWSE_SESSION=<name> を使用することを確認 — なしの場合、コマンドはデフォルトセッションに移動
• セッション停止しない: BROWSE_SESSION=<name> browse stop。ゾンビについて: pkill -f "browse.*<name>.*daemon"