proffesor-for-testing/qe-browser

QE Browser

Thin AQE-owned wrapper around Vibium that adds QE-specific primitives: typed assertions, batch execution, visual-diff against baselines, prompt-injection scanning, and semantic intent scoring.

Engine: Vibium — single ~10MB Go binary, built on WebDriver BiDi (W3C standard), Apache-2.0 licensed, published on npm/PyPI/Maven Central. Auto-launches a background daemon and auto-downloads Chrome for Testing on first use.

Why Vibium, not Playwright?

• 10MB binary vs ~300MB Playwright install
• WebDriver BiDi standard (not CDP) — future-proof for Firefox/Safari
• --json mode on every command (matches AQE structured-output rule)
• Built-in MCP server: npx -y vibium mcp
• First-class semantic locators: find text|label|placeholder|testid|role|xpath|alt|title

Platform support (verified 2026-04-09 against Vibium v26.3.18)

| Platform | npm install -g vibium | vibium go <url> | smoke-test.sh | |---|---|---|---| | macOS arm64 (Apple Silicon native) | ✅ | ✅ | ✅ | | macOS x64 (Intel) | ✅ | ✅ | ✅ | | Linux x86_64 | ✅ | ✅ | ✅ | | Windows x64 | ✅ | ✅ | not yet tested | | Linux ARM64 (aarch64) | ✅ binary itself | ⚠️ Workaround required | ✅ after workaround |

Linux ARM64 workaround

Google Chrome for Testing does not publish a linux-arm64 build. Vibium falls back to chrome-linux64 (x86_64) on aarch64 hosts, which fails under Rosetta with failed to open elf at /lib64/ld-linux-x86-64.so.2. To run qe-browser on a Linux ARM64 codespace or container:

# 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"

This workaround is verified working on Debian bookworm aarch64 with chromium 146.0.7680.177-1~deb12u1. Track upstream — when Vibium adds a --browser-path flag or Google ships linux-arm64 Chrome for Testing, this section becomes obsolete.

Headless mode

Helper scripts (assert.js, batch.js, visual-diff.js, check-injection.js, intent-score.js) automatically inject --headless into every vibium invocation because the qe-browser skill is designed for QE/CI use cases where there's no display server. Vibium itself defaults to "visible by default" — running vibium go on a headless container without --headless fails with Missing X server or $DISPLAY.

Opt out for interactive debugging:

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

When you call vibium directly (not through a helper), pass --headless yourself if you're in a container:

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

Activation

• When a QE skill needs to navigate, read, interact with, or capture a web page
• When running visual regression tests against stored baselines
• When asserting page state (URL, text visibility, console errors, network failures)
• When validating exploitability of security findings (pentest)
• When scanning untrusted pages for prompt injection
• When running batch automation with explicit pass/fail gates

Core Workflow

Every browser-driven QE task follows the same shape:

1. Navigate — vibium go <url>
2. Map — vibium map to get element refs (@e1, @e2, …)
3. Interact — vibium click @e1, vibium fill @e2 "text"
4. Verify — use this skill's assert.js to run typed checks, OR use vibium diff map to see what changed
5. Re-map if DOM changed

# 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"}
]'

Ref Lifecycle — use diff map

Vibium refs are invalidated when the DOM changes. Instead of versioning refs manually, Vibium gives you vibium diff map which shows exactly what's new, removed, or repositioned since the last map call. After any interaction that changes the DOM:

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

This is cleaner than tracking version numbers — you get a structured delta you can feed directly into the next action.

QE Primitives (this skill's value-add)

All scripts live in .claude/skills/qe-browser/scripts/ and shell out to vibium. They expect vibium to be on PATH (installed by aqe init).

assert.js — Typed assertions with 16 check kinds

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}
]'

All 16 kinds: 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.

Full reference: references/assertion-kinds.md.

Exit code is non-zero if any check fails. Output is JSON: { "passed": N, "failed": M, "results": [...] }.

batch.js — Multi-step execution with stop-on-failure

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

Reduces round-trips vs calling vibium per step. Supports --stop-on-failure (default true) and --summary-only.

visual-diff.js — Pixel diff against stored baselines

# 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

Baselines stored in .aqe/visual-baselines/ (project-local, gitignored by default). Uses pixelmatch for pixel comparison; returns similarity % and diff image path.

check-injection.js — Prompt injection scanner

Scans the current page content for known prompt-injection patterns (ignore previous instructions, system prompts in hidden text, etc.). Ported from gsd-browser's heuristic scanner (MIT/Apache).

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

Returns severity-ranked findings. Intended for pentest-validation, injection-analyst, and aidefence-guardian.

intent-score.js — 15 semantic intents

Heuristic-scored element discovery — no LLM round-trip. Ported from gsd-browser's 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

Intents: 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.

Returns top 5 candidates with scores and selectors. Useful for dismissing cookie banners, finding login forms, and navigating through wizards without having to map the whole page.

Common QE Patterns

Pattern 1 — Visual regression in 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

Pattern 2 — E2E flow with explicit assertions

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

Pattern 3 — Accessibility audit without axe round-trip

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

Pattern 4 — Auth state reuse

# 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

Pattern 5 — Pentest exploit validation

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

Pattern 6 — Semantic cookie banner dismissal

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 Integration

Vibium ships its own MCP server. Use via:

claude mcp add vibium -- npx -y vibium mcp

When Vibium MCP tools are available (mcp__vibium__*), prefer them over shell-out for the core navigate/map/click/fill operations. Continue to use this skill's scripts/ for the QE-specific primitives (assertions, batch, visual-diff, injection, intents) — they are not part of Vibium.

Fallback Policy

If vibium is not installed (e.g., aqe init hasn't run or user opted out), the qe-browser helper scripts implement the contract automatically. You don't have to grep error strings. Each script:

1. Catches the VibiumUnavailableError thrown by lib/vibium.js when the binary isn't on PATH
2. Emits a structured skipped envelope (see Output Contract below) with vibiumUnavailable: true at the top level and output.reason: "browser-engine-unavailable"
3. Exits with exit code 2 (skipped, distinct from 0=success and 1=failed)
4. Never silently falls back to Playwright or puppeteer-extra

Downstream skills that shell out to these helpers can branch on the structured fields:

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

Or in 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 };
}

Migration from Playwright

If you have an existing Playwright test:

// 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/);

Becomes:

# 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"}
]'

Full migration guide: references/migration-from-playwright.md.

Output Contract

All scripts emit a structured JSON envelope. There are three valid status values:

success (exit code 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 (exit code 1)

Same shape; status: "failed" indicates a genuine assertion failure or operation error. The output.* block carries the per-check details.

skipped (exit code 2) — F1 contract

Emitted when vibium is not installed on PATH. Top-level vibiumUnavailable: true is the canonical signal for downstream skills.

{
  "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 }
}

Exit code summary

| Exit | Status | Meaning | |------|-------------|-----------------------------------------------------------| | 0 | success | every assertion passed / operation completed | | 1 | failed | genuine assertion failure or operation error | | 2 | skipped | vibium unavailable; environment problem, not a test result |

CI tooling can use the exit code to distinguish "test legitimately failed" (block the build) from "we couldn't run the test because the browser engine isn't installed" (warn but don't block).

Validate with scripts/validate-config.json + schemas/output.json.

Attribution

• Prompt-injection scanner and intent-scoring logic ported from gsd-browser (MIT/Apache-2.0).
• Engine: Vibium (Apache-2.0).