@matware/e2e-runner 1.3.1 → 1.5.1

package/src/runner.js

@@ -9,10 +9,11 @@ import fs from 'fs';
 import path from 'path';
 import http from 'http';
 import https from 'https';
+import crypto from 'crypto';
 import { connectToPool, getCachedDriver, disconnectFromPool } from './pool.js';
-import { getPoolUrls, selectPool, releasePending } from './pool-manager.js';
+import { getPoolUrls, selectPool, releasePending, resolvePoolsForTest } from './pool-manager.js';
 import { forkAppInstance, destroyFork, isAppPoolEnabled } from './app-pool.js';
-import { executeAction } from './actions.js';
+import { executeAction, pageHasRenderableContent, looksLikeBlankCapture } from './actions.js';
 import { narrateAction } from './narrate.js';
 import { log, colors as C } from './logger.js';
 import { resolveTestData, validateActionTypes } from './module-resolver.js';
@@ -23,6 +24,81 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * Best-effort step thumbnail for the storyline view.
+ * Captures once in memory, writes to disk AND returns base64 so callers
+ * can stream the same frame through the live preview WebSocket.
+ * Skips silently on any error so it never breaks a test run.
+ *
+ * Content dedup: when the captured frame is byte-identical to the previous
+ * step's frame (tracked per-test via dedupState), reuses the existing file
+ * instead of writing a duplicate, and skips re-streaming the live frame.
+ *
+ * Raw data responses (JSON/plain-text endpoints rendered by Chrome's viewer
+ * as a white page with a single <pre>) are NOT screenshotted — the body is
+ * saved as a minified .json sidecar instead and returned as { dataPath }.
+ */
+const NO_AUTO_CAPTURE_TYPES = new Set(['screenshot', 'close_tab']);
+async function tryAutoCaptureStep(page, action, idx, testName, effectiveConfig, alreadyCaptured, dedupState) {
+  if (!effectiveConfig.autoCaptureSteps) return null;
+  if (NO_AUTO_CAPTURE_TYPES.has(action?.type)) return null;
+  if (alreadyCaptured) return null;
+  if (!page || (typeof page.isClosed === 'function' && page.isClosed())) return null;
+  // Skip auto-capture when the page can't produce a meaningful image —
+  // about:blank or fully empty DOM — to stop blank step-*.jpg flooding.
+  if (!(await pageHasRenderableContent(page))) return null;
+  try {
+    const safeName = String(testName).replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+    // Raw JSON/text response? Save the body as data, not as a white JPEG.
+    const rawBody = await page.evaluate(() => {
+      const ct = document.contentType || '';
+      const b = document.body;
+      const lonePre = !!(b && b.children.length === 1 && b.children[0].tagName === 'PRE' && b.children[0].children.length === 0);
+      if ((ct && ct !== 'text/html') || lonePre) return (b && b.innerText) || '';
+      return null;
+    }).catch(() => null);
+    if (rawBody !== null) {
+      let text = rawBody.trim();
+      if (!text) return null;
+      try { text = JSON.stringify(JSON.parse(text)); } catch { /* not JSON — keep raw text */ }
+      const dataBuf = Buffer.from(text, 'utf8');
+      const dataHash = crypto.createHash('sha1').update(dataBuf).digest('hex');
+      if (dedupState && dedupState.hash === dataHash && dedupState.path) {
+        return { dataPath: dedupState.path, deduped: true };
+      }
+      const dataPath = path.join(effectiveConfig.screenshotsDir, `step-${safeName}-${String(idx).padStart(3, '0')}-${Date.now()}.json`);
+      fs.writeFileSync(dataPath, dataBuf);
+      if (dedupState) {
+        dedupState.hash = dataHash;
+        dedupState.path = dataPath;
+      }
+      return { dataPath };
+    }
+    const filename = `step-${safeName}-${String(idx).padStart(3, '0')}-${Date.now()}.jpg`;
+    const filepath = path.join(effectiveConfig.screenshotsDir, filename);
+    const buf = await page.screenshot({
+      type: 'jpeg',
+      quality: effectiveConfig.autoCaptureQuality ?? 60,
+      fullPage: false,
+      encoding: 'binary',
+    });
+    if (looksLikeBlankCapture(buf, 'jpeg')) return null;
+    const contentHash = crypto.createHash('sha1').update(buf).digest('hex');
+    if (dedupState && dedupState.hash === contentHash && dedupState.path) {
+      // Same frame as the previous step — reuse the file, don't re-stream
+      return { path: dedupState.path, base64: null, deduped: true };
+    }
+    fs.writeFileSync(filepath, buf);
+    if (dedupState) {
+      dedupState.hash = contentHash;
+      dedupState.path = filepath;
+    }
+    return { path: filepath, base64: buf.toString('base64') };
+  } catch {
+    return null;
+  }
+}
+
 /** Simple glob matching with * wildcards for exclude patterns. */
 function matchesExclude(filename, excludePatterns) {
   if (!excludePatterns?.length) return false;
@@ -190,9 +266,24 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
     }
 
     const driverOpts = { poolDriver: config.poolDriver || 'auto', maxSessions: config.maxSessions || 10 };
