@matware/e2e-runner 1.3.1 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "AI-powered E2E testing tools by Matware — JSON-driven browser tests, Chrome pool, visual verification, and stability learning",
-    "version": "1.3.0"
+    "version": "1.5.0"
   },
   "plugins": [
     {
@@ -14,10 +14,10 @@
       "source": {
         "source": "npm",
         "package": "@matware/e2e-runner",
-        "version": "^1.3.0"
+        "version": "^1.5.0"
       },
-      "description": "JSON-driven E2E browser test runner — no JavaScript test files needed. Parallel execution against a Chrome pool, 28+ built-in actions, visual verification, network debugging, flaky test detection, reusable modules, and a real-time dashboard. Includes 3 specialized agents (test-creator, test-analyzer, test-improver), 4 slash commands, and 16 MCP tools.",
-      "version": "1.3.0",
+      "description": "JSON-driven E2E browser test runner — no JavaScript test files needed. Parallel execution against a Chrome pool (browserless, CDP, Lightpanda, Obscura, Steel), 28+ built-in actions, visual verification, network debugging, flaky test detection, reusable modules, and a real-time dashboard. Includes 3 specialized agents (test-creator, test-analyzer, test-improver), 4 slash commands, and 17 MCP tools.",
+      "version": "1.5.0",
       "author": { "name": "Matware" },
       "homepage": "https://www.npmjs.com/package/@matware/e2e-runner",
       "repository": "https://github.com/fastslack/mtw-e2e-runner",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "e2e-runner",
-  "version": "1.3.0",
-  "description": "JSON-driven E2E browser test runner — no JavaScript test files needed. Parallel execution against a Chrome pool, 28+ built-in actions, visual verification, network debugging, flaky test detection, reusable modules, and a real-time dashboard. Includes 3 specialized agents, 4 slash commands, and 16 MCP tools.",
+  "version": "1.5.0",
+  "description": "JSON-driven E2E browser test runner — no JavaScript test files needed. Parallel execution against a Chrome pool (browserless, CDP, Lightpanda, Obscura, Steel), 28+ built-in actions, visual verification, network debugging, flaky test detection, reusable modules, and a real-time dashboard. Includes 3 specialized agents, 4 slash commands, and 17 MCP tools.",
   "author": { "name": "Matware" },
   "repository": "https://github.com/fastslack/mtw-e2e-runner",
   "homepage": "https://www.npmjs.com/package/@matware/e2e-runner",

package/README.md

@@ -31,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
 [
@@ -49,7 +49,7 @@ 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.
 
 ---
 
@@ -69,32 +69,51 @@ This gives your agent the knowledge to create, run, and debug JSON-driven E2E te
 
 ## Getting Started
 
-**Prerequisites:** Node.js >= 20, Docker running, your app on a known port.
+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.
 
-### Quickstart
+### Try it in 60 seconds
 
 ```bash
 npm install --save-dev @matware/e2e-runner
-npx e2e-runner init          # creates e2e/tests/ with a sample test
-npx e2e-runner pool start    # starts Chrome in Docker
-npx e2e-runner run --all     # runs the sample test
+npx e2e-runner init        # scaffolds e2e/ with a sample test + config
+npx e2e-runner run --all   # runs it — Chrome starts automatically on first run
 ```
 
-Or do it all in one command:
+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
-curl -fsSL https://raw.githubusercontent.com/fastslack/mtw-e2e-runner/main/scripts/quickstart.sh | bash
-```
+> Prefer a single command? `curl -fsSL https://raw.githubusercontent.com/fastslack/mtw-e2e-runner/main/scripts/quickstart.sh | bash`
+
+### Point it at your app
 
-After setup, edit `e2e.config.js` to set 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
 };
 ```
 
-> **Why `host.docker.internal`?** Chrome runs inside Docker and can't reach `localhost` on your machine. This hostname bridges the gap. On Linux (Docker Engine, not Desktop), you may need `--add-host=host.docker.internal:host-gateway` or use your LAN IP directly.
+<details>
+<summary><strong>Why <code>host.docker.internal</code> instead of <code>localhost</code>?</strong></summary>
+
+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>
+
+### Write your first test
+
+Open `e2e/tests/sample.json` and describe a flow as a list of actions:
+
+```json
+[
+  { "name": "homepage loads", "actions": [
+    { "type": "goto", "value": "/" },
+    { "type": "assert_text", "text": "Welcome" },
+    { "type": "screenshot", "value": "home.png" }
+  ]}
+]
+```
+
+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)
 
@@ -103,7 +122,7 @@ claude plugin marketplace add fastslack/mtw-e2e-runner
 claude plugin install e2e-runner@matware
 ```
 
-This gives Claude 13 MCP tools, slash commands, and specialized agents. Just say *"Run all E2E tests"* or *"Create a test for the login flow"*.
+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"*.
 
 ### Add OpenCode (optional)
 
@@ -128,7 +147,7 @@ See [OPENCODE.md](OPENCODE.md) for details.
 
 🧪 **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*.
 
@@ -136,7 +155,9 @@ See [OPENCODE.md](OPENCODE.md) for details.
 
 🧠 **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.
 
@@ -177,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 |
@@ -226,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]`. |
 
@@ -512,6 +534,67 @@ Monitor Chrome pool health: available slots, running sessions, memory pressure.
 
 ---
 
+## Browser Drivers
+
+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.
+
+| 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 |
+
+### Pick a driver per test
+
+```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.
+
+### Force a driver for a whole run
+
+```bash
+e2e-runner run --all --driver obscura
+e2e-runner run --all --driver obscura --fallback-driver cdp
+```
+
+CLI overrides win over per-test fields — useful for A/B benchmarks against the same suite.
+
+### Running each driver locally
+
+```bash
+# browserless (default) — managed by `pool start`
+e2e-runner pool start
+
+# Lightpanda — pool start uses templates/docker-compose-lightpanda.yml
+e2e-runner pool start                 # with poolDriver: 'lightpanda' in config
+
+# 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'
+```
+
+---
+
 ## Screenshot Capture
 
 Capture screenshots of any URL on demand — no test suite required:
@@ -536,7 +619,7 @@ claude plugin marketplace add fastslack/mtw-e2e-runner
 claude plugin install e2e-runner@matware
 ```
 
-This gives Claude 13 MCP tools, a workflow skill, 3 slash commands (`/e2e-runner:run`, `/e2e-runner:create-test`, `/e2e-runner:verify-issue`), and 3 specialized agents (test-analyzer, test-creator, test-improver).
+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).
 
 **MCP-only install** (tools only, no skill/commands/agents):
 
@@ -563,13 +646,17 @@ See [OPENCODE.md](OPENCODE.md) for details.
 | `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.
@@ -679,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 |
 
 ---
 

package/agents/test-creator.md

@@ -63,11 +63,12 @@ You are a specialist in creating robust E2E tests for web applications. You expl
 
 ### Form Interaction
 - Standard input → `type` (clears first)
-- React controlled input → `type_react`
-- Dropdown select → `select` (native) or `focus_autocomplete` + `click_option` (MUI)
+- React controlled input → `type_react` (optional `blur`, `waitAfter`)
+- Dropdown select → `select` (native) or `select_combobox` (MUI Autocomplete/Select — opens, optional `filter`, picks `text` in one action)
 - Checkbox/radio → `click`
 - Clear field → `clear`
 - Submit → `click` on submit button or `press` Enter
+- Confirm in a modal → `click` with `text` + `scope: "dialog"` (add `last: true` if multiple matches)
 
 ### Storage
 - Set localStorage key → `set_storage` with `value: "key=val"`
@@ -83,6 +84,7 @@ You are a specialist in creating robust E2E tests for web applications. You expl
 ### Waiting
 - Element appears → `wait` with `selector`
 - Text appears → `wait` with `text`
+- Element/spinner/dialog disappears → `wait` with `gone` (e.g. `{ "type": "wait", "gone": ".MuiBackdrop-root" }`)
 - Fixed delay (last resort) → `wait` with `value` (ms)
 
 ### Assertions

package/agents/test-improver.md

@@ -26,7 +26,7 @@ You are a specialist in refactoring and optimizing existing E2E tests without ch
 - **Duplication extraction**: Identify repeated action sequences across tests and extract them into reusable modules (`$use`)
 - **Selector hardening**: Replace brittle selectors (nth-child, deep nesting, generated classes) with stable alternatives (`data-testid`, `id`, text-based)
 - **Flaky test stabilization**: Add `wait` actions, `retries`, and `serial: true` based on historical failure data from the learning system
-- **Fixed delay elimination**: Replace hardcoded `wait` with ms values with proper waits on selectors or text
+- **Fixed delay elimination**: Replace hardcoded `wait` with ms values with condition waits — `wait` on a `selector`/`text` to appear, or `wait` with `gone` to wait for a spinner/backdrop/dialog to disappear (e.g. `{ "type": "wait", "gone": ".MuiBackdrop-root" }`)
 - **Visual verification**: Add `expect` fields to tests that lack visual verification
 - **Serial marking**: Mark tests that share mutable state as `serial: true` to prevent race conditions
 - **Hook extraction**: Move duplicated setup/teardown actions into `beforeEach`/`beforeAll` hooks
@@ -68,9 +68,11 @@ When you find an `evaluate` action, check if it matches one of these patterns
 | `el.classList.contains(cls)` | `assert_class` with `selector` + `value` |
 | `el.hasAttribute(attr)` or `el.getAttribute(attr)` | `assert_attribute` with `selector` + `value` |
 | `document.querySelectorAll(sel).length` | `assert_count` with `selector` + `value` |
-| Native value setter + `dispatchEvent(new Event('input'))` | `type_react` with `selector` + `value` |
-| `querySelectorAll('[role="option"]')...click()` | `click_option` with `text` |
+| Native value setter + `dispatchEvent(new Event('input'))` (single input) | `type_react` with `selector` + `value` (+ `blur:true` / `waitAfter` if it blurred/slept) |
+| `querySelectorAll('[role="option"]')...click()` (no combobox open first) | `click_option` with `text` |
+| Open combobox (focus/click input) + optional type filter + click matching option | `select_combobox` with `selector` + `text` (+ `filter`) |
 | `MuiAutocomplete-root...input.focus()` | `focus_autocomplete` with `text` |
+| Find a button by text inside `[role="dialog"]`/`.MuiDialog-root` and click (often the LAST one) | `click` with `text` + `scope: "dialog"` (+ `last: true`) |
 | `querySelectorAll('button').filter(regex)...click()` | `click_regex` with `text` + optional `selector` + `value` |
 | `querySelectorAll('[class*="Chip"]')...click()` | `click_chip` with `text` |
 | `localStorage.setItem(key, val)` or `sessionStorage.setItem(...)` | `set_storage` with `value: "key=val"`, `selector: "session"` for session |

package/bin/cli.js

@@ -21,7 +21,8 @@
  *   e2e-runner issue <url> --generate     Generate test file via Claude API
  *   e2e-runner issue <url> --verify       Generate + run + report bug status
  *   e2e-runner issue <url> --prompt       Output the AI prompt (for piping)
- *   e2e-runner init                       Scaffold e2e/ in the current project
+ *   e2e-runner init                       Interactive wizard to scaffold e2e/
+ *   e2e-runner init --yes                 Scaffold with defaults (no prompts)
  *   e2e-runner --help                     Show help
  *   e2e-runner --version                  Show version
  */
@@ -43,6 +44,7 @@ import { verifyIssue } from '../src/verify.js';
 import { ensureProject, computeScreenshotHash, registerScreenshotHash } from '../src/db.js';
 import { log, colors as C } from '../src/logger.js';
 import { listModules } from '../src/module-resolver.js';
+import { runInitWizard, renderConfig, getDefaultAnswers } from '../src/wizard.js';
 import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends } from '../src/learner-sqlite.js';
 import { startNeo4j, stopNeo4j, getNeo4jStatus } from '../src/neo4j-pool.js';
 import { 
@@ -118,6 +120,8 @@ function parseCLIConfig() {
       cliArgs.verificationStrictness = val;
     }
   }
