@matware/e2e-runner 1.3.0 → 1.5.0

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);
+  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
@@ -351,7 +399,7 @@ async function cmdPool() {
 
     case 'status': {
       const statusPoolUrls = getPoolUrls(config);
-      const aggregated = await getAggregatedPoolStatus(statusPoolUrls);
+      const aggregated = await getAggregatedPoolStatus(statusPoolUrls, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
       console.log(`\n${C.bold}Chrome Pool Status:${C.reset}\n`);
 
       if (statusPoolUrls.length > 1) {
@@ -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}
 `);
 }
 
@@ -494,11 +557,12 @@ async function cmdCapture() {
 
   const capturePoolUrls = getPoolUrls(config);
   log('🔌', 'Checking Chrome Pool...');
-  await waitForAnyPool(capturePoolUrls);
+  const captureDriverOpts = { poolDriver: config.poolDriver, maxSessions: config.maxSessions };
+  await waitForAnyPool(capturePoolUrls, 30000, captureDriverOpts);
 
   let browser;
   try {
-    const capturePool = await selectPool(capturePoolUrls);
+    const capturePool = await selectPool(capturePoolUrls, 2000, 60000, captureDriverOpts);
     browser = await connectToPool(capturePool);
     const page = await browser.newPage();
     await page.setViewport(config.viewport);
@@ -1137,7 +1201,7 @@ async function main() {
       break;
 
     case 'init':
-      cmdInit();
+      await cmdInit();
       break;
 
     default:

package/commands/capture.md

@@ -0,0 +1,45 @@
+---
+description: Capture a screenshot of any URL with automatic authentication
+user_invocable: true
+allowed_tools:
+  - mcp__e2e-runner__e2e_pool_status
+  - mcp__e2e-runner__e2e_capture
+  - mcp__e2e-runner__e2e_analyze
+  - mcp__e2e-runner__e2e_screenshot
+---
+
+# Quick Capture
+
+Take a screenshot of any URL in one step. Handles pool checks and authentication automatically.
+
+## Workflow
+
+1. **Check pool** — 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 and stop.
+
+2. **Capture** — Call `e2e_capture` with:
+   - `url`: The URL from the user's request (REQUIRED)
+   - `cwd`: The current working directory (REQUIRED — always pass this)
+   - `fullPage`: true if user says "full page", "full", "complete", or "toda la página"
+   - `selector`: CSS selector if user wants to wait for a specific element
+   - `delay`: milliseconds if user says "wait", "delay", or "espera"
+   - `waitUntil`: "domcontentloaded" if user mentions WebSocket, SSE, or real-time apps
+   - `filename`: if user specifies a name
+
+   **Authentication is automatic**: the tool reads `authToken`, `authLoginEndpoint`, and `authCredentials` from the project's `e2e.config.js`. You do NOT need to pass `authToken` unless the user explicitly provides one.
+
+3. **Show result** — The tool returns the screenshot as an inline image. Show it to the user with the file path.
+
+## Arguments
+
+The user passes the URL after the command:
+- `/e2e-runner:capture http://localhost:3000/dashboard` → capture that URL
+- `/e2e-runner:capture http://localhost/concept-maps --full-page` → full page capture
+- `/e2e-runner:capture http://localhost/admin --delay 3000` → wait 3s before capture
+
+If no URL is provided, ask the user for one.
+
+## Important
+
+- Do NOT try to manually authenticate, fetch tokens, write test files, or use curl. The tool handles auth automatically from project config.
+- Do NOT use the `e2e_run` tool — this is a screenshot capture, not a test run.
+- Keep it simple: one `e2e_pool_status` call + one `e2e_capture` call. That's it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matware/e2e-runner",
-  "version": "1.3.0",
+  "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: