@matware/e2e-runner 1.3.1 → 1.5.1

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

@@ -24,9 +24,9 @@ You are a specialist in refactoring and optimizing existing E2E tests without ch
 
 - **Evaluate replacement**: Replace verbose `evaluate` actions with equivalent built-in actions (`type_react`, `click_option`, `assert_element_text`, etc.)
 - **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)
+- **Selector hardening**: Replace brittle selectors (nth-child, deep nesting, generated classes) with stable alternatives (`data-testid`, `id`, text-based). Applies to *interaction* selectors only — assertion selectors are treated as stable contracts (see Rules)
 - **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 |
@@ -165,6 +167,7 @@ When extracting to a module, use `{{param}}` placeholders for values that vary b
 4. **Preserve test ordering** — don't reorder tests within a suite. Numeric prefix ordering is intentional.
 5. **Keep evaluates when no built-in exists** — if the evaluate does something that no built-in action covers (e.g., complex DOM manipulation, localStorage checks), leave it as-is.
 6. **Prefer selector waits over fixed delays** — replace `{ "type": "wait", "value": "3000" }` with `{ "type": "wait", "selector": ".expected-element" }` when possible. Only keep fixed delays when there's genuinely no element to wait for.
+7. **Assertion selectors are the contract** — interaction selectors may heal, but never retarget the `selector` of an `assert_*` action while hardening: that silently changes *what* the test verifies. If an assertion selector is genuinely broken, pin it to a stable `data-testid` and call it out in the summary instead of swapping it for whatever makes the test green.
 
 ## Output
 

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
  */
@@ -34,6 +35,7 @@ import { loadConfig } from '../src/config.js';
 import { startPool, stopPool, restartPool, connectToPool } from '../src/pool.js';
 import { getPoolUrls, getAggregatedPoolStatus, waitForAnyPool, selectPool } from '../src/pool-manager.js';
 import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from '../src/runner.js';
+import { looksLikeBlankCapture } from '../src/actions.js';
 import { generateReport, saveReport, printReport, persistRun, printInsights } from '../src/reporter.js';
 import { startDashboard } from '../src/dashboard.js';
 import { startWatch } from '../src/watch.js';
@@ -43,6 +45,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 +121,8 @@ function parseCLIConfig() {
       cliArgs.verificationStrictness = val;
     }
   }
+  if (getFlag('--driver')) cliArgs.cliDriverOverride = getFlag('--driver');
+  if (getFlag('--fallback-driver')) cliArgs.cliFallbackDriverOverride = getFlag('--fallback-driver');
   return cliArgs;
 }
 
@@ -148,6 +153,7 @@ ${C.bold}Usage:${C.reset}
   e2e-runner capture <url> --selector <sel>  Wait for selector before capture
   e2e-runner capture <url> --delay <ms> Wait before capturing
   e2e-runner capture <url> --filename <name> Custom filename
+  e2e-runner capture <url> --force      Save even if the frame is blank
 
   e2e-runner issue <url>                Fetch issue and show details
   e2e-runner issue <url> --generate     Generate test file via Claude API
