@matware/e2e-runner 1.2.1 → 1.3.0

package/commands/create-test.md

@@ -37,11 +37,26 @@ Help the user create a new E2E test file by exploring the application and design
    - Add `wait` actions before assertions on dynamic content
    - Add `assert_no_network_errors` after critical page loads
    - Consider adding an `expect` field for visual verification
+   - **DRY**: If auth/setup is repeated across tests, use `beforeEach` hook (object format) instead of repeating per test
+   - **DRY**: If 3+ tests repeat the same action pattern, create a module with `e2e_create_module` first
 
-7. **Create the test** — Call `e2e_create_test` with the designed test structure. Consider creating reusable modules with `e2e_create_module` for repeated sequences (auth, navigation).
+7. **Create the test** — Call `e2e_create_test` with the designed test structure.
+   - Check existing modules (`e2e/modules/`) — reuse them via `$use` instead of duplicating actions
+   - Create new modules with `e2e_create_module` for repeated sequences (auth, navigation, screenshot patterns)
+   - Use object format `{ "beforeEach": [...], "tests": [...] }` when hooks are needed
 
 8. **Validate** — Run the newly created test with `e2e_run` using the `suite` parameter. Analyze results and iterate if needed.
 
+## Naming Rules (CRITICAL)
+
+Suite names MUST be unique and specific to the feature, issue, or user flow:
+- GOOD: `login-valid-credentials`, `issue-1743-auth-redirect`, `checkout-payment-flow`
+- BAD: `all`, `test`, `debug`, `new`, `temp`, `main`, `suite`
+
+If testing a GitHub/GitLab issue, include the issue number: `issue-1743-auth-timeout`, `bug-502-duplicate-submit`
+
+Before creating, always call `e2e_list` to verify the name doesn't already exist.
+
 ## Arguments
 
 The user may provide:

