/qe-browser

name: "qe-browser"
description: "Browser automation for QE agents using Vibium (WebDriver BiDi) with assertions, batch execution, visual diff, prompt-injection scanning, and semantic intents. Use when any QE skill needs to drive a real browser — visual testing, accessibility audits, E2E flow verification, pentest validation, or exploratory testing."
trust_tier: 3
validation:
  schema_path: schemas/output.json
  validator_path: scripts/validate-config.json
  eval_path: evals/qe-browser.yaml

QE Browser

Thin AQE-owned wrapper around [Vibium](https://github.com/VibiumDev/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/scr