@@ -175,7 +181,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 +208,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 +232,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 +289,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 +437,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 +468,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 +520,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}
 `);
 }
 
@@ -483,7 +548,7 @@ async function cmdDashboard() {
 async function cmdCapture() {
   const url = args[1];
   if (!url || url.startsWith('--')) {
-    console.error(`${C.red}Usage: e2e-runner capture <url> [--filename <name>] [--full-page] [--selector <sel>] [--delay <ms>]${C.reset}`);
+    console.error(`${C.red}Usage: e2e-runner capture <url> [--filename <name>] [--full-page] [--selector <sel>] [--delay <ms>] [--force]${C.reset}`);
     process.exit(1);
   }
 
@@ -529,7 +594,16 @@ async function cmdCapture() {
 
     const screenshotPath = path.join(config.screenshotsDir, filename);
     const fullPage = hasFlag('--full-page');
-    await page.screenshot({ path: screenshotPath, fullPage });
+    const captureBuf = await page.screenshot({ fullPage });
+
+    // Blank frame (uniform color — page never rendered): skip the save
+    // unless the user explicitly forces it.
+    if (!hasFlag('--force') && looksLikeBlankCapture(captureBuf, 'png')) {
+      log('⚠️', `${C.yellow}Capture skipped:${C.reset} page rendered a blank (uniform-color) frame — nothing saved. Use ${C.dim}--force${C.reset} to save anyway.`);
+      console.log('');
+      return;
+    }
+    fs.writeFileSync(screenshotPath, captureBuf);
 
     // Register hash in SQLite
     const cwd = process.cwd();
@@ -1138,7 +1212,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.1",
   "mcpName": "io.github.fastslack/e2e-runner",
   "description": "E2E test runner using Chrome Pool (browserless/chrome) with parallel execution",
   "type": "module",
@@ -39,7 +39,7 @@
     "github-issues",
     "ai-testing"
   ],
-  "author": "Matware",
+  "author": "Matias Aguirre (Matware)",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -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

@@ -9,7 +9,7 @@ description: Create, run, and debug JSON-driven E2E browser tests with Chrome po
 
 `@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.
+**Key capabilities:** 17 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
 
@@ -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`
@@ -158,6 +159,7 @@ Start/stop the web dashboard with `e2e_dashboard_start` / `e2e_dashboard_stop` f
 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.
+7. **Assertion selectors are the contract** — when fixing flaky tests, heal *interaction* selectors freely, but never retarget an `assert_*` selector to make a test pass: pin assertion selectors to stable `data-testid`s.
 
 ## References
 

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]`. |
 
@@ -46,11 +47,25 @@ Complete catalog of all action types supported by @matware/e2e-runner.
 | `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. |
 
+## Multi-Tab
+
+All subsequent actions run in the active tab. The runner manages a tab registry keyed by label.
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `open_tab` | `value` (URL), `text` (label, optional) | Open a new tab and navigate (relative to `baseUrl` or absolute). Label defaults to `tab-<n>`. The new tab becomes active. |
+| `switch_tab` | `value` | Switch active tab by label (exact), numeric index, or title/URL match (regex or substring). `"default"` returns to the original tab. |
+| `wait_for_tab` | `text` (label, optional), `timeout` | Wait for a tab/popup opened by the app (`window.open`, `target="_blank"`) and make it active. Use right after the action that triggers the popup. |
+| `assert_tab_count` | `value` | Assert number of open tabs: exact (`"2"`) or operators (`">=2"`). |
+| `close_tab` | `value` (label, optional) | Close the current (or named) tab and switch back to the last remaining one. Cannot close `default` while other tabs are open. |
+
 ## Assertions
 
 | Action | Fields | Description |
 |--------|--------|-------------|
 | `assert_text` | `text` | Check entire page body contains text (substring match). |
+| `assert_no_text` | `text` | Check text does NOT appear anywhere in the page body. Opposite of `assert_text`. |
+| `assert_text_in` | `selector`, `text`, `value` (`"exact"` optional) | Check text inside a scoped container. Joins `textContent` from all matching elements. Default: case-insensitive regex; with `value: "exact"`: case-sensitive substring. |
 | `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). |
@@ -61,11 +76,14 @@ Complete catalog of all action types supported by @matware/e2e-runner.
 | `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. |
+| `assert_visual` | `value` (golden image filename), `selector` (optional element scope), `text` (max diff fraction, e.g. `"0.02"`), plus `fullPage`, `maskRegions`, `threshold` | Visual regression against a golden reference image (`goldenDir`, default `{screenshotsDir}/golden`). First run saves the golden and passes; later runs fail if more pixels differ than the max diff (default 2%) and write a diff image. `maskRegions: [{x,y,width,height}]` ignores dynamic areas (timestamps, avatars). |
 
 ### Assertion Disambiguation
 
 - **`assert_text`** → searches the **entire page body** (substring)
+- **`assert_no_text`** → asserts text is **absent** from the page body (do NOT use `assert_not_visible` with `text` — it requires `selector`)
 - **`assert_element_text`** → checks a **specific element** (substring, or exact with `value: "exact"`)
+- **`assert_text_in`** → checks text inside a **scoped container** (regex by default)
 - **`assert_matches`** → checks a specific element against a **regex** pattern
 - **`assert_input_value`** → reads the `.value` property (for form fields)
 
@@ -75,7 +93,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,31 +125,30 @@ 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" }
 ```
 