+  if (getFlag('--driver')) cliArgs.cliDriverOverride = getFlag('--driver');
+  if (getFlag('--fallback-driver')) cliArgs.cliFallbackDriverOverride = getFlag('--fallback-driver');
   return cliArgs;
 }
 
@@ -175,7 +179,10 @@ ${C.bold}Usage:${C.reset}
   e2e-runner sync push                  Process sync queue (agent mode)
   e2e-runner sync pull                  Pull runs from hub (agent mode)
 
-  e2e-runner init                       Scaffold e2e/ in the current project
+  e2e-runner init                       Interactive wizard to scaffold e2e/
+  e2e-runner init --yes                 Scaffold with defaults (CI / non-interactive)
+                                          Flags: --name, --base-url, --driver,
+                                          --pool-port, --concurrency, --no-sample
 
 ${C.bold}Options:${C.reset}
   --base-url <url>         App base URL (default: http://host.docker.internal:3000)
@@ -199,6 +206,9 @@ ${C.bold}Options:${C.reset}
   --auth-login-endpoint <url>  Auto-login: POST credentials to this URL to get auth token
   --auth-token-path <path>     Dot-path to token in auth response (default: token)
   --verification-strictness <level>  Visual verification: strict, moderate (default), lenient
+  --driver <name>          Force pool driver for this run: browserless, cdp, lightpanda, obscura, steel
+                           (overrides per-test "driver" field; useful for A/B benchmarks)
+  --fallback-driver <name> Explicit fallback if no pool with --driver is reachable (overrides per-test "fallbackDriver")
 
 ${C.bold}Watch Options:${C.reset}
   --interval <time>          Run interval: 15m, 1h, 30s (required for schedule mode)
@@ -220,6 +230,21 @@ async function cmdRun() {
   const cliArgs = parseCLIConfig();
   const config = await loadConfig(cliArgs);
   config.triggeredBy = 'cli';
+
+  // Validate CLI driver overrides up-front (clearer error than waiting for first test)
+  if (config.cliDriverOverride || config.cliFallbackDriverOverride) {
+    const allowed = ['browserless', 'cdp', 'lightpanda', 'obscura', 'steel'];
+    for (const [flag, val] of [['--driver', config.cliDriverOverride], ['--fallback-driver', config.cliFallbackDriverOverride]]) {
+      if (val && !allowed.includes(val)) {
+        console.error(`${C.red}Invalid value for ${flag}: "${val}". Allowed: ${allowed.join(', ')}.${C.reset}`);
+        process.exit(1);
+      }
+    }
+    if (config.cliFallbackDriverOverride && !config.cliDriverOverride) {
+      console.error(`${C.red}--fallback-driver requires --driver.${C.reset}`);
+      process.exit(1);
+    }
+  }
   let tests = [];
   let hooks = {};
 
@@ -262,9 +287,32 @@ async function cmdRun() {
     process.exit(1);
   }
 
-  // Verify pool connectivity
+  // Verify pool connectivity — auto-start the Docker-managed pool if none is
+  // reachable, so first-time users don't need a separate `pool start` step.
   log('🔌', `Checking Chrome Pool${poolUrls.length > 1 ? 's' : ''}...`);
-  const pressure = await waitForAnyPool(poolUrls, 30000, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
+  const driverOpts = { poolDriver: config.poolDriver, maxSessions: config.maxSessions };
+  const _driver = config.poolDriver || 'auto';
+  const _dockerManaged = ['auto', 'browserless', 'lightpanda'].includes(_driver);
+  const _autoStart = config.autoStartPool !== false;
+  let pressure;
+  try {
+    pressure = await waitForAnyPool(poolUrls, 5000, driverOpts);
+  } catch {
+    if (_autoStart && _dockerManaged) {
+      log('🐳', `${C.dim}No pool detected — starting Chrome pool via Docker...${C.reset}`);
+      try {
+        startPool(config);
+      } catch (se) {
+        console.error(`${C.red}Could not auto-start the Chrome pool: ${se.message}${C.reset}`);
+        console.error(`${C.dim}Is Docker running? You can also start it manually: ${C.cyan}e2e-runner pool start${C.reset}`);
+        process.exit(1);
+      }
+      pressure = await waitForAnyPool(poolUrls, 45000, driverOpts);
+    } else {
+      console.error(`${C.red}No Chrome Pool available.${C.reset} Driver "${_driver}" is not Docker-managed — start your browser endpoint, then re-run.`);
+      process.exit(1);
+    }
+  }
   log('✅', `Pool ready (${pressure.running}/${pressure.maxConcurrent} sessions, queued: ${pressure.queued})`);
 
   // Wire up live progress to dashboard if running
@@ -387,10 +435,23 @@ async function cmdPool() {
   }
 }
 
-function cmdInit() {
+async function cmdInit() {
   const cwd = process.cwd();
   const templatesDir = path.join(__dirname, '..', 'templates');
 
+  const skipWizard = hasFlag('--yes') || hasFlag('-y') || hasFlag('--non-interactive');
+  const flagOverrides = {};
+  if (getFlag('--name') && typeof getFlag('--name') === 'string') flagOverrides.projectName = getFlag('--name');
+  if (getFlag('--base-url') && typeof getFlag('--base-url') === 'string') flagOverrides.baseUrl = getFlag('--base-url');
+  if (getFlag('--driver') && typeof getFlag('--driver') === 'string') flagOverrides.driver = getFlag('--driver');
+  if (getFlag('--pool-port') && typeof getFlag('--pool-port') === 'string') flagOverrides.poolPort = parseInt(getFlag('--pool-port'), 10);
+  if (getFlag('--concurrency') && typeof getFlag('--concurrency') === 'string') flagOverrides.concurrency = parseInt(getFlag('--concurrency'), 10);
+  if (hasFlag('--no-sample')) flagOverrides.includeSampleTest = false;
+
+  const answers = skipWizard
+    ? { ...getDefaultAnswers(cwd), ...flagOverrides }
+    : await runInitWizard(cwd, flagOverrides);
+
   // Create directory structure
   const dirs = [
     path.join(cwd, 'e2e', 'tests'),
@@ -405,22 +466,24 @@ function cmdInit() {
     }
   }
 
-  // Copy config template
+  // Write generated config
   const configDest = path.join(cwd, 'e2e.config.js');
   if (!fs.existsSync(configDest)) {
-    fs.copyFileSync(path.join(templatesDir, 'e2e.config.js'), configDest);
+    fs.writeFileSync(configDest, renderConfig(answers));
     log('📄', 'Created e2e.config.js');
   } else {
     log('⏭️', 'e2e.config.js already exists, skipping');
   }
 
   // Copy sample test
-  const testDest = path.join(cwd, 'e2e', 'tests', 'sample.json');
-  if (!fs.existsSync(testDest)) {
-    fs.copyFileSync(path.join(templatesDir, 'sample-test.json'), testDest);
-    log('📄', 'Created e2e/tests/sample.json');
-  } else {
-    log('⏭️', 'e2e/tests/sample.json already exists, skipping');
+  if (answers.includeSampleTest) {
+    const testDest = path.join(cwd, 'e2e', 'tests', 'sample.json');
+    if (!fs.existsSync(testDest)) {
+      fs.copyFileSync(path.join(templatesDir, 'sample-test.json'), testDest);
+      log('📄', 'Created e2e/tests/sample.json');
+    } else {
+      log('⏭️', 'e2e/tests/sample.json already exists, skipping');
+    }
   }
 
   // Create .gitkeep
@@ -455,9 +518,9 @@ ${C.bold}${C.green}E2E structure created!${C.reset}
 
 ${C.bold}Next steps:${C.reset}
   1. Edit ${C.cyan}e2e.config.js${C.reset} with your app URL
-  2. Edit ${C.cyan}e2e/tests/sample.json${C.reset} with your tests
-  3. Start the pool: ${C.cyan}e2e-runner pool start${C.reset}
-  4. Run your tests: ${C.cyan}e2e-runner run --all${C.reset}
+  2. Run your tests: ${C.cyan}e2e-runner run --all${C.reset}  ${C.dim}(starts Chrome automatically)${C.reset}
+
+${C.dim}That's it — the runner spins up the Chrome pool for you on first run.${C.reset}
 `);
 }
 
@@ -1138,7 +1201,7 @@ async function main() {
       break;
 
     case 'init':
-      cmdInit();
+      await cmdInit();
       break;
 
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matware/e2e-runner",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "mcpName": "io.github.fastslack/e2e-runner",
   "description": "E2E test runner using Chrome Pool (browserless/chrome) with parallel execution",
   "type": "module",
@@ -52,7 +52,8 @@
     "puppeteer-core": "^24.0.0"
   },
   "scripts": {
-    "build:dashboard": "node templates/build-dashboard.js"
+    "build:dashboard": "node templates/build-dashboard.js",
+    "prepublishOnly": "node templates/build-dashboard.js"
   },
   "engines": {
     "node": ">=20.0.0"

package/skills/e2e-testing/SKILL.md

@@ -72,8 +72,9 @@ Use `e2e_create_test` to write test files. Use `e2e_create_module` for reusable
 ### 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`
+- **Interaction**: `click` (selector or text; text mode also takes `scope:"dialog"`, `visible:true`, `last:true`), `type`/`fill`, `select`, `press`, `hover`, `scroll`
+- **React/MUI**: `type_react` (controlled inputs; optional `blur`, `waitAfter`), `click_option`, `select_combobox` (open+filter+pick MUI Autocomplete/Select in one action), `focus_autocomplete`, `click_chip`, `click_regex`
+- **Waiting**: prefer conditions over sleeps — `wait` takes `selector`/`text` (appear), `gone` (disappear, e.g. spinner/closing dialog), or `value` (fixed ms, last resort); `wait_network_idle`
 - **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`

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

@@ -13,7 +13,7 @@ Complete catalog of all action types supported by @matware/e2e-runner.
 
 | 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`. |
+| `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`. Optional text-mode refinements: `scope: "dialog"` (only match inside an open `[role="dialog"]`/`.MuiDialog-root`), `visible: true` (skip hidden/zero-size matches — implied by `scope:dialog`), `last: true` (click the LAST match instead of the first). Prefer these over hand-rolled `evaluate` button-by-text scans. |
 | `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. |
@@ -25,9 +25,10 @@ Complete catalog of all action types supported by @matware/e2e-runner.
 
 | 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>`. |
+| `type_react` | `selector`, `value`, `blur` (optional), `waitAfter` (optional ms) | Types into React controlled inputs using native value setter. Focuses, then dispatches `input` + `change` events so React state updates. Supports `<input>` and `<textarea>`. `blur: true` commits on blur (for fields that validate on blur); `waitAfter: "<ms>"` waits after (e.g. for debounced autocomplete). Prefer over inline `setNativeValue` evaluates. |
 | `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. |
+| `select_combobox` | `selector` (optional, default `input[role='combobox']`), `text` (option to pick), `filter` (optional typed text), `openWait`/`filterWait`/`waitAfter` (optional ms) | Open a MUI Autocomplete/Select, optionally type `filter` to narrow, then click the option matching `text` (case-insensitive substring). Falls back across `[role="option"]`, `.MuiAutocomplete-option`, `li.MuiMenuItem-root`. Replaces the verbose open-input + setNativeValue + scan-options `evaluate` pattern. |
 | `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]`. |
 
@@ -75,7 +76,7 @@ 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. |
+| `wait` | `selector` OR `text` OR `gone` OR `value` (ms) | Prefer **conditions over fixed sleeps**: `{ selector }` waits for it to appear, `{ text }` waits for text to appear, **`{ gone: "<css>" }`** waits until a selector disappears/hides (spinner, closing dialog), `{ gone: true, selector|text }` is the explicit form, `{ value: "<ms>" }` is a fixed delay (last resort). Replacing `wait` sleeps with `gone`/`selector` makes suites faster and less flaky. |
 | `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. |
@@ -107,10 +108,27 @@ Delay between retries: `actionRetryDelay` config (default 500ms).
 ### React input + autocomplete flow
 ```json
 { "type": "focus_autocomplete", "text": "Category" },
-{ "type": "type_react", "selector": "#category-input", "value": "Electr" },
+{ "type": "type_react", "selector": "#category-input", "value": "Electr", "waitAfter": "400" },
 { "type": "click_option", "text": "Electronics" }
 ```
 
+### MUI combobox in one action (open + filter + pick)
+```json
+{ "type": "select_combobox", "selector": "[data-cy='specialty'] input", "filter": "cardio", "text": "Cardiología" }
+```
+
+### Condition waits instead of fixed sleeps (faster, less flaky)
+```json
+{ "type": "click", "text": "Guardar" },
+{ "type": "wait", "gone": ".MuiBackdrop-root" },
+{ "type": "wait", "selector": "[data-testid='saved-banner']" }
+```
+
+### Click a button inside an open dialog (no evaluate needed)
+```json
+{ "type": "click", "text": "Iniciar encuentro", "scope": "dialog", "last": true }
+```
+
 ### Regex click (last match)
 ```json
 { "type": "click_regex", "text": "add to cart", "selector": "button", "value": "last" }

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

@@ -113,6 +113,29 @@ Module definition (in `e2e/modules/auth-login.json`):
 }
 ```
 
+### Composing modules (nested `$use` + parameter forwarding)
+
+A module can `$use` other modules, and **forward its own params/defaults** into the
+nested call's `params` block. Placeholders in a nested `params` value are resolved
+against the outer module's scope before the inner module runs:
+
+```json
+{
+  "$module": "login-and-open",
+  "params": {
+    "patientId": { "required": true },
+    "email": { "required": false, "default": "admin@test.com" }
+  },
+  "actions": [
+    { "$use": "auth-login", "params": { "email": "{{email}}", "password": "secret" } },
+    { "$use": "open-patient", "params": { "id": "{{patientId}}" } }
+  ]
+}
+```
+
+Cycles are detected and rejected. Action types are validated **after** all `$use`
+references are expanded.
+
 ## Suite Naming & Ordering
 
 Files can have numeric prefixes for execution order: