@matware/e2e-runner 1.3.0 → 1.5.0

package/README.md

@@ -9,12 +9,16 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/npm/v/@matware/e2e-runner?color=blue" alt="npm version" />
+  <a href="https://www.npmjs.com/package/@matware/e2e-runner"><img src="https://img.shields.io/npm/v/@matware/e2e-runner?color=blue" alt="npm version" /></a>
   <img src="https://img.shields.io/node/v/@matware/e2e-runner" alt="node version" />
-  <img src="https://img.shields.io/npm/l/@matware/e2e-runner" alt="license" />
+  <a href="https://www.npmjs.com/package/@matware/e2e-runner"><img src="https://img.shields.io/npm/dm/@matware/e2e-runner" alt="npm downloads" /></a>
+  <a href="https://hub.docker.com/r/fastslack/e2e-runner-mcp"><img src="https://img.shields.io/docker/pulls/fastslack/e2e-runner-mcp" alt="Docker pulls" /></a>
+  <a href="https://github.com/fastslack/mtw-e2e-runner/stargazers"><img src="https://img.shields.io/github/stars/fastslack/mtw-e2e-runner" alt="GitHub stars" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@matware/e2e-runner" alt="license" /></a>
   <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP compatible" />
   <img src="https://img.shields.io/badge/AI--native-Claude%20Code-blueviolet" alt="AI native" />
   <img src="https://img.shields.io/badge/AI--native-OpenCode-orange" alt="OpenCode compatible" />
+  <a href="https://skills.sh"><img src="https://img.shields.io/badge/skills.sh-e2e--testing-ff6600" alt="Agent Skills" /></a>
 </p>
 
 <p align="center">
@@ -27,7 +31,7 @@
 
 But what makes it truly different is its **deep AI integration**. With a built-in [MCP server](https://modelcontextprotocol.io/), Claude Code can create tests from a conversation, run them, read the results, capture screenshots, and even visually verify that pages look correct — all without leaving the chat. Paste a GitHub issue URL and get a runnable test back. That's the workflow.
 
-### This is a test
+### A test is just JSON
 
 ```json
 [
@@ -45,200 +49,89 @@ But what makes it truly different is its **deep AI integration**. With a built-i
 ]
 ```
 
-No imports. No `describe`/`it`. No compilation step. Just a JSON file that describes what a user does — and the runner makes it happen.
+You describe what a user does — click this, type that, check the page says X — and the runner does it in a real browser. No imports, no `describe`/`it`, no build step. If you can read it, you can write it.
 
 ---
 
-## Getting Started
-
-### Prerequisites
-
-- **Node.js** >= 20
-- **Docker** running (for the Chrome pool)
-- Your app running on a known port (e.g. `http://localhost:3000`)
-
-> **Why `host.docker.internal`?**
->
-> Chrome runs inside a Docker container. From inside the container, `localhost` refers to the container itself — not your machine. The special hostname `host.docker.internal` resolves to your host machine, so Chrome can reach your locally running app.
->
-> The default `baseUrl` is `http://host.docker.internal:3000`. If your app runs on a different port, change it in `e2e.config.js` after init.
->
-> **Linux note:** On Docker Engine (not Docker Desktop), you may need to add `--add-host=host.docker.internal:host-gateway` to the Docker run flags, or use your machine's LAN IP directly as the `baseUrl`.
+## Agent Skills
 
----
-
-### Path A: With Claude Code
-
-If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code), this is the fastest path — Claude handles test creation and debugging for you.
-
-**1. Install the package**
+Install E2E testing skills for any coding agent (Claude Code, Cursor, Codex, Copilot, and [40+ more](https://github.com/vercel-labs/skills#supported-agents)):
 
 ```bash
-npm install --save-dev @matware/e2e-runner
-```
-
-**2. Scaffold the project structure**
-
-```bash
-npx e2e-runner init
-```
-
-This creates `e2e/tests/` with a sample test and `e2e/screenshots/` for captures.
-
-**3. Configure your base URL**
-
-Edit `e2e.config.js` and set `baseUrl` to match your app's port:
-
-```js
-export default {
-  baseUrl: 'http://host.docker.internal:3000', // change 3000 to your port
-};
-```
-
-**4. Start the Chrome pool**
-
-```bash
-npx e2e-runner pool start
-```
-
-You should see:
-
-```
-✓ Chrome pool started on port 3333 (max 3 sessions)
-```
-
-**5. Install the Claude Code plugin**
-
-```bash
-# Add the marketplace (one-time)
-claude plugin marketplace add fastslack/mtw-e2e-runner
-
-# Install the plugin
-claude plugin install e2e-runner@matware
+npx skills add fastslack/mtw-e2e-runner
 ```
 
-The plugin gives Claude 13 MCP tools, a workflow skill, 3 slash commands, and 3 specialized agents.
+This gives your agent the knowledge to create, run, and debug JSON-driven E2E tests — no documentation reading required.
 
-**6. Ask Claude to run the sample test**
-
-In Claude Code, just say:
-
-> "Run all E2E tests"
-
-Claude will check the pool, run the sample test, and report back:
-
-```
-==================================================
-  E2E RESULTS
-==================================================
-  Total:    1
-  Passed:   1
-  Failed:   0
-  Rate:     100.00%
-  Duration: 1.23s
-==================================================
-```
-
-From here, you can ask Claude to create new tests ("test the login flow"), debug failures, or verify GitHub issues.
+> Browse all available skills at [skills.sh](https://skills.sh)
 
 ---
 
-### Path B: CLI Only
+## Getting Started
 
-No AI required — use the runner directly from your terminal.
+You need just two things: **Node.js 20+** and **Docker running**. You don't install any browser — the runner spins up Chrome in a container for you.
 
-**1. Install the package**
+### Try it in 60 seconds
 
 ```bash
 npm install --save-dev @matware/e2e-runner
+npx e2e-runner init        # scaffolds e2e/ with a sample test + config
+npx e2e-runner run --all   # runs it — Chrome starts automatically on first run
 ```
 
-**2. Scaffold the project structure**
+That's the whole setup. No separate `pool start`, no browser download: the first run boots the Chrome pool for you and reuses it afterwards.
 
-```bash
-npx e2e-runner init
-```
+> Prefer a single command? `curl -fsSL https://raw.githubusercontent.com/fastslack/mtw-e2e-runner/main/scripts/quickstart.sh | bash`
 
-This creates `e2e/tests/` with a sample test and `e2e/screenshots/` for captures.
+### Point it at your app
 
-**3. Configure your base URL**
-
-Edit `e2e.config.js` and set `baseUrl` to match your app's port:
+`init` created `e2e.config.js`. Set your app's URL there:
 
 ```js
 export default {
-  baseUrl: 'http://host.docker.internal:3000', // change 3000 to your port
+  baseUrl: 'http://host.docker.internal:3000', // ← change 3000 to your app's port
 };
 ```
 
-**4. Start the Chrome pool**
+<details>
+<summary><strong>Why <code>host.docker.internal</code> instead of <code>localhost</code>?</strong></summary>
 
-```bash
-npx e2e-runner pool start
-```
+Chrome runs inside Docker, so `localhost` there points at the container, not your machine. `host.docker.internal` bridges to your host. On Linux (Docker Engine, not Docker Desktop) you may need to add `--add-host=host.docker.internal:host-gateway`, or just use your machine's LAN IP.
+</details>
 
-You should see:
+### Write your first test
 
-```
-✓ Chrome pool started on port 3333 (max 3 sessions)
-```
-
-**5. Run the sample test**
-
-```bash
-npx e2e-runner run --all
-```
-
-Expected output:
-
-```
-==================================================
-  E2E RESULTS
-==================================================
-  Total:    1
-  Passed:   1
-  Failed:   0
-  Rate:     100.00%
-  Duration: 1.23s
-==================================================
-```
-
-A screenshot is saved at `e2e/screenshots/homepage.png`.
-
-**6. Write your first real test**
-
-Create `e2e/tests/my-first-test.json`:
+Open `e2e/tests/sample.json` and describe a flow as a list of actions:
 
 ```json
 [
-  {
-    "name": "homepage-visible",
-    "actions": [
-      { "type": "goto", "value": "/" },
-      { "type": "assert_visible", "selector": "body" },
-      { "type": "screenshot", "value": "my-first-test.png" }
-    ]
-  }
+  { "name": "homepage loads", "actions": [
+    { "type": "goto", "value": "/" },
+    { "type": "assert_text", "text": "Welcome" },
+    { "type": "screenshot", "value": "home.png" }
+  ]}
 ]
 ```
 
-Run it:
+Then `npx e2e-runner run --all` again. Pass/fail, timing, screenshots, and network errors print to your terminal — and to the [web dashboard](#web-dashboard) if it's open.
+
+### Add Claude Code (optional)
 
 ```bash
-npx e2e-runner run --suite my-first-test
+claude plugin marketplace add fastslack/mtw-e2e-runner
+claude plugin install e2e-runner@matware
 ```
 
----
-
-### One-liner quickstart
+This gives Claude 17 MCP tools, slash commands, and specialized agents. Just say *"Run all E2E tests"* or *"Create a test for the login flow"*.
 
-If you want to skip the step-by-step and get everything running in one command:
+### Add OpenCode (optional)
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/fastslack/mtw-e2e-runner/main/scripts/quickstart.sh | bash
+cp node_modules/@matware/e2e-runner/opencode.json ./
+mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/
 ```
 
-> This installs the package, scaffolds the project, and starts the Chrome pool. You'll still need to configure your `baseUrl` afterwards.
+See [OPENCODE.md](OPENCODE.md) for details.
 
 ### What's next?
 
@@ -254,7 +147,7 @@ curl -fsSL https://raw.githubusercontent.com/fastslack/mtw-e2e-runner/main/scrip
 
 🧪 **Zero-code tests** — JSON files that anyone on your team can read and write. No JavaScript, no compilation, no framework lock-in.
 
-🤖 **AI-powered testing** — Claude Code creates, executes, and debugs tests natively through 13 MCP tools. Ask it to "test the checkout flow" and it builds the JSON, runs it, and reports back.
+🤖 **AI-powered testing** — Claude Code creates, executes, and debugs tests natively through 17 MCP tools. Ask it to "test the checkout flow" and it builds the JSON, runs it, and reports back.
 
 🐛 **Issue-to-Test pipeline** — Paste a GitHub or GitLab issue URL. The runner fetches it, generates E2E tests, runs them, and tells you: *bug confirmed* or *not reproducible*.
 
@@ -262,7 +155,9 @@ curl -fsSL https://raw.githubusercontent.com/fastslack/mtw-e2e-runner/main/scrip
 
 🧠 **Learning system** — Tracks test stability across runs. Detects flaky tests, unstable selectors, slow APIs, and error patterns — then surfaces actionable insights.
 
-⚡ **Parallel execution** — Run N tests simultaneously against a shared Chrome pool (browserless/chrome). Serial mode available for tests that share state.
+⚡ **Parallel execution** — Run N tests simultaneously against a shared browser pool (browserless, raw CDP, Lightpanda, Obscura, or Steel). Serial mode available for tests that share state.
+
+🎯 **Pluggable browser drivers** — Pick the engine that fits each test: real Chrome via browserless, Lightpanda or Obscura for fast lightweight runs, Steel for managed sessions. Set `driver` per test or override the whole run with `--driver`.
 
 📊 **Real-time dashboard** — Live execution view, run history with pass-rate charts, screenshot gallery with hash-based search, expandable network request logs.
 
@@ -303,9 +198,9 @@ Suite files can have numeric prefixes for ordering (`01-auth.json`, `02-dashboar
 | Action | Fields | Description |
 |--------|--------|-------------|
 | `goto` | `value` | Navigate to URL (relative to `baseUrl` or absolute) |
-| `click` | `selector` or `text` | Click by CSS selector or visible text content |
+| `click` | `selector` or `text` | Click by CSS selector or visible text content. Text mode also takes `scope: "dialog"`, `visible: true`, `last: true` |
 | `type` / `fill` | `selector`, `value` | Clear field and type text |
-| `wait` | `selector`, `text`, or `value` (ms) | Wait for element, text, or fixed delay |
+| `wait` | `selector`, `text`, `gone`, or `value` (ms) | Wait for element/text to appear, for `gone` to disappear (spinner/dialog), or fixed delay. Prefer conditions over fixed `value` sleeps |
 | `screenshot` | `value` (filename) | Capture a screenshot |
 | `select` | `selector`, `value` | Select a dropdown option |
 | `clear` | `selector` | Clear an input field |
@@ -352,9 +247,10 @@ These actions handle common patterns in React/MUI apps that normally require ver
 
 | Action | Fields | Description |
 |--------|--------|-------------|
-| `type_react` | `selector`, `value` | Type into React controlled inputs using the native value setter. Dispatches `input` + `change` events so React state updates correctly. |
+| `type_react` | `selector`, `value`, optional `blur`, `waitAfter` | Type into React controlled inputs using the native value setter. Dispatches `input` + `change` events so React state updates correctly. `blur: true` commits on blur; `waitAfter: "<ms>"` waits after (debounced autocomplete). |
 | `click_regex` | `text` (regex), optional `selector`, optional `value: "last"` | Click element whose textContent matches a regex (case-insensitive). Default: first match. Use `value: "last"` for last match. |
 | `click_option` | `text` | Click a `[role="option"]` element by text — common in autocomplete/select dropdowns. |
+| `select_combobox` | `text`, optional `selector`, `filter`, `openWait`/`filterWait`/`waitAfter` | Open a MUI Autocomplete/Select, optionally type `filter`, then click the option matching `text`. Falls back across `[role="option"]`, `.MuiAutocomplete-option`, `li.MuiMenuItem-root`. |
 | `focus_autocomplete` | `text` (label text) | Focus an autocomplete input by its label text. Supports MUI and generic `[role="combobox"]`. |
 | `click_chip` | `text` | Click a chip/tag element by text. Searches `[class*="Chip"]`, `[class*="chip"]`, `[data-chip]`. |
 
@@ -408,11 +304,7 @@ Serial tests run one at a time **after** all parallel tests finish — preventin
 
 ## Testing Authenticated Apps
 
-Most real-world apps require login before tests can interact with protected pages. E2E Runner provides multiple strategies — choose the one that matches your app's auth mechanism.
-
-### Strategy 1: UI Login Flow (any app)
-
-The most universal approach — fill in the login form like a real user. Works with **any** authentication system (session cookies, JWT, OAuth redirect, etc.):
+The simplest approach — log in via the UI like a real user:
 
 ```json
 {
@@ -425,279 +317,29 @@ The most universal approach — fill in the login form like a real user. Works w
       { "type": "wait", "selector": ".dashboard" }
     ]
   },
-  "tests": [
-    {
-      "name": "profile-page",
-      "actions": [
-        { "type": "goto", "value": "/profile" },
-        { "type": "assert_text", "text": "My Profile" }
-      ]
-    }
-  ]
-}
-```
-
-> **When to use:** You don't know or care how auth works internally. The browser handles cookies/tokens automatically after login — just like a real user.
-
-### Strategy 2: JWT Token Injection (SPAs)
-
-For single-page apps that store JWT tokens in `localStorage` or `sessionStorage`. Skip the login form entirely by injecting the token directly:
-
-```json
-{
-  "hooks": {
-    "beforeEach": [
-      { "type": "goto", "value": "/" },
-      { "type": "set_storage", "value": "accessToken=eyJhbGciOiJIUzI1NiIs..." },
-      { "type": "goto", "value": "/dashboard" },
-      { "type": "wait", "selector": ".dashboard-loaded" }
-    ]
-  },
   "tests": [...]
 }
 ```
 
-**Common storage key names** (depends on your app):
-
-| Framework / Library | Typical key | Storage |
-|---------------------|-------------|---------|
-| Custom JWT | `accessToken`, `token`, `jwt` | localStorage |
-| Auth0 SPA SDK | `@@auth0spajs@@::*` | localStorage |
-| Firebase Auth | `firebase:authUser:*` | localStorage |
-| AWS Amplify | `CognitoIdentityServiceProvider.*` | localStorage |
-| Supabase | `sb-<ref>-auth-token` | localStorage |
-| NextAuth (client) | `next-auth.session-token` | cookie (see Strategy 4) |
-
-**Using `sessionStorage` instead:**
-
-```json
-{ "type": "set_storage", "value": "token=eyJhbG...", "selector": "session" }
-```
-
-**Asserting the token was stored correctly:**
+For SPAs with JWT, skip the login form by injecting the token directly:
 
 ```json
-{ "type": "assert_storage", "value": "accessToken" }
-{ "type": "assert_storage", "value": "accessToken=eyJhbG..." }
+{ "type": "set_storage", "value": "accessToken=eyJhbGciOiJIUzI1NiIs..." }
 ```
 
-> **When to use:** Your SPA reads auth tokens from browser storage. Fastest strategy — no network round-trip for login.
-
-### Strategy 3: Config-Level Auth Token
-
-For apps where every test needs the same JWT token. Set it once in config — it's injected into `localStorage` before every `e2e_capture` and `e2e_issue --verify` run:
+Or set it globally in config:
 
 ```js
 // e2e.config.js
 export default {
   authToken: 'eyJhbGciOiJIUzI1NiIs...',
-  authStorageKey: 'accessToken',  // default
+  authStorageKey: 'accessToken',
 };
 ```
 
-Or via environment variables:
-
-```bash
-AUTH_TOKEN="eyJhbGciOiJIUzI1NiIs..." npx e2e-runner run --all
-```
-
-Or via CLI:
-
-```bash
-npx e2e-runner run --all --auth-token "eyJhbG..." --auth-storage-key "jwt"
-```
-
-MCP tools (`e2e_capture`, `e2e_issue`) also accept `authToken` and `authStorageKey` per call.
-
-> **When to use:** All tests share the same user session and your app uses JWT in localStorage.
-
-### Strategy 4: Cookie-Based Auth (server-rendered apps)
-
-For apps that use HTTP cookies (Rails, Django, Laravel, Express sessions, NextAuth, etc.). Use `evaluate` to set cookies before navigating:
-
-```json
-{
-  "hooks": {
-    "beforeEach": [
-      { "type": "goto", "value": "/" },
-      { "type": "evaluate", "value": "document.cookie = 'session_id=abc123; path=/; SameSite=Lax'" },
-      { "type": "goto", "value": "/dashboard" }
-    ]
-  },
-  "tests": [...]
-}
-```
-
-**Multiple cookies:**
-
-```json
-{ "type": "evaluate", "value": "document.cookie = 'session_id=abc123; path=/'; document.cookie = '_csrf_token=xyz789; path=/'" }
-```
-
-**For `HttpOnly` cookies** (can't be set via JavaScript), use the UI login strategy instead — the browser will store them automatically.
-
-> **When to use:** Traditional server-rendered apps, or any app that authenticates via cookies.
-
-### Strategy 5: HTTP Header Auth (API tests)
-
-For API testing where you need to send `Authorization` headers with every request. Use `evaluate` to override `fetch`/`XMLHttpRequest`:
-
-```json
-{
-  "hooks": {
-    "beforeEach": [
-      { "type": "goto", "value": "/" },
-      { "type": "evaluate", "value": "const origFetch = window.fetch; window.fetch = (url, opts = {}) => { opts.headers = { ...opts.headers, 'Authorization': 'Bearer eyJhbG...' }; return origFetch(url, opts); }" }
-    ]
-  },
-  "tests": [
-    {
-      "name": "api-returns-user",
-      "actions": [
-        { "type": "evaluate", "value": "const res = await fetch('/api/me'); const data = await res.json(); if (data.email !== 'test@example.com') throw new Error('Wrong user: ' + data.email)" }
-      ]
-    }
-  ]
-}
-```
+Each test runs in a **fresh browser context**, so auth state is automatically clean between tests.
 
-> **When to use:** API-level tests (with `--test-type api`) that need auth headers.
-
-### Strategy 6: OAuth / SSO (external provider)
-
-OAuth flows redirect to external providers (Google, GitHub, Okta, etc.) which can't be automated reliably. Common workarounds:
-
-**Option A — Test environment bypass:** Most apps have a direct login endpoint for testing that skips OAuth:
-
-```json
-{ "type": "goto", "value": "/auth/test-login?user=test@example.com" }
-```
-
-**Option B — Pre-authenticated token:** Get a token from your auth provider's API and inject it:
-
-```json
-{
-  "hooks": {
-    "beforeEach": [
-      { "type": "goto", "value": "/" },
-      { "type": "set_storage", "value": "oidc.user:https://auth.example.com:client_id={\"access_token\":\"...\"}" }
-    ]
-  }
-}
-```
-
-**Option C — Session cookie from CI:** If your CI can authenticate via API, pass the session cookie as an env var:
-
-```bash
-SESSION=$(curl -s -c - https://api.example.com/auth/login -d '{"email":"test@example.com","password":"secret"}' | grep session_id | awk '{print $NF}')
-AUTH_TOKEN="$SESSION" AUTH_STORAGE_KEY="session_id" npx e2e-runner run --all
-```
-
-> **When to use:** Apps with Google/GitHub/Okta/Auth0 login. You almost always need a test-environment backdoor.
-
-### Reusable Auth Modules
-
-Extract your auth strategy into a module so every test can reference it without duplication:
-
-```json
-// e2e/modules/login.json — UI login (universal)
-{
-  "$module": "login",
-  "description": "Log in via the UI login form",
-  "params": {
-    "email": { "required": true, "description": "User email" },
-    "password": { "required": true, "description": "User password" },
-    "redirectTo": { "default": "/dashboard", "description": "Page to land on after login" }
-  },
-  "actions": [
-    { "type": "goto", "value": "/login" },
-    { "type": "type", "selector": "#email", "value": "{{email}}" },
-    { "type": "type", "selector": "#password", "value": "{{password}}" },
-    { "type": "click", "text": "Sign In" },
-    { "type": "wait", "selector": "{{redirectTo}}" }
-  ]
-}
-```
-
-```json
-// e2e/modules/auth-token.json — JWT injection (SPAs)
-{
-  "$module": "auth-token",
-  "description": "Inject an auth token into browser storage",
-  "params": {
-    "token": { "required": true, "description": "JWT or session token" },
-    "storageKey": { "default": "accessToken", "description": "Storage key name" },
-    "storage": { "default": "local", "description": "local or session" },
-    "redirectTo": { "default": "/dashboard", "description": "Page to navigate to after injection" }
-  },
-  "actions": [
-    { "type": "goto", "value": "/" },
-    { "type": "set_storage", "value": "{{storageKey}}={{token}}", "selector": "{{#storage}}{{storage}}{{/storage}}" },
-    { "type": "goto", "value": "{{redirectTo}}" }
-  ]
-}
-```
-
-Use in tests:
-
-```json
-// UI login
-{ "$use": "login", "params": { "email": "admin@test.com", "password": "secret" } }
-
-// Token injection
-{ "$use": "auth-token", "params": { "token": "eyJhbG..." } }
-
-// Token in sessionStorage, redirect to /settings
-{ "$use": "auth-token", "params": { "token": "eyJhbG...", "storage": "session", "redirectTo": "/settings" } }
-```
-
-### Testing Different User Roles
-
-Use separate tests (or the same module with different credentials) to test role-based access:
-
-```json
-[
-  {
-    "name": "admin-sees-settings",
-    "actions": [
-      { "$use": "login", "params": { "email": "admin@test.com", "password": "admin-pass" } },
-      { "type": "goto", "value": "/settings" },
-      { "type": "assert_visible", "selector": ".admin-panel" }
-    ]
-  },
-  {
-    "name": "viewer-cannot-access-settings",
-    "actions": [
-      { "$use": "login", "params": { "email": "viewer@test.com", "password": "viewer-pass" } },
-      { "type": "goto", "value": "/settings" },
-      { "type": "assert_text", "text": "Access Denied" }
-    ]
-  }
-]
-```
-
-### Clearing Auth State
-
-Each test runs in a **fresh browser context** (new connection to the Chrome pool), so cookies and storage are automatically clean. If you need to explicitly clear state mid-test:
-
-```json
-{ "type": "clear_cookies" }
-```
-
-This clears cookies, localStorage, and sessionStorage for the current origin.
-
-### Quick Reference
-
-| Auth type | Strategy | Key actions |
-|-----------|----------|-------------|
-| Username/password form | UI Login | `goto` + `type` + `click` in `beforeEach` |
-| JWT in localStorage | Token Injection | `set_storage` in `beforeEach` |
-| JWT in sessionStorage | Token Injection | `set_storage` with `selector: "session"` |
-| Session cookies | Cookie | `evaluate` to set `document.cookie` |
-| HttpOnly cookies | UI Login | Must go through login form |
-| OAuth / SSO | Test bypass | App-specific test login endpoint |
-| API auth headers | Header Override | `evaluate` to patch `fetch` |
-| Config-level token | Config | `authToken` + `authStorageKey` in config |
+> **More strategies:** Cookie-based auth, HTTP header injection, OAuth/SSO bypasses, reusable auth modules, and role-based testing — see [docs/authentication.md](docs/authentication.md)
 
 ---
 
@@ -892,152 +534,132 @@ Monitor Chrome pool health: available slots, running sessions, memory pressure.
 
 ---
 
-## Screenshot Capture
+## Browser Drivers
 
-Capture screenshots of any URL on demand — no test suite required:
+The runner can talk to multiple browser engines through different drivers. The default is **`auto`** — it probes each pool URL and picks the right driver per pool.
 
-```bash
-e2e-runner capture https://example.com
-e2e-runner capture https://example.com --full-page --selector ".loaded" --delay 2000
-```
+| Driver | Engine | Detection probe | When to use |
+|--------|--------|-----------------|-------------|
+| `browserless` | Real Chromium via [browserless](https://www.browserless.io/) | `/pressure` returns JSON | Default. Production-grade JS execution, screencast, full Chrome behavior |
+| `cdp` | Generic CDP-compatible (raw Chrome, etc.) | `/json/version` reachable | Fallback for any CDP server that isn't one of the others |
+| `lightpanda` | [Lightpanda](https://lightpanda.io) (Zig) | `/json/version` Browser=lightpanda | ~9× faster, ~16× less memory than headless Chrome — ideal for high-volume scrape-style tests |
+| `obscura` | [Obscura](https://github.com/h4ckf0r0day/obscura) (Rust + V8) | `/json/version` Browser=obscura | ~30 MB RAM footprint, built-in anti-detection (`--stealth`), stays close to real Chrome via Puppeteer |
+| `steel` | [Steel Browser](https://steel.dev) | `/v1/sessions` returns JSON | Managed session lifecycle, REST API for orchestration |
 
-Via MCP, the `e2e_capture` tool supports `authToken` and `authStorageKey` for authenticated pages — it injects the token into localStorage before navigating.
+### Pick a driver per test
 
-Every screenshot gets a deterministic hash (`ss:a3f2b1c9`). Use `e2e_screenshot` to retrieve any screenshot by hash — it returns the image with metadata (test name, step, type).
+```json
+{
+  "tests": [
+    {
+      "name": "checkout flow (heavy JS, real Chrome)",
+      "driver": "browserless",
+      "actions": [...]
+    },
+    {
+      "name": "scrape product page (lightweight)",
+      "driver": "obscura",
+      "fallbackDriver": "cdp",
+      "actions": [...]
+    }
+  ]
+}
+```
 
----
+`driver` is optional. If set, only pools whose detected driver matches become candidates. `fallbackDriver` is **explicit opt-in** — without it, a missing target driver fails the test with a clear message. Pool busyness does **not** trigger fallback; the runner waits inside the filtered set.
 
-## Claude Code Integration
+### Force a driver for a whole run
 
-The package ships as a **Claude Code plugin** — a single install that gives Claude native access to the test runner, teaches it the optimal workflow, and adds slash commands and specialized agents.
+```bash
+e2e-runner run --all --driver obscura
+e2e-runner run --all --driver obscura --fallback-driver cdp
+```
 
-### Install as Plugin (recommended)
+CLI overrides win over per-test fields — useful for A/B benchmarks against the same suite.
+
+### Running each driver locally
 
 ```bash
-# 1. Add the marketplace (one-time)
-claude plugin marketplace add fastslack/mtw-e2e-runner
+# browserless (default) — managed by `pool start`
+e2e-runner pool start
 
-# 2. Install the plugin
-claude plugin install e2e-runner@matware
-```
+# Lightpanda — pool start uses templates/docker-compose-lightpanda.yml
+e2e-runner pool start                 # with poolDriver: 'lightpanda' in config
 
-**What you get:**
+# Obscura — install the binary and run it yourself
+curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
+tar xzf obscura-x86_64-linux.tar.gz
+./obscura serve --port 9222 --stealth
+# then point the runner at it: poolUrls: ['http://localhost:9222'], poolDriver: 'obscura'
+```
 
-| Component | Description |
-|-----------|-------------|
-| **13 MCP tools** | Run tests, create test files, capture screenshots, query network logs, manage dashboard, verify issues, query learnings |
-| **Skill** | Teaches Claude the full e2e-runner workflow — how to combine tools, interpret results, debug failures, create tests |
-| **3 Commands** | `/e2e-runner:run` — run & analyze tests<br>`/e2e-runner:create-test` — explore UI and create tests<br>`/e2e-runner:verify-issue <url>` — verify GitHub/GitLab bugs |
-| **3 Agents** | **test-analyzer** — diagnoses failures, analyzes flaky tests, drills into network errors<br>**test-creator** — explores UI, discovers selectors, designs and validates tests<br>**test-improver** — refactors verbose evaluate actions, extracts modules, adds waits/retries, eliminates hardcoded delays |
+---
 
-### Install MCP-only (alternative)
+## Screenshot Capture
 
-If you only want the 13 MCP tools without skills, commands, or agents:
+Capture screenshots of any URL on demand — no test suite required:
 
 ```bash
-claude mcp add --transport stdio --scope user e2e-runner \
-  -- npx -y -p @matware/e2e-runner e2e-runner-mcp
+e2e-runner capture https://example.com
+e2e-runner capture https://example.com --full-page --selector ".loaded" --delay 2000
 ```
 
-### Slash Commands
-
-| Command | Description |
-|---------|-------------|
-| `/e2e-runner:run` | Check pool, list suites, run tests, analyze results with screenshots and network drill-down |
-| `/e2e-runner:create-test` | Explore the UI with screenshots, find selectors in source code, design test actions, create and validate |
-| `/e2e-runner:verify-issue <url>` | Fetch a GitHub/GitLab issue, create tests that verify correct behavior, report bug confirmed or not reproducible |
-
-### MCP Tools
+Via MCP, the `e2e_capture` tool supports `authToken` and `authStorageKey` for authenticated pages — it injects the token into localStorage before navigating.
 
-| Tool | Description |
-|------|-------------|
-| `e2e_run` | Run tests: all suites, by name, or by file. Supports `concurrency`, `baseUrl`, `retries`, `failOnNetworkError` overrides. Returns verification results if tests have `expect`. |
-| `e2e_list` | List available test suites with test names and counts |
-| `e2e_create_test` | Create a new test JSON file with name, tests, and optional hooks |
-| `e2e_create_module` | Create a reusable module with parameterized actions |
-| `e2e_pool_status` | Check Chrome pool availability, running sessions, capacity |
-| `e2e_screenshot` | Retrieve a screenshot by hash (`ss:a3f2b1c9`). Returns image + metadata |
-| `e2e_capture` | Capture screenshot of any URL. Supports `authToken`, `fullPage`, `selector`, `delay` |
-| `e2e_dashboard_start` | Start the web dashboard |
-| `e2e_dashboard_stop` | Stop the web dashboard |
-| `e2e_issue` | Fetch GitHub/GitLab issue and generate tests. `mode: "prompt"` or `mode: "verify"` |
-| `e2e_network_logs` | Query network request/response logs by `runDbId`. Filter by test name, method, status, URL pattern. Supports headers and bodies |
-| `e2e_learnings` | Query the learning system: `summary`, `flaky`, `selectors`, `pages`, `apis`, `errors`, `trends` |
-| `e2e_neo4j` | Manage Neo4j knowledge graph container: `start`, `stop`, `status` |
-
-> **Note:** Pool start/stop are CLI-only (`e2e-runner pool start|stop`) — not exposed via MCP to prevent killing active sessions.
-
-### What You Can Ask Claude Code
-
-> "Run all E2E tests"
-> "Create a test that verifies the checkout flow"
-> "What tests are flaky? Show me the learning summary"
-> "Capture a screenshot of /dashboard with auth"
-> "Fetch issue #42 and create tests for it"
-> "What's the API error rate for the last 7 days?"
+Every screenshot gets a deterministic hash (`ss:a3f2b1c9`). Use `e2e_screenshot` to retrieve any screenshot by hash — it returns the image with metadata (test name, step, type).
 
 ---
 
-## OpenCode Integration
-
-The package also supports [OpenCode](https://github.com/anomalyco/opencode) with native MCP server configuration, skills, and commands.
+## AI Integration
 
-### Quick Setup
+### Claude Code
 
 ```bash
-# 1. Install the package
-npm install --save-dev @matware/e2e-runner
-
-# 2. Copy OpenCode config to your project
-cp node_modules/@matware/e2e-runner/opencode.json ./
-
-# 3. Copy skills and commands (optional)
-mkdir -p .opencode
-cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/
-
-# 4. Start the Chrome pool
-npx e2e-runner pool start
+claude plugin marketplace add fastslack/mtw-e2e-runner
+claude plugin install e2e-runner@matware
 ```
 
-### What's Included
+This gives Claude 17 MCP tools, a workflow skill, 4 slash commands (`/e2e-runner:run`, `/e2e-runner:create-test`, `/e2e-runner:verify-issue`, `/e2e-runner:capture`), and 3 specialized agents (test-analyzer, test-creator, test-improver).
 
-| Component | Description |
-|-----------|-------------|
-| **15 MCP tools** | Same tools as Claude Code — run tests, create files, screenshots, network logs, learnings, etc. |
-| **Skill** | `e2e-testing` — full workflow guidance with references |
-| **3 Commands** | `/run`, `/create-test`, `/verify-issue` |
+**MCP-only install** (tools only, no skill/commands/agents):
 
-### MCP Configuration
+```bash
+claude mcp add --transport stdio --scope user e2e-runner \
+  -- npx -y -p @matware/e2e-runner e2e-runner-mcp
+```
 
-The `opencode.json` configures the MCP server as a local process:
+### OpenCode
 
-```json
-{
-  "mcp": {
-    "e2e-runner": {
-      "type": "local",
-      "command": "node",
-      "args": ["node_modules/@matware/e2e-runner/bin/mcp-server.js"],
-      "cwd": "${workspaceFolder}"
-    }
-  }
-}
+```bash
+cp node_modules/@matware/e2e-runner/opencode.json ./
+mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/
 ```
 
-For global installation, use the binary directly:
+See [OPENCODE.md](OPENCODE.md) for details.
 
-```json
-{
-  "mcp": {
-    "e2e-runner": {
-      "type": "local",
-      "command": "e2e-runner-mcp"
-    }
-  }
-}
-```
+### MCP Tools
 
-See [OPENCODE.md](OPENCODE.md) for full documentation on OpenCode integration.
+| Tool | Description |
+|------|-------------|
+| `e2e_run` | Run tests (all, by suite, or by file) |
+| `e2e_list` | List available test suites |
+| `e2e_create_test` | Create a new test JSON file |
+| `e2e_create_module` | Create a reusable module |
+| `e2e_pool_status` | Check Chrome pool health |
+| `e2e_app_pool_status` | Inspect the app environment pool (forks, ports, drivers) |
+| `e2e_screenshot` | Retrieve a screenshot by hash |
+| `e2e_capture` | Capture screenshot of any URL |
+| `e2e_analyze` | Extract page structure (interactive elements, forms, headings) and emit test scaffolds |
+| `e2e_dashboard_start` | Start web dashboard |
+| `e2e_dashboard_stop` | Stop web dashboard |
+| `e2e_dashboard_restart` | Restart the dashboard (new project dir/port, clear stale sessions) |
+| `e2e_issue` | Fetch issue and generate tests |
+| `e2e_network_logs` | Query network logs for a run |
+| `e2e_learnings` | Query stability insights |
+| `e2e_vars` | Manage SQLite-backed `{{var.KEY}}` project variables |
+| `e2e_neo4j` | Manage Neo4j knowledge graph |
+
+> Pool start/stop are CLI-only — not exposed via MCP.
 
 ---
 
@@ -1144,6 +766,8 @@ e2e-runner init                       # Scaffold project
 | `--env <name>` | `default` | Environment profile |
 | `--fail-on-network-error` | `false` | Fail tests with network errors |
 | `--project-name <name>` | dir name | Project display name |
+| `--driver <name>` | _(per-test)_ | Force pool driver for the run: `browserless`, `cdp`, `lightpanda`, `obscura`, `steel` |
+| `--fallback-driver <name>` | _none_ | Explicit fallback if no pool with `--driver` is reachable |
 
 ---