package/opencode.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/schemas/opencode.json",
+  "mcp": {
+    "e2e-runner": {
+      "type": "local",
+      "command": "node",
+      "args": ["bin/mcp-server.js"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matware/e2e-runner",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "mcpName": "io.github.fastslack/e2e-runner",
   "description": "E2E test runner using Chrome Pool (browserless/chrome) with parallel execution",
   "type": "module",
@@ -20,7 +20,11 @@
     ".mcp.json",
     "skills/",
     "commands/",
-    "agents/"
+    "agents/",
+    ".opencode/",
+    "opencode.json",
+    "OPENCODE.md",
+    "scripts/setup-opencode.sh"
   ],
   "keywords": [
     "e2e",
@@ -31,6 +35,7 @@
     "parallel",
     "mcp",
     "claude-code",
+    "opencode",
     "github-issues",
     "ai-testing"
   ],

package/scripts/setup-opencode.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Setup @matware/e2e-runner for OpenCode
+# Usage: ./setup-opencode.sh [--global]
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_info() { echo -e "${GREEN}✓${NC} $1"; }
+log_warn() { echo -e "${YELLOW}!${NC} $1"; }
+log_error() { echo -e "${RED}✗${NC} $1"; }
+
+# Check if --global flag is passed
+GLOBAL_INSTALL=false
+if [[ "$1" == "--global" ]]; then
+    GLOBAL_INSTALL=true
+fi
+
+if [ "$GLOBAL_INSTALL" = true ]; then
+    echo "Setting up e2e-runner for OpenCode (global)..."
+    
+    # Global config directory
+    OPENCODE_CONFIG="${HOME}/.config/opencode"
+    
+    # Create directories
+    mkdir -p "${OPENCODE_CONFIG}/skills"
+    mkdir -p "${OPENCODE_CONFIG}/commands"
+    
+    # Copy skills
+    if [ -d "${PACKAGE_DIR}/.opencode/skills" ]; then
+        cp -r "${PACKAGE_DIR}/.opencode/skills/"* "${OPENCODE_CONFIG}/skills/"
+        log_info "Installed skills to ${OPENCODE_CONFIG}/skills/"
+    fi
+    
+    # Copy commands
+    if [ -d "${PACKAGE_DIR}/.opencode/commands" ]; then
+        cp -r "${PACKAGE_DIR}/.opencode/commands/"* "${OPENCODE_CONFIG}/commands/"
+        log_info "Installed commands to ${OPENCODE_CONFIG}/commands/"
+    fi
+    
+    echo ""
+    log_warn "To use the MCP server, add this to your project's opencode.json:"
+    echo ""
+    cat << 'EOF'
+{
+  "mcp": {
+    "e2e-runner": {
+      "type": "local",
+      "command": "e2e-runner-mcp"
+    }
+  }
+}
+EOF
+    echo ""
+    
+else
+    echo "Setting up e2e-runner for OpenCode (project-local)..."
+    
+    # Check if we're in the package directory or a project that installed it
+    if [ -f "${PWD}/opencode.json" ] && [ -d "${PWD}/.opencode" ]; then
+        # We're in the package directory
+        log_info "Already in e2e-runner package directory"
+        exit 0
+    fi
+    
+    # Look for node_modules/@matware/e2e-runner
+    if [ -d "${PWD}/node_modules/@matware/e2e-runner" ]; then
+        PACKAGE_DIR="${PWD}/node_modules/@matware/e2e-runner"
+    elif [ ! -f "${PACKAGE_DIR}/package.json" ]; then
+        log_error "Cannot find @matware/e2e-runner package"
+        log_error "Run: npm install @matware/e2e-runner"
+        exit 1
+    fi
+    
+    # Copy opencode.json if it doesn't exist
+    if [ ! -f "${PWD}/opencode.json" ]; then
+        cp "${PACKAGE_DIR}/opencode.json" "${PWD}/opencode.json"
+        log_info "Created opencode.json"
+    else
+        log_warn "opencode.json already exists - merge manually if needed"
+    fi
+    
+    # Copy .opencode directory
+    mkdir -p "${PWD}/.opencode"
+    
+    if [ -d "${PACKAGE_DIR}/.opencode/skills" ]; then
+        mkdir -p "${PWD}/.opencode/skills"
+        cp -r "${PACKAGE_DIR}/.opencode/skills/"* "${PWD}/.opencode/skills/"
+        log_info "Installed skills to .opencode/skills/"
+    fi
+    
+    if [ -d "${PACKAGE_DIR}/.opencode/commands" ]; then
+        mkdir -p "${PWD}/.opencode/commands"
+        cp -r "${PACKAGE_DIR}/.opencode/commands/"* "${PWD}/.opencode/commands/"
+        log_info "Installed commands to .opencode/commands/"
+    fi
+fi
+
+echo ""
+log_info "OpenCode setup complete!"
+echo ""
+echo "Next steps:"
+echo "  1. Start the Chrome pool: npx e2e-runner pool start"
+echo "  2. Restart OpenCode to load the MCP server"
+echo "  3. Ask: 'Run all E2E tests'"
+echo ""

package/skills/e2e-testing/SKILL.md

@@ -85,7 +85,7 @@ Add an `expect` field to any test for AI-powered visual verification:
 ```json
 {
   "name": "dashboard-loads",
-  "expect": "Should show patient list with at least 3 rows and no error messages",
+  "expect": "Should show data table with at least 3 rows and no error messages",
   "actions": [...]
 }
 ```
@@ -162,5 +162,12 @@ Start/stop the web dashboard with `e2e_dashboard_start` / `e2e_dashboard_stop` f
 ## References
 
 - [Action Types Reference](references/action-types.md) — Complete catalog of 28+ action types with fields and examples
-- [Test JSON Format](references/test-json-format.md) — JSON structure, hooks, serial, retries, modules, exclude patterns, environment profiles
-- [Troubleshooting](references/troubleshooting.md) — Common problems and solutions
+- [Test JSON Format](references/test-json-format.md) — JSON structure, hooks, serial, retries, modules, exclude patterns, environment profiles, CI output
+- [GraphQL Action](references/graphql.md) — GQL action config, variables, inline assertions, __e2eGql helper
+- [Authentication Strategies](references/auth-strategies.md) — 6 auth methods + auto-login + reusable auth modules
+- [Network Debugging](references/network-debugging.md) — Error handling, request logging, drill-down pattern
+- [Visual Verification](references/visual-verification.md) — Expect field, double screenshots, strictness levels, verdict format
+- [Multi-Pool Support](references/multi-pool.md) — Config, selection algorithm, failover, pool-aware queue
+- [Variables](references/variables.md) — SQLite-backed variables, syntax, MCP tool, dashboard UI, REST API
+- [Issue Verification](references/issue-verification.md) — GitHub/GitLab, AI modes, test categories, GitLab limitations
+- [Troubleshooting](references/troubleshooting.md) — Common problems, pre-validation, screenshot hashes, dashboard

package/skills/e2e-testing/references/action-types.md

@@ -31,6 +31,21 @@ Complete catalog of all action types supported by @matware/e2e-runner.
 | `focus_autocomplete` | `text` (label text) | Focus an autocomplete input by label. Supports MUI `.MuiAutocomplete-root` and `[role="combobox"]`. |
 | `click_chip` | `text` | Click a chip/tag element by text. Searches `[class*="Chip"]`, `[class*="chip"]`, `[data-chip]`. |
 
+## Storage
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `set_storage` | `value` (`"key=val"`), `selector` (`"session"` optional) | Set a `localStorage` key (default) or `sessionStorage` key (with `selector: "session"`). |
+| `assert_storage` | `value` (`"key"` or `"key=expected"`), `selector` (`"session"` optional) | Without `=`: checks key exists. With `=`: checks exact value match. Uses `localStorage` by default, `sessionStorage` with `selector: "session"`. |
+
+## Smart Interaction
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `click_icon` | `value` (icon identifier), `selector` (scope, optional) | Click an icon by `data-testid`, `data-icon`, `aria-label`, CSS class, or SVG title. Walks up to nearest clickable ancestor (`button`, `a`, `[role="button"]`). Works with MUI, FontAwesome, Heroicons, Bootstrap Icons, Lucide. |
+| `click_menu_item` | `text` (menu item text), `selector` (scope, optional) | Click a menu item by text. Searches `[role="menuitem"]`, `[role="menuitemradio"]`, `[role="menuitemcheckbox"]`, `.dropdown-item`, `.menu-item`, `[class*="MenuItem"]`, `[role="menu"] > li`. Waits for element to appear. |
+| `click_in_context` | `text` (container text), `selector` (child to click) | Find the smallest container whose text includes `text`, then click the `selector` child within it. Containers: `section`, `article`, `[class*="card"]`, `li`, `tr`, `div[class]`, etc. Both fields required. |
+
 ## Assertions
 
 | Action | Fields | Description |
@@ -61,9 +76,21 @@ Complete catalog of all action types supported by @matware/e2e-runner.
 | `get_text` | `selector` | Returns `{ value: textContent.trim() }`. Non-assertion — never fails. |
 | `screenshot` | `value` (filename, optional) | Captures screenshot. Filename gets timestamp suffix for uniqueness. |
 | `wait` | `selector` OR `text` OR `value` (ms) | Wait for selector, text on page, or fixed delay. |
-| `evaluate` | `value` (JS code) | Run JavaScript in browser context. **Strict**: returns starting with `FAIL:`/`ERROR:` → test fails. Returns `false` → test fails. |
+| `wait_network_idle` | `value` (idle ms, default 500), `timeout` (max wait ms, default 30000) | Waits for all network requests to complete. Uses Puppeteer's `page.waitForNetworkIdle()`. Useful after SPA page transitions or data loading. |
+| `evaluate` | `value` (JS code) | Run JavaScript in browser context. See **Strict Evaluate** below. |
 | `clear_cookies` | `value` (origin, optional) | Clears cookies, localStorage, sessionStorage for origin. |
 
+### Strict Evaluate Semantics
+
+The `evaluate` action checks the return value:
+
+- If the JS returns a string starting with `FAIL:`, `ERROR:`, or `FAILED:` → the test **fails** with that message.
+- If the JS returns `false` → the test **fails** (`evaluate returned false`).
+- If the JS returns any other non-null value → stored as `{ value: result }` for visibility.
+- If the JS throws → the test **fails** (standard Puppeteer error).
+
+This prevents false PASSes where evaluate actions return error strings that were previously silently ignored.
+
 ## Action-Level Retry
 
 Any action can have `"retries": N` for per-action retry on failure:
@@ -79,14 +106,14 @@ Delay between retries: `actionRetryDelay` config (default 500ms).
 
 ### React input + autocomplete flow
 ```json
-{ "type": "focus_autocomplete", "text": "Diagnosis" },
-{ "type": "type_react", "selector": "#diagnosis-input", "value": "Cefalea" },
-{ "type": "click_option", "text": "Cefalea tensional" }
+{ "type": "focus_autocomplete", "text": "Category" },
+{ "type": "type_react", "selector": "#category-input", "value": "Electr" },
+{ "type": "click_option", "text": "Electronics" }
 ```
 
 ### Regex click (last match)
 ```json
-{ "type": "click_regex", "text": "start encounter", "selector": "button", "value": "last" }
+{ "type": "click_regex", "text": "add to cart", "selector": "button", "value": "last" }
 ```
 
 ### Form validation assertions
@@ -98,3 +125,19 @@ Delay between retries: `actionRetryDelay` config (default 500ms).
 { "type": "assert_matches", "selector": ".phone", "value": "\\d{3}-\\d{3}-\\d{4}" },
 { "type": "assert_count", "selector": ".table-row", "value": ">3" }
 ```
+
+### Storage operations
+```json
+{ "type": "set_storage", "value": "authToken=eyJhbGciOiJIUzI1NiJ9..." },
+{ "type": "assert_storage", "value": "authToken" },
+{ "type": "set_storage", "value": "theme=dark", "selector": "session" },
+{ "type": "assert_storage", "value": "theme=dark", "selector": "session" }
+```
+
+### Icon, menu, and contextual clicks
+```json
+{ "type": "click_icon", "value": "edit" },
+{ "type": "click_icon", "value": "delete", "selector": ".user-card" },
+{ "type": "click_menu_item", "text": "Export as PDF" },
+{ "type": "click_in_context", "text": "John Doe", "selector": "button.edit" }
+```

package/skills/e2e-testing/references/auth-strategies.md

@@ -0,0 +1,91 @@
+# Authentication Strategies
+
+Tests can authenticate using multiple strategies depending on the app's auth mechanism.
+
+## 1. UI Login (universal)
+
+Fill the login form in `beforeEach`. Works with any auth system — the browser stores cookies/tokens automatically.
+
+```json
+{ "hooks": { "beforeEach": [
+  { "type": "goto", "value": "/login" },
+  { "type": "type", "selector": "#email", "value": "test@example.com" },
+  { "type": "type", "selector": "#password", "value": "secret" },
+  { "type": "click", "text": "Sign In" },
+  { "type": "wait", "selector": ".dashboard" }
+]}}
+```
+
+## 2. JWT Injection (SPAs)
+
+Skip the login form by injecting a token into `localStorage` or `sessionStorage`:
+
+```json
+{ "type": "set_storage", "value": "accessToken=eyJhbG..." }
+{ "type": "set_storage", "value": "token=eyJhbG...", "selector": "session" }
+```
+
+## 3. Config-Level Token
+
+Set `authToken` + `authStorageKey` in config, env vars (`AUTH_TOKEN`, `AUTH_STORAGE_KEY`), or CLI flags (`--auth-token`, `--auth-storage-key`). Used by `e2e_capture` and `e2e_issue --verify`.
+
+## 4. Cookie-Based (server-rendered)
+
+Set cookies via `evaluate`:
+```json
+{ "type": "evaluate", "value": "document.cookie = 'session_id=abc123; path=/; SameSite=Lax'" }
+```
+
+## 5. API Headers
+
+Override `fetch` to inject Authorization headers (useful for `--test-type api`):
+```json
+{ "type": "evaluate", "value": "const orig = window.fetch; window.fetch = (url, opts = {}) => { opts.headers = { ...opts.headers, 'Authorization': 'Bearer eyJhbG...' }; return orig(url, opts); }" }
+```
+
+## 6. OAuth/SSO
+
+Use a test-environment bypass endpoint, pre-authenticated token injection, or CI-obtained session cookie. External OAuth providers (Google, GitHub, Okta) can't be automated directly.
+
+## Auth Auto-Login
+
+Automatically fetch an auth token from a login API endpoint before tests run. Avoids repeating login flows in every test.
+
+### Config fields
+
+| Field | Description | Env / CLI |
+|-------|-------------|-----------|
+| `authLoginEndpoint` | Full URL to POST credentials to | `AUTH_LOGIN_ENDPOINT` / `--auth-login-endpoint` |
+| `authCredentials` | Object with login credentials (config file only — never in env vars) | — |
+| `authTokenPath` | Dot-path to extract token from response JSON (default: `'token'`) | `AUTH_TOKEN_PATH` / `--auth-token-path` |
+
+### Flow
+
+1. Before workers start, if `authLoginEndpoint` is set and `authToken` is NOT already set, `fetchAuthToken()` POSTs `authCredentials` as JSON.
+2. The token is extracted from the response using `authTokenPath` (supports dot notation, e.g. `'data.access_token'`).
+3. The extracted token is stored in `config.authToken`.
+4. Each test worker navigates to `baseUrl` and injects `localStorage[authStorageKey] = authToken` before `beforeEach` hooks run.
+
+### Example config
+
+```js
+export default {
+  authLoginEndpoint: 'https://api.example.com/auth/login',
+  authCredentials: { email: 'test@example.com', password: 'secret123' },
+  authTokenPath: 'data.access_token',
+  authStorageKey: 'accessToken',
+};
+```
+
+If `authToken` is already set (via config, env var, or CLI), the auto-login step is skipped.
+
+## Clearing State
+
+Each test runs in a fresh browser context (auto-clean). Use `clear_cookies` to explicitly clear cookies + localStorage + sessionStorage mid-test.
+
+## Reusable Auth Modules
+
+Create `e2e/modules/login.json` or `e2e/modules/auth-token.json` and reference via:
+```json
+{ "$use": "login", "params": { "email": "...", "password": "..." } }
+```

package/skills/e2e-testing/references/graphql.md

@@ -0,0 +1,59 @@
+# GraphQL Action Reference
+
+The `gql` action executes GraphQL queries and mutations via browser `fetch`, with automatic auth token injection from `localStorage`. It also installs a `window.__e2eGql(query, vars)` helper for use in subsequent `evaluate` actions.
+
+## Action Fields
+
+| Action | Fields | Behavior |
+|--------|--------|----------|
+| `gql` | `value` (query string, required), `text` (variables JSON, optional), `selector` (assertion JS expression, optional) | Sends a GraphQL request to the configured endpoint. Reads auth token from localStorage. Throws on GraphQL errors. Returns `{ value: response.data }`. Stores full response on `window.__e2eLastGql`. |
+
+## Config Fields
+
+| Field | Default | Env Var | CLI Flag |
+|-------|---------|---------|----------|
+| `gqlEndpoint` | `/api/graphql` | `GQL_ENDPOINT` | `--gql-endpoint` |
+| `gqlAuthHeader` | `Authorization` | `GQL_AUTH_HEADER` | `--gql-auth-header` |
+| `gqlAuthKey` | `accessToken` | `GQL_AUTH_KEY` | `--gql-auth-key` |
+| `gqlAuthPrefix` | `Bearer ` | `GQL_AUTH_PREFIX` | `--gql-auth-prefix` |
+
+The endpoint path is appended to `location.origin`. The auth token is read from `localStorage[gqlAuthKey]` and sent as `gqlAuthHeader: gqlAuthPrefix + token`.
+
+## Examples
+
+### Basic query
+```json
+{ "type": "gql", "value": "{ users { id name } }" }
+```
+
+### With variables
+```json
+{ "type": "gql", "value": "query($id: ID, $orgId: ID) { orders(userId: $id, orgId: $orgId) { orderId status } }", "text": "{\"id\": \"abc-123\", \"orgId\": \"org-456\"}" }
+```
+
+### With inline assertion (selector field)
+```json
+// selector is a JS expression where `r` is the full GraphQL response
+{ "type": "gql", "value": "{ pendingOrders(userId: \"abc-123\") { status } }", "selector": "r.data.pendingOrders.some(o => o.status === 'CANCELLED') ? 'FAIL: cancelled order found in pending list' : 'OK: all pending'" }
+```
+
+### Using the installed helper in evaluate
+```json
+// After any gql action runs, window.__e2eGql(query, vars) is available
+{ "type": "gql", "value": "{ __typename }" }
+{ "type": "evaluate", "value": "(async () => { const r = await window.__e2eGql('query { orders(status: [PROCESSING]) { orderId } }'); for (const o of r.data.orders) await window.__e2eGql('mutation($id: ID, $input: OrderInput) { updateOrder(orderId: $id, input: $input) { orderId } }', { id: o.orderId, input: { status: 'COMPLETED' } }); return 'Updated ' + r.data.orders.length; })()" }
+```
+
+## Custom Auth Header Config
+
+If your API uses a non-standard auth header (e.g., `x-api-key` instead of `Authorization`):
+
+```js
+// e2e.config.js
+export default {
+  gqlEndpoint: '/api/graphql',
+  gqlAuthHeader: 'x-api-key',   // custom header name
+  gqlAuthKey: 'apiToken',       // localStorage key to read from
+  gqlAuthPrefix: '',             // no 'Bearer ' prefix — raw token
+};
+```

package/skills/e2e-testing/references/issue-verification.md

@@ -0,0 +1,59 @@
+# Issue-to-Test Verification Reference
+
+Turns bug reports and feature requests into executable E2E tests.
+
+## Supported Providers
+
+- **GitHub** (`github.com`) — requires `gh` CLI (`gh auth login`)
+- **GitLab** (including self-hosted) — requires `glab` CLI (`glab auth login`)
+
+Auto-detected from URL. All external commands use `execFileSync` (no shell injection).
+
+## Two AI Modes
+
+### 1. Prompt Mode (default, no API key)
+
+`e2e_issue` MCP tool returns issue details + a structured prompt. Claude Code then uses `e2e_create_test` to create tests and `e2e_run` to execute them.
+
+### 2. Verify Mode (requires `ANTHROPIC_API_KEY`)
+
+Calls Claude API directly to generate tests, runs them, and reports whether the bug is confirmed or not reproducible.
+
+## Config Fields
+
+| Field | Description | Env Var |
+|-------|-------------|---------|
+| `anthropicApiKey` | Required for verify/generate mode | `ANTHROPIC_API_KEY` |
+| `anthropicModel` | Claude model for generation (default: `claude-sonnet-4-5-20250929`) | `ANTHROPIC_MODEL` |
+
+## Bug Verification Logic
+
+Generated tests assert **correct** behavior:
+- **Test failure** = bug confirmed (expected behavior doesn't match reality)
+- **All tests pass** = not reproducible
+
+## Test Categories (`testType`)
+
+The `--test-type` CLI flag (or `testType` MCP parameter) controls what kind of tests the AI generates:
+
+- **`e2e`** (default): UI-driven tests — navigate pages, interact with elements (click, type, select), verify visible state. Never uses `evaluate` for API calls.
+- **`api`**: Backend API tests — use `evaluate` actions for GraphQL/REST calls, assert response shapes and values. No UI interaction needed.
+
+CLI: `e2e-runner issue <url> --generate --test-type api`
+MCP: `e2e_issue({ url, testType: "api" })`
+
+## GitLab Limitations
+
+- Requires `glab` CLI installed and authenticated (`glab auth login`)
+- Self-hosted GitLab instances supported via URL detection
+- Verify mode works with GitLab issues but does NOT post comments back to the issue
+- Private repos require `glab` to be authenticated with appropriate access
+- The `authToken`/`authStorageKey` params on `e2e_issue` are for the **app under test**, not for GitLab API auth
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/issues.js` | GitHub/GitLab provider drivers |
+| `src/ai-generate.js` | AI prompt builder + Claude API |
+| `src/verify.js` | Verification orchestrator: fetch + generate + run |

package/skills/e2e-testing/references/multi-pool.md

@@ -0,0 +1,60 @@
+# Multi-Pool Support
+
+A single runner can distribute tests across multiple Chrome pools on different machines. `src/pool-manager.js` abstracts pool selection behind a **least-pressure** strategy. `poolUrl` (singular string) remains fully backwards compatible.
+
+## Configuration
+
+```js
+// Single pool (unchanged)
+export default { poolUrl: 'ws://localhost:3333' };
+
+// Multi-pool — tests distribute across all pools
+export default {
+  poolUrls: ['ws://machine1:3333', 'ws://machine2:3333'],
+  concurrency: 15,
+};
+
+// CI environment profile
+export default {
+  poolUrl: 'ws://localhost:3333',
+  environments: {
+    ci: { poolUrls: ['ws://ci-chrome1:3333', 'ws://ci-chrome2:3333'], concurrency: 10 },
+  },
+};
+```
+
+**CLI:** `e2e-runner run --all --pool-urls ws://m1:3333,ws://m2:3333`
+**Env:** `CHROME_POOL_URLS=ws://m1:3333,ws://m2:3333` (comma-separated)
+
+## Pool Selection Algorithm (`selectPool`)
+
+1. Query all pools' `/pressure` in parallel
+2. Filter to reachable pools with `running < maxConcurrent`
+3. Sort by: lowest `running/maxConcurrent` → fewest queued → most free slots
+4. Return best candidate URL
+5. If all full, poll every 2s up to 60s, then pick least-pressured anyway
+
+## Pool-Aware Queue
+
+Before opening a browser connection, each worker checks the pool's `/pressure` endpoint. If the pool is at capacity, the worker waits (polling every 2s, up to 60s) for a free slot instead of piling requests into browserless's internal queue. This prevents memory pressure and SIGKILL of Chrome processes under heavy load.
+
+## Failure Resilience
+
+Dead pools are excluded from selection. `waitForAnyPool` succeeds if any pool responds. Failed connections trigger re-selection on the next worker.
+
+## Config Normalization in `loadConfig()`
+
+- If `poolUrls` array is set → `config._poolUrls = poolUrls`, `config.poolUrl = poolUrls[0]`
+- Else → `config._poolUrls = [config.poolUrl]`
+- `config.poolUrls` is deleted after normalization (use `config._poolUrls` internally)
+
+## Key Functions (`src/pool-manager.js`)
+
+| Function | Purpose |
+|----------|---------|
+| `getPoolUrls(config)` | Returns `config._poolUrls` (always an array) |
+| `getAllPoolStatuses(poolUrls)` | Fetches `/pressure` from all pools in parallel |
+| `getAggregatedPoolStatus(poolUrls)` | Combined view: `totalRunning`, `totalMaxConcurrent`, per-pool details |
+| `waitForAnyPool(poolUrls)` | Blocks until at least one pool is reachable + available |
+| `selectPool(poolUrls)` | Picks pool with lowest pressure ratio |
+| `selectAndConnect(config)` | Convenience: selectPool + connectToPool in one call |

package/skills/e2e-testing/references/network-debugging.md

@@ -0,0 +1,62 @@
+# Network Debugging Reference
+
+## Network Error Handling
+
+### `assert_no_network_errors` action
+
+Checks accumulated `requestfailed` events during the test. If any network errors exist (e.g., `net::ERR_CONNECTION_REFUSED`), the test fails with details of each error URL. Place after critical page loads.
+
+### `failOnNetworkError` config option
+
+When `true`, automatically fails any test that has network errors after all actions complete. Default: `false` (opt-in).
+
+Set via: config `failOnNetworkError: true` | CLI `--fail-on-network-error` | env `FAIL_ON_NETWORK_ERROR=true` | MCP `failOnNetworkError: true`
+
+### `networkIgnoreDomains` config option
+
+Array of domain substrings to filter from network error tracking. Errors from matching URLs are silently dropped by both `assert_no_network_errors` and `failOnNetworkError`.
+
+Set via: config `networkIgnoreDomains: ['google-analytics.com', 'fonts.googleapis.com']` | CLI `--network-ignore-domains ga.com,fonts.com` | env `NETWORK_IGNORE_DOMAINS=ga.com,fonts.com` (comma-separated)
+
+## Network Request/Response Logging
+
+All XHR/fetch requests are captured with full detail regardless of status code:
+
+- `url`, `method`, `status`, `statusText`, `duration`
+- `requestHeaders` — all request headers as object
+- `requestBody` — POST body (from `req.postData()`)
+- `responseHeaders` — all response headers as object
+- `responseBody` — full response text (truncated at 50KB)
+
+Response bodies are read asynchronously and flushed via `Promise.allSettled` before the browser disconnects. Data is stored in the `network_logs` column in SQLite and displayed in the dashboard.
+
+## MCP Response Optimization
+
+The `e2e_run` MCP tool returns a compact `networkSummary` instead of full logs (~5KB vs ~400KB):
+
+```json
+{
+  "networkSummary": [{
+    "name": "test-name",
+    "totalRequests": 37,
+    "statusDistribution": { "2xx": 30, "3xx": 5, "4xx": 1, "5xx": 0, "other": 1 },
+    "avgDurationMs": 245,
+    "failedRequests": [{ "url": "/api/x", "method": "POST", "status": 500 }],
+    "slowestRequests": [{ "url": "/api/y", "method": "GET", "status": 200, "duration": 1200 }]
+  }]
+}
+```
+
+## Drill-Down Pattern
+
+The response includes `runDbId` — the SQLite row ID. Use it with `e2e_network_logs` to drill down:
+
+```
+1. e2e_run → compact summary + runDbId
+2. e2e_network_logs(runDbId) → all requests (url, method, status, duration)
+3. e2e_network_logs(runDbId, errorsOnly: true) → only failed requests
+4. e2e_network_logs(runDbId, includeHeaders: true) → with headers
+5. e2e_network_logs(runDbId, includeBodies: true) → full request/response bodies
+```
+
+Dashboard REST equivalent: `GET /api/db/runs/:id/network-logs?testName=X&errorsOnly=true&includeHeaders=true`

package/skills/e2e-testing/references/test-json-format.md

@@ -150,6 +150,10 @@ export default {
 
 Activate with `--env staging` or `E2E_ENV=staging`. Profile values override all other config.
 
+## CI Output Formats
+
+Use `--output <format>` to control report output: `json` (default), `junit` (JUnit XML), or `both`. JUnit XML is generated without external dependencies and saved to `{screenshotsDir}/junit.xml`. The `generateJUnitXML()` function is also exported from the programmatic API.
+
 ## Config Priority (ascending)
 
 1. Hardcoded defaults