-    const chosenPool = await selectPool(getPoolUrls(config), 2000, 60000, driverOpts);
+
+    // CLI override (--driver / --fallback-driver) wins over per-test fields.
+    const requestedDriver = config.cliDriverOverride || test.driver || null;
+    const requestedFallback = config.cliFallbackDriverOverride || test.fallbackDriver || null;
+
+    let candidatePoolUrls = getPoolUrls(config);
+    let driverChoice = null;
+    if (requestedDriver) {
+      const resolved = await resolvePoolsForTest(candidatePoolUrls, requestedDriver, requestedFallback, driverOpts);
+      candidatePoolUrls = resolved.urls;
+      driverChoice = { requested: requestedDriver, used: resolved.driver, usedFallback: resolved.usedFallback };
+      log('🎯', `${C.dim}${test.name}: driver=${resolved.driver}${resolved.usedFallback ? ' (fallback)' : ''}${C.reset}`);
+    }
+
+    const chosenPool = await selectPool(candidatePoolUrls, 2000, 60000, driverOpts);
     result.poolUrl = chosenPool;
     result.poolDriver = getCachedDriver(chosenPool);
+    if (driverChoice) result.driverChoice = driverChoice;
     const poolLabel = chosenPool.replace('ws://', '').replace('wss://', '');
     const isMultiPool = getPoolUrls(config).length > 1;
     if (isMultiPool) {
@@ -236,9 +327,13 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
           maxHeight: config.screencastMaxHeight || 600,
           everyNthFrame: 1,
         }), 5000);
-      } catch {
+        log('📹', `${C.dim}screencast started for ${test.name} (driver=${poolDriver})${C.reset}`);
+      } catch (err) {
+        log('⚠️', `${C.amber}screencast failed for ${test.name}: ${err.message} (driver=${poolDriver})${C.reset}`);
         cdpSession = null;
       }
+    } else if (config.screencast && poolDriver === 'cdp') {
+      log('⚠️', `${C.amber}screencast disabled: pool driver is generic CDP (Lightpanda?), not supported${C.reset}`);
     }
 
     page.on('console', (msg) => {
@@ -304,16 +399,25 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
       await executeHookActions(page, hooks.beforeEach, effectiveConfig);
     }
 
-    // Auto-capture baseline screenshot if test has "expect" (BEFORE actions)
+    // Auto-capture baseline screenshot if test has "expect" (BEFORE actions).
+    // Blank frames (about:blank, white unrendered page) are not saved —
+    // they have no comparison value and pollute screenshotsDir.
     if (test.expect && page) {
       try {
-        const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
-        const baselinePath = path.join(effectiveConfig.screenshotsDir, `baseline-${safeName}-${Date.now()}.png`);
-        await page.screenshot({ path: baselinePath, fullPage: true });
-        result.baselineScreenshot = baselinePath;
+        const baseBuf = await page.screenshot({ fullPage: true });
+        if (!looksLikeBlankCapture(baseBuf, 'png')) {
+          const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+          const baselinePath = path.join(effectiveConfig.screenshotsDir, `baseline-${safeName}-${Date.now()}.png`);
+          fs.writeFileSync(baselinePath, baseBuf);
+          result.baselineScreenshot = baselinePath;
+        }
       } catch { /* page may not be ready */ }
     }
 
+    // Tracks the last auto-captured frame (content hash + path) so identical
+    // consecutive step screenshots reuse the same file instead of duplicating
+    const stepCaptureState = { hash: null, path: null };
+
     for (let i = 0; i < test.actions.length; i++) {
       const action = test.actions[i];
       const maxActionRetries = action.retries ?? effectiveConfig.actionRetries ?? 0;
@@ -440,16 +544,21 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
             actionResult = await executeAction(page, action, effectiveConfig);
           }
           const actionDuration = Date.now() - actionStart;
+          const autoShot = await tryAutoCaptureStep(page, action, i, test.name, effectiveConfig, !!actionResult?.screenshot, stepCaptureState);
           const actionEntry = {
             ...action,
             success: true,
             duration: actionDuration,
             result: actionResult,
           };
+          if (autoShot?.path) actionEntry.autoScreenshot = autoShot.path;
+          if (autoShot?.dataPath) actionEntry.dataCapture = autoShot.dataPath;
           if (attempt > 0) actionEntry.actionRetries = attempt;
           actionEntry.narrative = narrateAction(action, actionEntry);
           result.actions.push(actionEntry);
-          progressFn({ event: 'test:action', name: test.name, action, actionIndex: i, totalActions: test.actions.length, success: true, duration: actionDuration, narrative: actionEntry.narrative, screenshotPath: actionResult?.screenshot || null });
+          progressFn({ event: 'test:action', name: test.name, action, actionIndex: i, totalActions: test.actions.length, success: true, duration: actionDuration, narrative: actionEntry.narrative, screenshotPath: actionResult?.screenshot || null, autoScreenshot: autoShot?.path || null });
+          // Stream the auto-capture as a live frame so the storyline player has something to show even when CDP screencast is silent
+          if (autoShot?.base64) progressFn({ event: 'test:frame', name: test.name, data: autoShot.base64, source: 'step' });
           lastError = null;
           break;
         } catch (error) {
@@ -460,16 +569,20 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
             continue;
           }
           const actionDuration = Date.now() - actionStart;
+          const autoShot = await tryAutoCaptureStep(page, action, i, test.name, effectiveConfig, false, stepCaptureState);
           const failedEntry = {
             ...action,
             success: false,
             duration: actionDuration,
             error: error.message,
           };
+          if (autoShot?.path) failedEntry.autoScreenshot = autoShot.path;
+          if (autoShot?.dataPath) failedEntry.dataCapture = autoShot.dataPath;
           if (maxActionRetries > 0) failedEntry.actionRetries = attempt;
           failedEntry.narrative = narrateAction(action, failedEntry);
           result.actions.push(failedEntry);
-          progressFn({ event: 'test:action', name: test.name, action, actionIndex: i, totalActions: test.actions.length, success: false, duration: actionDuration, narrative: failedEntry.narrative, error: error.message });
+          progressFn({ event: 'test:action', name: test.name, action, actionIndex: i, totalActions: test.actions.length, success: false, duration: actionDuration, narrative: failedEntry.narrative, error: error.message, autoScreenshot: autoShot?.path || null });
+          if (autoShot?.base64) progressFn({ event: 'test:frame', name: test.name, data: autoShot.base64, source: 'step' });
           throw error;
         }
       }
@@ -481,14 +594,18 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
       throw new Error(`Network errors detected (failOnNetworkError=true): ${result.networkErrors.length} error(s): ${summary}`);
     }
 
