qe-browser

QE Browser

Vをベースにした、AQE が所有する軽量ラッパーです。型付きアサーション、バッチ実行、ベースラインとのビジュアル差分、プロンプトインジェクションのスキャン、セマンティックな意図のスコアリングといった QE 固有のプリミティブを追加します。

エンジン： Vibium — 約 10MB の単一 Go バイナリで、WebDriver BiDi（W3C 標準）を基盤とし、Apache-2.0 ライセンスで提供され、npm／PyPI／Maven Central で公開されています。バックグラウンドデーモンを自動起動し、初回使用時に Chrome for Testing を自動ダウンロードします。

Playwright ではなく Vibium を選ぶ理由

• Playwright の約 300MB のインストールに対して、バイナリは 10MB
• WebDriver BiDi 標準（CDP ではありません） — Firefox／Safari にも将来対応できます
• すべてのコマンドに --json モードを用意（AQE の構造化出力ルールに適合）
• MCP サーバーを内蔵：npx -y vibium mcp
• セマンティックロケーターに標準で対応：find text|label|placeholder|testid|role|xpath|alt|title

プラットフォームのサポート（2026-04-09、Vibium v26.3.18 で検証済み）

プラットフォーム	npm install -g vibium	vibium go <url>	smoke-test.sh
macOS arm64（Apple Silicon ネイティブ）	✅	✅	✅
macOS x64（Intel）	✅	✅	✅
Linux x86_64	✅	✅	✅
Windows x64	✅	✅	まだテストされていません
Linux ARM64（aarch64）	✅ バイナリ自体は動作	⚠️ 回避策が必要	✅ 回避策適用後

Linux ARM64 の回避策

Google Chrome for Testing は linux-arm64 ビルドを公開していません。Vibium は aarch64 ホスト上で chrome-linux64（x86_64）にフォールバックするため、Rosetta 経由では failed to open elf at /lib64/ld-linux-x86-64.so.2 エラーが発生します。Linux ARM64 の codespace またはコンテナーで qe-browser を実行するには、次の手順に従ってください。

# 1. Install Vibium normally — the vibium binary itself IS native ARM64
npm install -g vibium

# 2. Install Debian's native ARM64 chromium + chromedriver
sudo apt-get update
sudo apt-get install -y chromium chromium-driver

# 3. Symlink Vibium's broken cached binaries to the native system ones.
#    Run after `vibium install` (auto-runs on first `vibium go`).
for dir in ~/.cache/vibium/chrome-for-testing/*/; do
  # Newer Vibium layout (v26.3.x): chromedriver and chrome at the root
  if [ -e "$dir/chromedriver" ]; then
    rm -f "$dir/chromedriver" "$dir/chrome"
    ln -s /usr/bin/chromedriver "$dir/chromedriver"
    ln -s /usr/bin/chromium     "$dir/chrome"
  fi
  # Older Vibium layout: chromedriver-linux64/ and chrome-linux64/ subdirs
  if [ -e "$dir/chromedriver-linux64/chromedriver" ]; then
    rm -f "$dir/chromedriver-linux64/chromedriver" "$dir/chrome-linux64/chrome"
    ln -s /usr/bin/chromedriver "$dir/chromedriver-linux64/chromedriver"
    ln -s /usr/bin/chromium     "$dir/chrome-linux64/chrome"
  fi
done

# 4. Verify
vibium --headless go https://httpbin.org/html
vibium --headless title  # → "Herman Melville - Moby-Dick"

この回避策は、chromium 146.0.7680.177-1~deb12u1 を使用した Debian bookworm aarch64 で動作することを確認済みです。上流の動向を確認してください。Vibium に --browser-path フラグが追加されるか、Google が linux-arm64 の Chrome for Testing を公開した時点で、このセクションは不要になります。

ヘッドレスモード

ヘルパースクリプト（assert.js、batch.js、visual-diff.js、check-injection.js、intent-score.js）は、すべての vibium 呼び出しに --headless を自動的に追加します。qe-browser スキルは、ディスプレイサーバーのない QE／CI のユースケース向けに設計されているためです。Vibium 自体はデフォルトで「表示モード」です。ヘッドレスコンテナーで --headless を指定せずに vibium go を実行すると、Missing X server or $DISPLAY エラーが発生します。

対話的なデバッグで無効にするには：

QE_BROWSER_HEADED=1 node .claude/skills/qe-browser/scripts/assert.js --checks '...'

ヘルパー経由ではなく vibium を直接呼び出す場合、コンテナー内では --headless を自分で指定してください。

vibium --headless go https://example.com
vibium --headless title

有効化するタイミング

• QE スキルで Web ページへの移動、読み取り、操作、キャプチャが必要なとき
• 保存済みベースラインに対してビジュアル回帰テストを実行するとき
• ページの状態（URL、テキストの表示、コンソールエラー、ネットワーク障害）をアサートするとき
• セキュリティ上の検出事項の悪用可能性を検証するとき（ペンテスト）
• 信頼できないページをスキャンしてプロンプトインジェクションを検出するとき
• 明示的な合格／不合格ゲートを設けてバッチ自動化を実行するとき

基本的なワークフロー

ブラウザーを使うすべての QE タスクは、同じ流れに従います。

1. 移動 — vibium go <url>
2. マップ — vibium map で要素参照（@e1、@e2、…）を取得
3. 操作 — vibium click @e1、vibium fill @e2 "text"
4. 検証 — このスキルの assert.js で型付きチェックを実行するか、vibium diff map で変更点を確認
5. DOM が変更された場合は再マップ

# Typical login flow verification
vibium go https://app.example.com/login
vibium map --json > /tmp/refs.json
vibium fill @e1 "$USERNAME"
vibium fill @e2 "$PASSWORD"
vibium click @e3
vibium wait url "/dashboard"
node .claude/skills/qe-browser/scripts/assert.js --checks '[
  {"kind": "url_contains", "text": "/dashboard"},
  {"kind": "no_console_errors"},
  {"kind": "no_failed_requests"}
]'

参照のライフサイクル — diff map を使う

DOM が変更されると、Vibium の参照は無効になります。参照のバージョンを手動で管理する代わりに、Vibium の vibium diff map を使うと、前回の map 呼び出し以降に追加、削除、位置変更されたものを正確に確認できます。DOM を変更する操作の後は、次のようにします。

vibium click @e3
vibium diff map --json   # shows added/removed/moved refs

バージョン番号を追跡するよりも簡潔で、次のアクションにそのまま渡せる構造化された差分を取得できます。

QE プリミティブ（このスキルが付加する価値）

すべてのスクリプトは .claude/skills/qe-browser/scripts/ にあり、vibium を呼び出します。vibium が PATH 上にあること（aqe init でインストール済み）を前提とします。

assert.js — 16 種類のチェックに対応した型付きアサーション

node scripts/assert.js --checks '[
  {"kind": "url_contains", "text": "/dashboard"},
  {"kind": "text_visible", "text": "Welcome"},
  {"kind": "selector_visible", "selector": "#user-menu"},
  {"kind": "value_equals", "selector": "input[name=email]", "value": "[email protected]"},
  {"kind": "no_console_errors"},
  {"kind": "no_failed_requests"},
  {"kind": "response_status", "url": "/api/user", "status": 200},
  {"kind": "element_count", "selector": ".result", "op": ">=", "count": 5}
]'

全 16 種類：url_contains、url_equals、text_visible、text_hidden、selector_visible、selector_hidden、value_equals、attribute_equals、no_console_errors、no_failed_requests、response_status、request_url_seen、console_message_matches、element_count、title_matches、page_source_contains。

詳細はリファレンスをご覧ください。

いずれかのチェックに失敗すると、終了コードは 0 以外になります。出力は JSON です：{ "passed": N, "failed": M, "results": [...] }。

batch.js — 失敗時に停止する複数ステップの実行

node scripts/batch.js --steps '[
  {"action": "go", "url": "https://example.com/login"},
  {"action": "fill", "ref": "@e1", "text": "[email protected]"},
  {"action": "fill", "ref": "@e2", "text": "secret"},
  {"action": "click", "ref": "@e3"},
  {"action": "wait_url", "pattern": "/dashboard"},
  {"action": "assert", "checks": [{"kind": "no_console_errors"}]}
]' --summary-only

各ステップで vibium を呼び出す場合と比べて、ラウンドトリップを削減します。--stop-on-failure（デフォルトは true）と --summary-only に対応しています。

visual-diff.js — 保存済みのベースラインとのピクセル差分

# First run — creates baseline
node scripts/visual-diff.js --name "homepage"

# Subsequent runs — compare
node scripts/visual-diff.js --name "homepage" --threshold 0.05

# Scope to an element
node scripts/visual-diff.js --name "hero" --selector "#hero"

# Reset baseline after intentional change
node scripts/visual-diff.js --name "homepage" --update-baseline

ベースラインは .aqe/visual-baselines/ に保存されます（プロジェクトローカルで、デフォルトでは gitignore の対象です）。ピクセル比較には pixelmatch を使用し、一致率と差分画像のパスを返します。

check-injection.js — プロンプトインジェクションスキャナー

現在のページコンテンツをスキャンし、既知のプロンプトインジェクションのパターン（以前の指示を無視する、非表示テキスト内のシステムプロンプトなど）を検出します。gsd-browser のヒューリスティックスキャナー（MIT/Apache）を移植したものです。

vibium go https://untrusted-page.com
node scripts/check-injection.js --include-hidden --json

重大度順に検出結果を返します。pentest-validation、injection-analyst、aidefence-guardian を対象としています。

intent-score.js — 15 種類のセマンティックインテント

ヒューリスティックによるスコアリングで要素を検出します。LLM とのラウンドトリップは不要です。gsd-browser の intent.rs:59-385（MIT/Apache）を移植したものです。

node scripts/intent-score.js --intent accept_cookies
node scripts/intent-score.js --intent submit_form --scope "#login-form"
node scripts/intent-score.js --intent primary_cta

インテント：submit_form、close_dialog、primary_cta、search_field、next_step、dismiss、auth_action、back_navigation、fill_email、fill_password、fill_username、accept_cookies、main_content、pagination_next、pagination_prev。

スコアとセレクターを含む上位 5 件の候補を返します。ページ全体をマッピングすることなく、Cookie バナーの閉じる操作、ログインフォームの検出、ウィザードの操作を行うのに便利です。

QE でよく使うパターン

パターン 1 — CI でのビジュアルリグレッション

vibium go "$STAGING_URL"
vibium wait load
node scripts/visual-diff.js --name "homepage-$(uname -m)" --threshold 0.02
# Non-zero exit if diff exceeds threshold

パターン 2 — 明示的なアサーションを含む E2E フロー

node scripts/batch.js --steps @flows/login-flow.json
node scripts/assert.js --checks @assertions/post-login.json

パターン 3 — axe とのラウンドトリップなしで行うアクセシビリティ監査

vibium go "$URL"
vibium a11y-tree --json > a11y.json
# Analyze a11y.json with axe-core or in-skill rules

パターン 4 — 認証状態の再利用

# Once: log in and save state
vibium go https://app.example.com/login
vibium fill "input[name=email]" "$USERNAME"
vibium fill "input[name=password]" "$PASSWORD"
vibium click "button[type=submit]"
vibium wait url "/dashboard"
vibium storage -o .aqe/auth/myapp.json

# Every subsequent run
vibium storage restore .aqe/auth/myapp.json
vibium go https://app.example.com/dashboard

パターン 5 — ペネトレーションテストのエクスプロイト検証

vibium go "$TARGET"
node scripts/check-injection.js --include-hidden > injection-report.json
vibium record start --name "exploit-$(date +%s)"
# Perform exploit steps via vibium commands
vibium record stop -o evidence.zip

パターン 6 — セマンティックインテントを使った Cookie バナーの閉じる操作

vibium go "$URL"
# Heuristic scoring — no LLM needed
ACCEPT=$(node scripts/intent-score.js --intent accept_cookies --json | jq -r '.candidates[0].selector // empty')
[ -n "$ACCEPT" ] && vibium click "$ACCEPT"

MCP 連携

Vibium には専用の MCP サーバーが付属しています。次のように使用します：

claude mcp add vibium -- npx -y vibium mcp

Vibium MCP ツール（mcp__vibium__*）を利用できる場合は、主要な navigate/map/click/fill 操作ではシェル呼び出しよりもこれらを優先してください。QE 固有のプリミティブ（アサーション、batch、visual-diff、injection、intents）には、このスキルの scripts/ を引き続き使用してください。これらは Vibium の一部ではありません。

フォールバックポリシー

vibium がインストールされていない場合（例：aqe init が実行されていない、またはユーザーがオプトアウトした場合）、qe-browser ヘルパースクリプトが契約を自動的に実装します。**エラー文字列を grep する必要はありません。**各スクリプトは次の処理を行います：

1. バイナリが PATH にない場合に lib/vibium.js がスローする VibiumUnavailableError をキャッチします
2. トップレベルに vibiumUnavailable: true、output.reason: "browser-engine-unavailable" を含む、構造化された skipped エンベロープを出力します（下記の出力契約を参照）
3. 終了コード 2 で終了します（スキップを示します。成功の 0、失敗の 1 とは異なります）
4. Playwright または puppeteer-extra にサイレントフォールバックすることはありません

これらのヘルパーをシェル呼び出しする下流のスキルでは、構造化フィールドを使って分岐できます：

node .claude/skills/qe-browser/scripts/assert.js --checks "$CHECKS"
EXIT=$?
case $EXIT in
  0) echo "passed" ;;
  1) echo "failed" ; cat last-output.json ;;
  2) echo "skipped — vibium not installed; run \`aqe init\` or \`npm install -g vibium\`" ;;
esac

または Node では：

const result = JSON.parse(stdout);
if (result.vibiumUnavailable) {
  // Surface skipped status to the caller; do NOT mark as failed
  return { status: 'skipped', reason: result.output.reason };
}

Playwright からの移行

既存の Playwright テストがある場合：

// Playwright
await page.goto('https://example.com');
await page.fill('input[name=email]', '[email protected]');
await page.click('button[type=submit]');
await expect(page).toHaveURL(/dashboard/);

次のようになります：

# qe-browser
vibium go https://example.com
vibium fill "input[name=email]" "[email protected]"
vibium click "button[type=submit]"
vibium wait url "/dashboard"
node .claude/skills/qe-browser/scripts/assert.js --checks '[
  {"kind": "url_contains", "text": "/dashboard"}
]'

移行ガイド全文：references/migration-from-playwright.md。

出力契約

すべてのスクリプトは、構造化された JSON エンベロープを出力します。有効な status 値は 3 種類です：

success（終了コード 0）

{
  "skillName": "qe-browser",
  "version": "1.0.0",
  "timestamp": "2026-04-09T12:00:00Z",
  "status": "success",
  "trustTier": 3,
  "output": {
    "operation": "assert",
    "summary": "All 6 assertions passed",
    "assert": { ... }
  },
  "metadata": { "executionTimeMs": 142 }
}

failed（終了コード 1）

形式は同じです。status: "failed" は、アサーションの失敗または操作エラーが発生したことを示します。output.* ブロックには、チェックごとの詳細が含まれます。

スキップ（終了コード 2）— F1 の仕様

vibium が PATH にインストールされていない場合に出力されます。トップレベルの vibiumUnavailable: true は、後続のスキル向けの正式なシグナルです。

{
  "skillName": "qe-browser",
  "version": "1.0.0",
  "timestamp": "2026-04-09T12:00:00Z",
  "status": "skipped",
  "trustTier": 3,
  "vibiumUnavailable": true,
  "output": {
    "operation": "assert",
    "summary": "vibium binary not found on PATH. Install via `npm install -g vibium` or run `aqe init`.",
    "reason": "browser-engine-unavailable",
    "error": "vibium binary not found on PATH...",
    "remediation": [
      "Install vibium globally: `npm install -g vibium`",
      "Or re-run `aqe init` to install via the AQE bootstrap",
      "Set QE_BROWSER_HEADED=1 only for interactive debugging (not the cause here)"
    ]
  },
  "metadata": { "executionTimeMs": 0 }
}

終了コードの概要

終了コード	ステータス	意味
0	success	すべてのアサーションに合格／操作が完了しました
1	failed	実際のアサーション失敗または操作エラー
2	skipped	vibium が利用できません。環境の問題であり、テスト結果ではありません

CI ツールは終了コードを使って、「テストが正当に失敗した」（ビルドをブロックする）場合と、「ブラウザーエンジンがインストールされていないためテストを実行できなかった」（警告するがブロックしない）場合を区別できます。

scripts/validate-config.json と schemas/output.json で検証してください。

クレジット

• プロンプトインジェクションスキャナーと意図スコアリングロジックは、gsd-browser（MIT/Apache-2.0）から移植されています。
• エンジン：Vibium（Apache-2.0）。