@matware/e2e-runner 1.1.1 → 1.3.0

package/commands/create-test.md

@@ -0,0 +1,65 @@
+---
+description: Create a new E2E test by exploring the UI and designing test actions
+user_invocable: true
+allowed_tools:
+  - mcp__e2e-runner__e2e_pool_status
+  - mcp__e2e-runner__e2e_capture
+  - mcp__e2e-runner__e2e_list
+  - mcp__e2e-runner__e2e_create_test
+  - mcp__e2e-runner__e2e_create_module
+  - mcp__e2e-runner__e2e_run
+  - mcp__e2e-runner__e2e_screenshot
+  - Read
+  - Grep
+  - Glob
+---
+
+# Create E2E Test
+
+Help the user create a new E2E test file by exploring the application and designing appropriate test actions.
+
+## Workflow
+
+1. **Understand the goal** — Ask the user what they want to test if not already specified. Identify the page(s), user flow, and expected outcomes.
+
+2. **Check pool** — Call `e2e_pool_status` to ensure the Chrome pool is available.
+
+3. **Explore the UI** — Use `e2e_capture` to screenshot the target page(s). This helps understand the current state of the UI, available elements, and layout.
+
+4. **Check existing tests** — Call `e2e_list` to see what test suites already exist. Read relevant existing test files with `Read` to follow conventions and avoid duplication.
+
+5. **Explore source code** (optional) — If needed, use `Grep` and `Read` to find selectors, form field IDs, API endpoints, or component structure in the application source code.
+
+6. **Design the test** — Based on UI exploration and source code analysis, design the test actions:
+   - Use the most specific selectors available (data-testid > id > class > text)
+   - Prefer granular assertion actions over `evaluate`
+   - Use framework-aware actions for React/MUI (`type_react`, `click_option`, `focus_autocomplete`)
+   - 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.
+   - 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:
+- A test name: `/e2e-runner:create-test login-flow`
+- A description of what to test: `/e2e-runner:create-test test the checkout process`
+- A URL to start from: `/e2e-runner:create-test http://localhost:3000/checkout`

package/commands/run.md

@@ -0,0 +1,49 @@
+---
+description: Run E2E tests and analyze results with screenshots and network drill-down
+user_invocable: true
+allowed_tools:
+  - mcp__e2e-runner__e2e_pool_status
+  - mcp__e2e-runner__e2e_list
+  - mcp__e2e-runner__e2e_run
+  - mcp__e2e-runner__e2e_screenshot
+  - mcp__e2e-runner__e2e_network_logs
+  - mcp__e2e-runner__e2e_learnings
+---
+
+# Run E2E Tests
+
+Execute E2E tests and provide a complete analysis of results.
+
+## Workflow
+
+1. **Check pool availability** — Call `e2e_pool_status` to confirm the Chrome pool is running. If not available, tell the user to run `npx e2e-runner pool start` via CLI.
+
+2. **List available suites** — Call `e2e_list` to show the user what test suites are available.
+
+3. **Run tests** — Call `e2e_run` based on user input:
+   - If user specified a suite name: use `suite` parameter
+   - If user specified a file: use `file` parameter
+   - If user said "all" or didn't specify: use `all: true`
+   - Always pass `cwd` with the current working directory
+   - Pass any user-specified overrides: `baseUrl`, `concurrency`, `retries`, `failOnNetworkError`
+
+4. **Analyze results** — Parse the run response:
+   - Report pass/fail summary and duration
+   - For failures: show error messages and retrieve error screenshots with `e2e_screenshot`
+   - For verifications (tests with `expect`): retrieve verification screenshots and judge against descriptions
+   - Highlight flaky tests if any
+   - Summarize network activity (failed requests, slow requests)
+
+5. **Drill down if needed** — For failed tests:
+   - Use `e2e_network_logs` with `runDbId` to investigate network failures
+   - Use `e2e_learnings` to check if this is a known pattern or new failure
+
+6. **Report** — Provide a clear summary to the user with actionable next steps.
+
+## Arguments
+
+The user may pass arguments after the command:
+- Suite name: `/e2e-runner:run auth` → run the auth suite
+- `--all`: run all suites
+- `--base-url <url>`: override base URL
+- `--retries <n>`: set retry count

package/commands/verify-issue.md

@@ -0,0 +1,63 @@
+---
+description: Verify a GitHub/GitLab issue by creating and running E2E tests
+user_invocable: true
+allowed_tools:
+  - mcp__e2e-runner__e2e_pool_status
+  - mcp__e2e-runner__e2e_issue
+  - mcp__e2e-runner__e2e_create_test
+  - mcp__e2e-runner__e2e_run
+  - mcp__e2e-runner__e2e_screenshot
+  - mcp__e2e-runner__e2e_network_logs
+  - mcp__e2e-runner__e2e_capture
+  - Read
+  - Grep
+---
+
+# Verify Issue
+
+Turn a GitHub or GitLab bug report into executable E2E tests to confirm or dismiss the bug.
+
+## Workflow
+
+1. **Check pool** — Call `e2e_pool_status` to ensure the Chrome pool is available.
+
+2. **Fetch the issue** — Call `e2e_issue` with the issue URL. Default `mode: "prompt"` returns issue details + a structured prompt for test creation.
+
+3. **Analyze the issue** — Parse the issue details:
+   - Understand the reported bug or expected behavior
+   - Identify affected pages/flows
+   - Note any reproduction steps provided
+
+4. **Explore the app** — Use `e2e_capture` to screenshot relevant pages. Use `Read` and `Grep` to check source code for related components, API endpoints, or selectors.
+
+5. **Design tests** — Create tests that assert the **correct behavior**:
+   - If tests **fail** → bug is confirmed (correct behavior is not working)
+   - If tests **pass** → bug is not reproducible
+
+6. **Create and run** — Use `e2e_create_test` to write the test file, then `e2e_run` to execute it.
+
+7. **Analyze results** — For failures:
+   - Retrieve error screenshots with `e2e_screenshot`
+   - Check network logs with `e2e_network_logs` for API-related issues
+   - Determine if the failure confirms the bug
+
+8. **Report verdict** — Clearly state:
+   - **BUG CONFIRMED**: tests failed, reproducing the issue
+   - **NOT REPRODUCIBLE**: tests passed, correct behavior works as expected
+   - Include evidence (screenshots, error messages, network details)
+
+## Alternative: Verify Mode
+
+If `ANTHROPIC_API_KEY` is set, use `e2e_issue` with `mode: "verify"` for a fully automated flow — it generates tests via Claude API, runs them, and reports the result.
+
+## Arguments
+
+**Required**: GitHub or GitLab issue URL
+
+```
+/e2e-runner:verify-issue https://github.com/org/repo/issues/123
+```
+
+Optional flags:
+- `--test-type api` — generate API tests instead of UI tests
+- `--verify` — use verify mode (requires ANTHROPIC_API_KEY)

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.1.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",
@@ -15,7 +15,16 @@
   "files": [
     "bin/",
     "src/",
-    "templates/"
+    "templates/",
+    ".claude-plugin/",
+    ".mcp.json",
+    "skills/",
+    "commands/",
+    "agents/",
+    ".opencode/",
+    "opencode.json",
+    "OPENCODE.md",
+    "scripts/setup-opencode.sh"
   ],
   "keywords": [
     "e2e",
@@ -26,6 +35,7 @@
     "parallel",
     "mcp",
     "claude-code",
+    "opencode",
     "github-issues",
     "ai-testing"
   ],
@@ -41,6 +51,9 @@
     "better-sqlite3": "^11.0.0",
     "puppeteer-core": "^24.0.0"
   },
+  "scripts": {
+    "build:dashboard": "node templates/build-dashboard.js"
+  },
   "engines": {
     "node": ">=20.0.0"
   }

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

@@ -0,0 +1,173 @@
+---
+name: e2e-testing
+description: Create, run, and debug JSON-driven E2E browser tests with Chrome pool integration
+---
+
+# E2E Testing with @matware/e2e-runner
+
+## Overview
+
+`@matware/e2e-runner` is a JSON-driven E2E test runner. Tests are defined as JSON files with sequential browser actions — no JavaScript test code. Tests run in parallel against a Chrome pool (browserless/chrome via Docker) using Puppeteer.
+
+**Key capabilities:** 13 MCP tools for running tests, creating test files, capturing screenshots, analyzing network traffic, verifying GitHub/GitLab issues, and querying a learning system for stability insights.
+
+## Prerequisites
+
+Before running any tests, verify the Chrome pool is available:
+
+```
+e2e_pool_status → check "Available: yes" and session capacity
+```
+
+If the pool is not running, the user must start it via CLI (not available via MCP):
+```bash
+npx e2e-runner pool start
+```
+
+## Core Workflow
+
+The standard test execution flow:
+
+1. **Check pool** → `e2e_pool_status` — confirm Chrome pool is ready
+2. **List suites** → `e2e_list` — discover available test files and modules
+3. **Run tests** → `e2e_run` — execute with `all`, `suite`, or `file` parameter
+4. **Interpret results** — check `summary`, `failures`, `narratives`, `networkSummary`
+5. **View screenshots** → `e2e_screenshot` — retrieve error/verification screenshots by `ss:HASH`
+6. **Drill into network** → `e2e_network_logs` — use `runDbId` to inspect requests/responses
+7. **Check learnings** → `e2e_learnings` — query stability trends, flaky tests, error patterns
+
+### Interpreting Run Results
+
+The `e2e_run` response includes:
+
+- **summary**: pass/fail counts, duration, `runDbId` for drill-down
+- **failures**: failed test names with error messages and error screenshot hashes
+- **narratives**: step-by-step human-readable story of each test execution
+- **networkSummary**: per-test request stats (status distribution, slow/failed requests)
+- **verifications**: tests with `expect` field — call `e2e_screenshot` to visually verify
+- **learnings**: stability insights from the learning system (new failures, flaky patterns)
+
+## Creating Tests
+
+### Basic Structure
+
+```json
+[
+  {
+    "name": "login-flow",
+    "actions": [
+      { "type": "goto", "value": "/login" },
+      { "type": "type", "selector": "#email", "value": "user@example.com" },
+      { "type": "type", "selector": "#password", "value": "secret" },
+      { "type": "click", "text": "Sign In" },
+      { "type": "wait", "selector": ".dashboard" },
+      { "type": "assert_url", "value": "/dashboard" }
+    ]
+  }
+]
+```
+
+Use `e2e_create_test` to write test files. Use `e2e_create_module` for reusable action sequences.
+
+### Key Action Patterns
+
+- **Navigation**: `goto` (full page load), `navigate` (SPA-friendly, non-blocking)
+- **Interaction**: `click` (selector or text), `type`/`fill`, `select`, `press`, `hover`, `scroll`
+- **React/MUI**: `type_react` (controlled inputs), `click_option`, `focus_autocomplete`, `click_chip`, `click_regex`
+- **Assertions**: `assert_text` (page-wide), `assert_element_text` (scoped), `assert_url`, `assert_visible`, `assert_not_visible`, `assert_count`, `assert_attribute`, `assert_class`, `assert_input_value`, `assert_matches`
+- **Extraction**: `get_text` (non-assertion, returns element text), `screenshot`
+- **Advanced**: `evaluate` (run JS in browser), `assert_no_network_errors`, `clear_cookies`
+
+### Visual Verification
+
+Add an `expect` field to any test for AI-powered visual verification:
+
+```json
+{
+  "name": "dashboard-loads",
+  "expect": "Should show data table with at least 3 rows and no error messages",
+  "actions": [...]
+}
+```
+
+After running, call `e2e_screenshot` with each verification hash and judge the screenshot against the description.
+
+### Reusable Modules
+
+Create modules with `e2e_create_module`, reference them in tests:
+
+```json
+{ "$use": "auth-jwt", "params": { "email": "admin@test.com" } }
+```
+
+For complete action type reference, see [action-types.md](references/action-types.md).
+For JSON format details (hooks, serial, retries, modules), see [test-json-format.md](references/test-json-format.md).
+
+## Issue Verification
+
+Turn GitHub/GitLab bug reports into executable tests:
+
+### Prompt Mode (default, no API key needed)
+
+1. `e2e_issue` with issue URL → returns structured prompt with issue details
+2. Analyze the issue and design test actions
+3. `e2e_create_test` → create the test file
+4. `e2e_run` → execute and verify
+
+### Verify Mode (requires ANTHROPIC_API_KEY)
+
+1. `e2e_issue` with `mode: "verify"` → auto-generates tests via Claude API, runs them, reports result
+2. Test failure = bug confirmed, all pass = not reproducible
+
+Supports both UI tests (`testType: "e2e"`) and API tests (`testType: "api"`).
+
+## Debugging & Analysis
+
+### Network Inspection
+
+```
+e2e_network_logs(runDbId)                     → all requests
+e2e_network_logs(runDbId, errorsOnly: true)    → failed requests only
+e2e_network_logs(runDbId, includeBodies: true) → full request/response bodies
+e2e_network_logs(runDbId, urlPattern: "/api/") → filter by URL pattern
+```
+
+### Learning System
+
+```
+e2e_learnings("summary")    → full project overview
+e2e_learnings("flaky")      → flaky test analysis
+e2e_learnings("selectors")  → selector stability
+e2e_learnings("errors")     → recurring error patterns
+e2e_learnings("test:name")  → drill into specific test history
+```
+
+### On-Demand Capture
+
+Use `e2e_capture` to screenshot any URL without running a full test suite. Useful for visual exploration or verifying current state.
+
+### Dashboard
+
+Start/stop the web dashboard with `e2e_dashboard_start` / `e2e_dashboard_stop` for a visual UI at `http://localhost:8484`.
+
+## Important Rules
+
+1. **Always pass `cwd`** — All MCP tools accept `cwd` (the project root). Always pass it so config files and test directories resolve correctly.
+2. **`baseUrl` default is `http://host.docker.internal:3000`** — Chrome runs inside Docker, so it uses `host.docker.internal` to reach the host machine. Override with `baseUrl` if the app runs on a different port.
+3. **Pool management is CLI-only** — `pool start` and `pool stop` are not available via MCP. Only `e2e_pool_status` is an MCP tool.
+4. **`evaluate` is strict** — Returns starting with `FAIL:`/`ERROR:` or returning `false` will fail the test. Prefer granular assertion actions over `evaluate` with inline JS.
+5. **Serial tests** — Mark tests with `"serial": true` if they share mutable state. They run after all parallel tests.
+6. **Action retries** — Use `"retries": N` on individual actions for flaky selectors, or globally via config.
+
+## 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, 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

@@ -0,0 +1,143 @@
+# Action Types Reference
+
+Complete catalog of all action types supported by @matware/e2e-runner.
+
+## Navigation
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `goto` | `value` (URL or path) | Full page navigation. Relative paths are prefixed with `baseUrl`. Waits for `domcontentloaded`. |
+| `navigate` | `value` (URL or path) | SPA-friendly navigation. Uses `load` event with a 5s race timeout — won't block if client-side routing doesn't fire `load`. |
+
+## Interaction
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `click` | `selector` OR `text` | Click by CSS selector or by visible text content. Text search covers: `button, a, [role="button"], [role="tab"], [role="menuitem"], [role="option"], [role="listitem"], div[class*="cursor"], span, li, td, th, label, p, h1-h6, dd, dt`. |
+| `type` / `fill` | `selector`, `value` | Triple-clicks to select all, then Backspace to clear, then types with 20ms delay per character. |
+| `select` | `selector`, `value` | Select an `<option>` value in a `<select>` element. |
+| `clear` | `selector` | Triple-click + Backspace to clear an input field. |
+| `press` | `value` (key name) | Press a keyboard key (e.g. `"Enter"`, `"Tab"`, `"Escape"`, `"ArrowDown"`). |
+| `scroll` | `selector` (optional), `value` (optional) | Scroll element into view, or scroll window by Y pixels (default 300). |
+| `hover` | `selector` | Hover over an element. |
+
+## Framework-Aware (React/MUI)
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `type_react` | `selector`, `value` | Types into React controlled inputs using native value setter. Dispatches `input` + `change` events so React state updates. Supports `<input>` and `<textarea>`. |
+| `click_regex` | `text` (regex), `selector` (optional), `value` (`"last"` optional) | Click element whose textContent matches regex (case-insensitive). Default: first match. `value: "last"` for last match. `selector` scopes the search. |
+| `click_option` | `text` | Click a `[role="option"]` element by text — for autocomplete/select dropdowns. Waits for option to appear. |
+| `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 |
+|--------|--------|-------------|
+| `assert_text` | `text` | Check entire page body contains text (substring match). |
+| `assert_element_text` | `selector`, `text`, `value` (`"exact"` optional) | Check specific element's `textContent`. Default: substring match. With `value: "exact"`: strict `trim() ===` comparison. |
+| `assert_url` | `value` | Check current URL. Path-only (`/dashboard`) compares pathname. Full URL does substring match. |
+| `assert_visible` | `selector` | Element exists and is visible (`display`, `visibility`, `opacity` checks). |
+| `assert_not_visible` | `selector` | Passes if element doesn't exist OR is hidden. |
+| `assert_count` | `selector`, `value` | Count matching elements. Supports exact (`"5"`) and operators (`">3"`, `">=1"`, `"<10"`, `"<=5"`). |
+| `assert_attribute` | `selector`, `value` (`"attr=expected"` or `"attr"`) | With `=`: checks attribute value. Without: checks attribute existence. |
+| `assert_class` | `selector`, `value` | Checks `classList.contains(value)`. |
+| `assert_input_value` | `selector`, `value` | Checks `element.value.includes(value)` on input/select/textarea. |
+| `assert_matches` | `selector`, `value` (regex) | Tests element's `textContent` against `new RegExp(value)`. |
+| `assert_no_network_errors` | — | Checks accumulated `requestfailed` events during the test. Fails with error details if any exist. |
+
+### Assertion Disambiguation
+
+- **`assert_text`** → searches the **entire page body** (substring)
+- **`assert_element_text`** → checks a **specific element** (substring, or exact with `value: "exact"`)
+- **`assert_matches`** → checks a specific element against a **regex** pattern
+- **`assert_input_value`** → reads the `.value` property (for form fields)
+
+## Extraction & Utility
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `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. |
+| `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:
+
+```json
+{ "type": "click", "selector": "#dynamic-btn", "retries": 3 }
+{ "type": "wait", "selector": ".lazy-loaded", "retries": 2 }
+```
+
+Delay between retries: `actionRetryDelay` config (default 500ms).
+
+## Examples
+
+### React input + autocomplete flow
+```json
+{ "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": "add to cart", "selector": "button", "value": "last" }
+```
+
+### Form validation assertions
+```json
+{ "type": "assert_attribute", "selector": "input#email", "value": "type=email" },
+{ "type": "assert_attribute", "selector": "button.submit", "value": "disabled" },
+{ "type": "assert_class", "selector": ".nav-item:first-child", "value": "active" },
+{ "type": "assert_input_value", "selector": "#email", "value": "user@example.com" },
+{ "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" }
+```