-### Regex click (last match)
+### MUI combobox in one action (open + filter + pick)
 ```json
-{ "type": "click_regex", "text": "add to cart", "selector": "button", "value": "last" }
+{ "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']" }
 ```
 
-### Form validation assertions
+### Click a button inside an open dialog (no evaluate needed)
 ```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" }
+{ "type": "click", "text": "Iniciar encuentro", "scope": "dialog", "last": true }
 ```
 
-### Storage operations
+### Regex click (last match)
 ```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" }
+{ "type": "click_regex", "text": "add to cart", "selector": "button", "value": "last" }
 ```
 
 ### Icon, menu, and contextual clicks

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:

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

@@ -193,32 +193,8 @@ The `KNOWN_ACTION_TYPES` Set in `src/actions.js` is the single source of truth.
 
 ## Screenshot Hashes
 
-Every screenshot captured during a run is assigned a short hash (`ss:a3f2b1c9`) — the first 8 hex chars of the SHA-256 of its file path. Hashes are deterministic and computed identically on the server (Node `crypto`) and in the browser (Web Crypto API).
-
-**Flow**: screenshot saved on disk → `saveRun()` registers hash in SQLite `screenshot_hashes` table → dashboard shows `[ss:XXXXXXXX]` badge (click to copy) → user pastes hash in Claude Code → `e2e_screenshot` MCP tool looks up hash, reads file, returns the image.
-
-- Hashes are registered inside the `saveRun()` transaction (covers action, error, verification, and baseline screenshots)
-- The `ss:` prefix is optional when calling `e2e_screenshot` — stripped during lookup
-- Dashboard computes hashes client-side (Web Crypto) for the Live view (before `persistRun()` writes to DB)
-- Run detail API (`/api/db/runs/:id`) includes `screenshotHashes` map per test result
-- Dashboard endpoint `/api/screenshot-hash/:hash` serves the image by hash
-- Dashboard Screenshots view has a **search bar** — type a hash to find and display the screenshot
+Every screenshot gets a short hash like `ss:a3f2b1c9` (deterministic, from its file path). The dashboard shows it as a click-to-copy badge; paste it (the `ss:` prefix is optional) and `e2e_screenshot` returns the image. The dashboard Screenshots view also has a hash search bar.
 
 ## Web Dashboard
 
-**`src/dashboard.js`** — HTTP server, REST API, WebSocket broadcast, pool polling.
-**`templates/dashboard.html`** — SPA, dark theme, vanilla JS, safe DOM (textContent + createEl helper).
-
-**Features:**
-- Live test execution with WebSocket updates
-- Run history with inline detail expansion
-- Screenshots gallery with hash badges and hash search
-- Network request logs with clickable expandable rows (full request/response detail)
-- Pool status monitoring
-- Multi-project support via project selector
-- Variables tab with masked values, inline edit, add, and delete
-
-**CLI:** `e2e-runner dashboard [--port 8484]`
-**MCP tools:** `e2e_dashboard_start`, `e2e_dashboard_stop`
-
-Config defaults: `dashboardPort: 8484`, `maxHistoryRuns: 100`
+Start with `e2e_dashboard_start` (or `e2e-runner dashboard [--port 8484]`), stop with `e2e_dashboard_stop`. Provides live execution (WebSocket), run history, screenshot gallery + hash search, expandable network logs, pool status, multi-project selector, and a variables tab.