@matware/e2e-runner 1.2.1 → 1.3.1

package/src/module-resolver.js

@@ -13,6 +13,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import { KNOWN_ACTION_TYPES } from './actions.js';
 
 /**
  * Loads all module definitions from a directory.
@@ -271,3 +272,39 @@ export function listModules(modulesDir) {
 
   return modules;
 }
+
+/**
+ * Validates that all action types in a resolved test data structure are known.
+ * Call AFTER module resolution so $use references have been expanded.
+ * @param {object} data - { tests, hooks } with resolved actions
+ * @param {string} context - File/suite name for error messages
+ * @throws {Error} if any unknown action types are found
+ */
+export function validateActionTypes(data, context) {
+  const unknown = [];
+
+  const check = (actions, location) => {
+    if (!Array.isArray(actions)) return;
+    for (const action of actions) {
+      if (action.$use) continue; // unresolved module ref — skip (shouldn't happen post-resolution)
+      if (action.type && !KNOWN_ACTION_TYPES.has(action.type)) {
+        unknown.push({ type: action.type, location });
+      }
+    }
+  };
+
+  // Check hooks
+  for (const [hookName, actions] of Object.entries(data.hooks || {})) {
+    check(actions, `hooks.${hookName}`);
+  }
+
+  // Check test actions
+  for (const test of data.tests || []) {
+    check(test.actions, `test "${test.name}"`);
+  }
+
+  if (unknown.length > 0) {
+    const details = unknown.map(u => `"${u.type}" in ${u.location}`).join(', ');
+    throw new Error(`Unknown action type(s) in ${context}: ${details}`);
+  }
+}

package/src/narrate.js

@@ -129,6 +129,33 @@ export function narrateAction(action, result) {
     case 'click_chip':
       return `Clicked chip "${text}"${time}`;
 
+    case 'set_storage': {
+      const storageType = selector === 'session' ? 'sessionStorage' : 'localStorage';
+      const eqIdx = value.indexOf('=');
+      const sKey = eqIdx === -1 ? value : value.slice(0, eqIdx);
+      const sVal = eqIdx === -1 ? '' : value.slice(eqIdx + 1);
+      const displayVal = isSensitive(sKey) ? '***' : (sVal.length > 30 ? sVal.slice(0, 27) + '...' : sVal);
+      return `Set ${storageType}.${sKey} = "${displayVal}"${time}`;
+    }
+
+    case 'assert_storage': {
+      const storageType = selector === 'session' ? 'sessionStorage' : 'localStorage';
+      const eqIdx = value.indexOf('=');
+      if (eqIdx === -1) {
+        return `Verified ${storageType} key "${value}" exists${time}`;
+      }
+      return `Verified ${storageType} key "${value.slice(0, eqIdx)}" has expected value${time}`;
+    }
+
+    case 'click_icon':
+      return `Clicked icon "${value}"${selector ? ` in "${selector}"` : ''}${time}`;
+
+    case 'click_menu_item':
+      return `Clicked menu item "${text}"${selector ? ` in "${selector}"` : ''}${time}`;
+
+    case 'click_in_context':
+      return `Clicked "${selector}" in container with text "${text}"${time}`;
+
     case 'evaluate': {
       const snippet = value.length > 80 ? value.slice(0, 77) + '...' : value;
       const evalResult = result.result?.value;
@@ -140,6 +167,28 @@ export function narrateAction(action, result) {
       return `Executed JS: ${snippet}${time}`;
     }
 
+    case 'assert_visual': {
+      const vr = result.result;
+      if (vr?.goldenCreated) return `Saved golden reference: ${value}${time}`;
+      const pct = vr?.diffPercentage != null ? (vr.diffPercentage * 100).toFixed(2) + '% diff' : '';
+      return `Visual comparison against "${value}": ${pct}${time}`;
+    }
+
+    case 'open_tab':
+      return `Opened new tab${text ? ` "${text}"` : ''} → ${value}${time}`;
+
+    case 'switch_tab':
+      return `Switched to tab "${value}"${time}`;
+
+    case 'close_tab':
+      return `Closed tab${value ? ` "${value}"` : ''}${time}`;
+
+    case 'assert_tab_count':
+      return `Verified ${value} tab(s) open${time}`;
+
+    case 'wait_for_tab':
+      return `Waited for new tab to open${text ? ` (labeled "${text}")` : ''}${time}`;
+
     default:
       return `Unknown action "${type}"${time}`;
   }
@@ -185,7 +234,23 @@ function describeIntent(action) {
     case 'click_option':          return `Click option "${text}"`;
     case 'focus_autocomplete':    return `Focus autocomplete "${text}"`;
     case 'click_chip':            return `Click chip "${text}"`;
+    case 'set_storage':            return `Set ${selector === 'session' ? 'sessionStorage' : 'localStorage'} key "${value?.split('=')[0] || value}"`;
+    case 'assert_storage': {
+      const eqIdx = value?.indexOf('=') ?? -1;
+      return eqIdx === -1
+        ? `Assert ${selector === 'session' ? 'sessionStorage' : 'localStorage'} key "${value}" exists`
+        : `Assert ${selector === 'session' ? 'sessionStorage' : 'localStorage'} key "${value.slice(0, eqIdx)}" value`;
+    }
+    case 'click_icon':             return `Click icon "${value}"`;
+    case 'click_menu_item':        return `Click menu item "${text}"`;
+    case 'click_in_context':       return `Click "${selector}" in context of "${text}"`;
     case 'evaluate':   return 'Execute JS';
+    case 'assert_visual':           return `Visual compare against "${value}"`;
+    case 'open_tab':               return `Open new tab → ${value}`;
+    case 'switch_tab':             return `Switch to tab "${value}"`;
+    case 'close_tab':              return `Close tab${value ? ` "${value}"` : ''}`;
+    case 'assert_tab_count':       return `Assert ${value} tab(s) open`;
+    case 'wait_for_tab':           return 'Wait for new tab';
     default:           return `Action "${type}"`;
   }
 }

package/src/pool-manager.js

@@ -0,0 +1,229 @@
+/**
+ * Pool Manager — multi-pool selection and distribution.
+ *
+ * Abstracts pool selection behind a least-pressure strategy.
+ * When multiple pools are configured, tests are distributed across
+ * all available Chrome capacity. Single-pool setups work identically.
+ *
+ * Uses a local pending counter to avoid "thundering herd" — when many
+ * workers call selectPool() simultaneously, the remote /pressure endpoint
+ * hasn't updated yet. The pending map tracks selections locally so
+ * subsequent calls factor in connections that are in-flight.
+ */
+
+import { getPoolStatus, connectToPool } from './pool.js';
+import { log, colors as C } from './logger.js';
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Local pending counter — tracks connections selected but not yet
+ * reflected in the pool's /pressure endpoint. Prevents all workers
+ * from picking the same pool when they query simultaneously.
+ */
+const pendingConnections = new Map();
+
+export function trackPending(poolUrl) {
+  pendingConnections.set(poolUrl, (pendingConnections.get(poolUrl) || 0) + 1);
+}
+
+export function releasePending(poolUrl) {
+  const current = pendingConnections.get(poolUrl) || 0;
+  if (current > 1) {
+    pendingConnections.set(poolUrl, current - 1);
+  } else {
+    pendingConnections.delete(poolUrl);
+  }
+}
+
+function getPending(poolUrl) {
+  return pendingConnections.get(poolUrl) || 0;
+}
+
+/** Extracts pool driver options from config for passing to getPoolStatus. */
+function driverOpts(config) {
+  if (!config) return {};
+  return { poolDriver: config.poolDriver || 'auto', maxSessions: config.maxSessions || 10 };
+}
+
+/** Returns the normalized pool URL array from config. Always an array, even for single pool. */
+export function getPoolUrls(config) {
+  return config._poolUrls || [config.poolUrl];
+}
+
+/** Fetches status from all pools in parallel. Returns [{ url, status, error }]. */
+export async function getAllPoolStatuses(poolUrls, options = {}) {
+  return Promise.all(poolUrls.map(async (url) => {
+    try {
+      const status = await getPoolStatus(url, options);
+      return { url, status, error: null };
+    } catch (error) {
+      return { url, status: null, error: error.message };
+    }
+  }));
+}
+
+/** Combined view across all pools: totalRunning, totalMaxConcurrent, per-pool details. */
+export async function getAggregatedPoolStatus(poolUrls, options = {}) {
+  const results = await getAllPoolStatuses(poolUrls, options);
+
+  let totalRunning = 0;
+  let totalMaxConcurrent = 0;
+  let totalQueued = 0;
+  let availableCount = 0;
+
+  const pools = results.map(({ url, status, error }) => {
+    if (error || !status) {
+      return { url, available: false, error: error || 'unreachable', running: 0, maxConcurrent: 0, queued: 0, sessions: [] };
+    }
+    totalRunning += status.running;
+    totalMaxConcurrent += status.maxConcurrent;
+    totalQueued += status.queued;
+    if (status.available) availableCount++;
+    return { url, ...status };
+  });
+
+  return {
+    totalRunning,
+    totalMaxConcurrent,
+    totalQueued,
+    availableCount,
+    totalPools: poolUrls.length,
+    pools,
+  };
+}
+
+/** Blocks until at least one pool is reachable and available. */
+export async function waitForAnyPool(poolUrls, maxWaitMs = 30000, options = {}) {
+  const start = Date.now();
+
+  while (Date.now() - start < maxWaitMs) {
+    const results = await getAllPoolStatuses(poolUrls, options);
+    const available = results.find(r => r.status?.available);
+    if (available) return available.status;
+
+    const reachable = results.filter(r => r.status && !r.error);
+    if (reachable.length > 0) {
+      log('⏳', `${C.dim}Pool(s) busy (${reachable.length}/${poolUrls.length} reachable), waiting...${C.reset}`);
+    } else {
+      log('⏳', `${C.dim}No pools reachable yet (0/${poolUrls.length}), waiting...${C.reset}`);
+    }
+
+    await sleep(2000);
+  }
+
+  throw new Error(`No Chrome Pool available after ${maxWaitMs / 1000}s. Verify containers are running.`);
+}
+
+/**
+ * Picks the pool with the lowest pressure ratio.
+ *
+ * Algorithm:
+ * 1. Query all pools' status in parallel (driver-aware)
+ * 2. Add local pending count to each pool's running total
+ * 3. Filter to reachable pools with (running + pending) < maxConcurrent
+ * 4. Sort by: lowest effective pressure → fewest queued → most free slots
+ * 5. Track selection in pending counter, return best candidate URL
+ * 6. If all full, poll every 2s up to 60s, then pick least-pressured anyway
+ */
+export async function selectPool(poolUrls, pollIntervalMs = 2000, maxWaitMs = 60000, options = {}) {
+  // Fast path: single pool
+  if (poolUrls.length === 1) {
+    await waitForSlotOnPool(poolUrls[0], pollIntervalMs, maxWaitMs, options);
+    trackPending(poolUrls[0]);
+    return poolUrls[0];
+  }
+
+  const start = Date.now();
+
+  while (Date.now() - start < maxWaitMs) {
+    const results = await getAllPoolStatuses(poolUrls, options);
+    const candidates = results
+      .filter(r => r.status && !r.error && r.status.available)
+      .map(r => {
+        const pending = getPending(r.url);
+        const effectiveRunning = r.status.running + pending;
+        return {
+          url: r.url,
+          running: r.status.running,
+          pending,
+          effectiveRunning,
+          maxConcurrent: r.status.maxConcurrent,
+          queued: r.status.queued,
+          pressure: r.status.maxConcurrent > 0 ? effectiveRunning / r.status.maxConcurrent : 1,
+          freeSlots: r.status.maxConcurrent - effectiveRunning,
+        };
+      })
+      .filter(c => c.effectiveRunning < c.maxConcurrent);
+
+    if (candidates.length > 0) {
+      candidates.sort((a, b) => {
+        if (a.pressure !== b.pressure) return a.pressure - b.pressure;
+        if (a.queued !== b.queued) return a.queued - b.queued;
+        return b.freeSlots - a.freeSlots;
+      });
+      const chosen = candidates[0].url;
+      trackPending(chosen);
+      return chosen;
+    }
+
+    // All full — check if any are reachable
+    const reachable = results.filter(r => r.status && !r.error);
+    if (reachable.length > 0) {
+      log('⏳', `${C.dim}All pools at capacity (${reachable.length}/${poolUrls.length} reachable), waiting for slot...${C.reset}`);
+    }
+
+    await sleep(pollIntervalMs);
+  }
+
+  // Timeout — pick the least-pressured pool anyway (let connectToPool deal with it)
+  const results = await getAllPoolStatuses(poolUrls, options);
+  const reachable = results
+    .filter(r => r.status && !r.error)
+    .sort((a, b) => {
+      const pendA = getPending(a.url);
+      const pendB = getPending(b.url);
+      const pA = a.status.maxConcurrent > 0 ? (a.status.running + pendA) / a.status.maxConcurrent : 1;
+      const pB = b.status.maxConcurrent > 0 ? (b.status.running + pendB) / b.status.maxConcurrent : 1;
+      return pA - pB;
+    });
+
+  if (reachable.length > 0) {
+    log('⚠️', `${C.yellow}Waited ${maxWaitMs / 1000}s for pool slot, proceeding with least-pressured pool${C.reset}`);
+    const chosen = reachable[0].url;
+    trackPending(chosen);
+    return chosen;
+  }
+
+  // All unreachable — return first and let connectToPool error
+  return poolUrls[0];
+}
+
+/** Convenience: selectPool + connectToPool in one call. */
+export async function selectAndConnect(config) {
+  const poolUrls = getPoolUrls(config);
+  const chosenUrl = await selectPool(poolUrls, 2000, 60000, driverOpts(config));
+  return connectToPool(chosenUrl, config.connectRetries, config.connectRetryDelay);
+}
+
+/** Waits until a single pool has capacity. */
+async function waitForSlotOnPool(poolUrl, pollIntervalMs = 2000, maxWaitMs = 60000, options = {}) {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    try {
+      const status = await getPoolStatus(poolUrl, options);
+      if (status.available && status.running < status.maxConcurrent) {
+        return;
+      }
+      log('⏳', `${C.dim}Pool at capacity (${status.running}/${status.maxConcurrent}, ${status.queued} queued), waiting for slot...${C.reset}`);
+    } catch {
+      // Pool unreachable, let connectToPool handle the error
+      return;
+    }
+    await sleep(pollIntervalMs);
+  }
+  // Timeout — proceed anyway and let connectToPool deal with it
+  log('⚠️', `${C.yellow}Waited ${maxWaitMs / 1000}s for pool slot, proceeding anyway${C.reset}`);
+}