-    // Auto-capture verification screenshot if test has "expect"
+    // Auto-capture verification screenshot if test has "expect".
+    // Blank frames are skipped (not saved) — same guard as the baseline.
     if (test.expect && page) {
       result.expect = test.expect;
       try {
         const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
-        const verifyPath = path.join(effectiveConfig.screenshotsDir, `verify-${safeName}-${Date.now()}.png`);
-        await page.screenshot({ path: verifyPath, fullPage: true });
-        result.verificationScreenshot = verifyPath;
+        const verifyBuf = await page.screenshot({ fullPage: true });
+        if (!looksLikeBlankCapture(verifyBuf, 'png')) {
+          const verifyPath = path.join(effectiveConfig.screenshotsDir, `verify-${safeName}-${Date.now()}.png`);
+          fs.writeFileSync(verifyPath, verifyBuf);
+          result.verificationScreenshot = verifyPath;
+        }
 
         // Auto visual comparison: compare baseline vs verification screenshot
         if (result.baselineScreenshot && result.verificationScreenshot) {
@@ -532,10 +649,18 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
 
     if (page) {
       try {
-        const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
-        const errorScreenshot = path.join(config.screenshotsDir, `error-${safeName}-${Date.now()}.png`);
-        await page.screenshot({ path: errorScreenshot, fullPage: true });
-        result.errorScreenshot = errorScreenshot;
+        // Only capture when the page actually has something to show.
+        // about:blank / empty-DOM failures produced 5KB blank PNGs that
+        // accumulated in screenshotsDir with no debug value.
+        if (await pageHasRenderableContent(page)) {
+          const errBuf = await page.screenshot({ fullPage: true });
+          if (!looksLikeBlankCapture(errBuf, 'png')) {
+            const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+            const errorScreenshot = path.join(config.screenshotsDir, `error-${safeName}-${Date.now()}.png`);
+            fs.writeFileSync(errorScreenshot, errBuf);
+            result.errorScreenshot = errorScreenshot;
+          }
+        }
       } catch { /* page may be dead */ }
     }
   } finally {

package/src/visual-diff.js

@@ -32,11 +32,12 @@ function readChunks(buf) {
   return chunks;
 }
 
-function decodePNG(filePath) {
-  const buf = fs.readFileSync(filePath);
+function decodePNG(input) {
+  // Accepts a file path or an in-memory PNG Buffer (capture-time checks).
+  const buf = Buffer.isBuffer(input) ? input : fs.readFileSync(input);
 
-  if (buf.compare(PNG_SIGNATURE, 0, 8, 0, 8) !== 0) {
-    throw new Error(`Not a valid PNG file: ${filePath}`);
+  if (buf.length < 8 || buf.compare(PNG_SIGNATURE, 0, 8, 0, 8) !== 0) {
+    throw new Error(`Not a valid PNG file: ${Buffer.isBuffer(input) ? '<buffer>' : input}`);
   }
 
   const chunks = readChunks(buf);
@@ -444,3 +445,72 @@ function buildMaskLookup(regions, imgWidth, imgHeight) {
     return (mask[bit >> 3] & (1 << (bit & 7))) !== 0;
   };
 }
+
+// ── Blank screenshot detection ─────────────────────────────────────────────
+/**
+ * Detects whether a PNG screenshot is "completely blank" — i.e. a single
+ * uniform fill color (a white/empty page, a solid error frame, etc.).
+ *
+ * Strategy: decode to RGBA, sample pixels evenly (capped for speed), compute
+ * the mean color, then count how many sampled pixels deviate from that mean by
+ * more than `tolerance` on any channel. An image is blank when the fraction of
+ * deviating pixels stays at/under `maxOutlierFraction` — this tolerates a few
+ * stray pixels (a cursor, a 1px border) while still requiring a near-uniform
+ * frame. Non-PNG or undecodable files are reported as not-blank so they are
+ * never deleted by mistake.
+ *
+ * @param {string|Buffer} input — PNG file path, or an in-memory PNG buffer
+ * @param {{tolerance?:number, maxOutlierFraction?:number, maxSamples?:number}} [opts]
+ * @returns {{blank:boolean, color?:{r:number,g:number,b:number}, brightness?:number,
+ *            width?:number, height?:number, outlierFraction?:number, error?:string}}
+ */
+export function isBlankImage(input, opts = {}) {
+  const tolerance = opts.tolerance ?? 10;
+  const maxOutlierFraction = opts.maxOutlierFraction ?? 0.005; // ≤0.5% off-color pixels
+  const maxSamples = opts.maxSamples ?? 120000;
+
+  let img;
+  try {
+    img = decodePNG(input);
+  } catch (error) {
+    return { blank: false, error: error.message };
+  }
+
+  const { width, height, data } = img;
+  const totalPixels = width * height;
+  if (totalPixels === 0) return { blank: false, width, height };
+
+  // Even sampling stride so huge captures stay fast without missing regions.
+  const step = Math.max(1, Math.floor(totalPixels / maxSamples));
+
+  let sumR = 0, sumG = 0, sumB = 0, n = 0;
+  for (let p = 0; p < totalPixels; p += step) {
+    const i = p * 4;
+    sumR += data[i]; sumG += data[i + 1]; sumB += data[i + 2];
+    n++;
+  }
+  const meanR = sumR / n, meanG = sumG / n, meanB = sumB / n;
+
+  let outliers = 0;
+  for (let p = 0; p < totalPixels; p += step) {
+    const i = p * 4;
+    if (Math.abs(data[i] - meanR) > tolerance ||
+        Math.abs(data[i + 1] - meanG) > tolerance ||
+        Math.abs(data[i + 2] - meanB) > tolerance) {
+      outliers++;
+    }
+  }
+
+  const outlierFraction = outliers / n;
+  const color = { r: Math.round(meanR), g: Math.round(meanG), b: Math.round(meanB) };
+  const brightness = Math.round((meanR + meanG + meanB) / 3);
+
+  return {
+    blank: outlierFraction <= maxOutlierFraction,
+    color,
+    brightness,
+    width,
+    height,
+    outlierFraction: Math.round(outlierFraction * 1e4) / 1e4,
+  };
+}

package/src/websocket.js

@@ -81,10 +81,21 @@ export function createWebSocketServer(httpServer, options = {}) {
   const clients = new Set();
 
   httpServer.on('upgrade', (req, socket, head) => {
-    // Validate Origin to prevent cross-site WebSocket hijacking
+    // Validate Origin to prevent cross-site WebSocket hijacking.
+    // Allow if: no Origin (curl/scripts), explicit whitelist match, or same-origin
+    // (Origin's host == the Host header the client connected to).
     const origin = req.headers.origin;
-    if (origin && options.allowedOrigins) {
-      if (!options.allowedOrigins.includes(origin)) {
+    const host = req.headers.host;
+    if (origin) {
+      let allowed = false;
+      if (options.allowedOrigins && options.allowedOrigins.includes(origin)) allowed = true;
+      if (!allowed && host) {
+        try {
+          const u = new URL(origin);
+          if (u.host === host) allowed = true;
+        } catch { /* malformed origin */ }
+      }
+      if (!allowed) {
         socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
         socket.destroy();
         return;

package/src/wizard.js

@@ -0,0 +1,184 @@
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import path from 'node:path';
+import { colors as C } from './logger.js';
+
+const DRIVERS = ['browserless', 'cdp', 'steel', 'lightpanda'];
+const OUTPUT_FORMATS = ['json', 'junit', 'both'];
+
+function isInteractive() {
+  return Boolean(input.isTTY && output.isTTY);
+}
+
+function defaultAnswers(cwd) {
+  return {
+    projectName: path.basename(cwd),
+    baseUrl: 'http://host.docker.internal:3000',
+    driver: 'browserless',
+    poolPort: 3333,
+    concurrency: 3,
+    maxSessions: 5,
+    outputFormat: 'json',
+    includeSampleTest: true,
+  };
+}
+
+export function getDefaultAnswers(cwd) {
+  return defaultAnswers(cwd);
+}
+
+async function ask(rl, question, fallback, validate) {
+  const hint = fallback === '' ? '' : ` ${C.dim}(${fallback})${C.reset}`;
+  for (;;) {
+    const raw = (await rl.question(`${C.cyan}?${C.reset} ${question}${hint} `)).trim();
+    const value = raw === '' ? fallback : raw;
+    if (validate) {
+      const err = validate(value);
+      if (err) {
+        console.log(`  ${C.red}${err}${C.reset}`);
+        continue;
+      }
+    }
+    return value;
+  }
+}
+
+async function askChoice(rl, question, choices, fallback) {
+  const list = choices.map((c, i) => `${i + 1}) ${c}${c === fallback ? ' [default]' : ''}`).join('  ');
+  for (;;) {
+    const raw = (await rl.question(`${C.cyan}?${C.reset} ${question}\n  ${C.dim}${list}${C.reset}\n  `)).trim();
+    if (raw === '') return fallback;
+    const asNum = parseInt(raw, 10);
+    if (!Number.isNaN(asNum) && asNum >= 1 && asNum <= choices.length) return choices[asNum - 1];
+    if (choices.includes(raw)) return raw;
+    console.log(`  ${C.red}Choose 1-${choices.length} or one of: ${choices.join(', ')}${C.reset}`);
+  }
+}
+
+async function askYesNo(rl, question, fallback = true) {
+  const hint = fallback ? 'Y/n' : 'y/N';
+  const raw = (await rl.question(`${C.cyan}?${C.reset} ${question} ${C.dim}(${hint})${C.reset} `)).trim().toLowerCase();
+  if (raw === '') return fallback;
+  return raw === 'y' || raw === 'yes' || raw === 's' || raw === 'si';
+}
+
+function validateUrl(value) {
+  try {
+    const u = new URL(value);
+    if (!['http:', 'https:'].includes(u.protocol)) return 'Use http:// or https://';
+    return null;
+  } catch {
+    return 'Not a valid URL';
+  }
+}
+
+function validatePositiveInt(value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) return 'Must be a positive integer';
+  return null;
+}
+
+export async function runInitWizard(cwd, overrides = {}) {
+  const defaults = { ...defaultAnswers(cwd), ...overrides };
+
+  if (!isInteractive()) return defaults;
+
+  console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner — init wizard${C.reset}`);
+  console.log(`${C.dim}Press Enter to accept the default in parentheses.${C.reset}\n`);
+
+  const rl = readline.createInterface({ input, output });
+
+  try {
+    const projectName = await ask(rl, 'Project name', defaults.projectName);
+    const baseUrl = await ask(rl, 'App base URL', defaults.baseUrl, validateUrl);
+    const driver = await askChoice(rl, 'Browser driver', DRIVERS, defaults.driver);
+    const poolPort = parseInt(await ask(rl, 'Chrome pool port', String(defaults.poolPort), validatePositiveInt), 10);
+    const concurrency = parseInt(await ask(rl, 'Parallel test workers', String(defaults.concurrency), validatePositiveInt), 10);
+    const maxSessions = parseInt(await ask(rl, 'Max concurrent pool sessions', String(defaults.maxSessions), validatePositiveInt), 10);
+    const outputFormat = await askChoice(rl, 'Report output format', OUTPUT_FORMATS, defaults.outputFormat);
+    const includeSampleTest = await askYesNo(rl, 'Include a sample test?', defaults.includeSampleTest);
+
+    return {
+      projectName,
+      baseUrl,
+      driver,
+      poolPort,
+      concurrency,
+      maxSessions,
+      outputFormat,
+      includeSampleTest,
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+export function renderConfig(answers) {
+  const { projectName, baseUrl, driver, poolPort, concurrency, maxSessions, outputFormat } = answers;
+  const driverLine = driver === 'browserless'
+    ? ''
+    : `\n  // Browser driver: 'browserless' | 'cdp' | 'steel' | 'lightpanda'\n  driver: '${driver}',\n`;
+
+  return `export default {
+  // Display name shown in the dashboard
+  projectName: '${projectName}',
+
+  // App URL (from inside Docker, use host.docker.internal to reach the host)
+  baseUrl: '${baseUrl}',
+${driverLine}
+  // Chrome Pool WebSocket URL
+  poolUrl: 'ws://localhost:${poolPort}',
+
+  // Chrome Pool port (for pool start/stop)
+  poolPort: ${poolPort},
+
+  // Directory containing JSON test files
+  testsDir: 'e2e/tests',
+
+  // Directory for reusable modules (referenced via $use in tests)
+  // modulesDir: 'e2e/modules',
+
+  // Directory for screenshots and reports
+  screenshotsDir: 'e2e/screenshots',
+
+  // Parallel test workers
+  concurrency: ${concurrency},
+
+  // Max concurrent pool sessions
+  maxSessions: ${maxSessions},
+
+  // Browser viewport
+  viewport: { width: 1280, height: 720 },
+
+  // Timeout per action (ms)
+  defaultTimeout: 10000,
+
+  // Per-test timeout (ms) — kills the test if it exceeds this
+  testTimeout: 60000,
+
+  // Retry failed tests N times (0 = no retries)
+  retries: 0,
+
+  // Delay between retries (ms)
+  retryDelay: 1000,
+
+  // Report output format: 'json', 'junit', or 'both'
+  outputFormat: '${outputFormat}',
+
+  // Global hooks — run actions before/after all tests or each test
+  // hooks: {
+  //   beforeAll: [{ type: 'goto', value: '/login' }],
+  //   afterAll: [],
+  //   beforeEach: [{ type: 'goto', value: '/' }],
+  //   afterEach: [],
+  // },
+
+  // Environment profiles — override any config key per environment
+  // Use with --env <name> or E2E_ENV=<name>
+  // environments: {
+  //   staging: { baseUrl: 'https://staging.example.com' },
+  //   production: { baseUrl: 'https://example.com', concurrency: 5 },
+  // },
+};
+`;
+}

package/templates/build-dashboard.js

@@ -24,6 +24,7 @@ const CSS_ORDER = [
   'view-tests.css',
   'view-runs.css',
   'view-live.css',
+  'view-tools.css',
 ];
 
 const JS_ORDER = [
@@ -36,6 +37,8 @@ const JS_ORDER = [
   'view-tests.js',
   'view-runs.js',
   'view-live.js',
+  'view-tools.js',
+  'quicksearch.js',
   'keyboard.js',
   'init.js',
 ];