@matware/e2e-runner 1.2.1 → 1.3.0

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;
@@ -185,6 +212,16 @@ 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';
     default:           return `Action "${type}"`;
   }

package/src/pool-manager.js

@@ -0,0 +1,223 @@
+/**
+ * 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;
+}
+
+/** 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 /pressure from all pools in parallel. Returns [{ url, status, error }]. */
+export async function getAllPoolStatuses(poolUrls) {
+  return Promise.all(poolUrls.map(async (url) => {
+    try {
+      const status = await getPoolStatus(url);
+      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) {
+  const results = await getAllPoolStatuses(poolUrls);
+
+  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) {
+  const start = Date.now();
+
+  while (Date.now() - start < maxWaitMs) {
+    const results = await getAllPoolStatuses(poolUrls);
+    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' /pressure in parallel
+ * 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) {
+  // Fast path: single pool
+  if (poolUrls.length === 1) {
+    await waitForSlotOnPool(poolUrls[0], pollIntervalMs, maxWaitMs);
+    trackPending(poolUrls[0]);
+    return poolUrls[0];
+  }
+
+  const start = Date.now();
+
+  while (Date.now() - start < maxWaitMs) {
+    const results = await getAllPoolStatuses(poolUrls);
+    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);
+  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);
+  return connectToPool(chosenUrl, config.connectRetries, config.connectRetryDelay);
+}
+
+/** Waits until a single pool has capacity (replaces the old waitForSlot from runner.js). */
+async function waitForSlotOnPool(poolUrl, pollIntervalMs = 2000, maxWaitMs = 60000) {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    try {
+      const status = await getPoolStatus(poolUrl);
+      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}`);
+}

package/src/reporter.js

@@ -9,6 +9,8 @@ import { ensureProject, saveRun as saveRunToDb } from './db.js';
 import { narrateTest } from './narrate.js';
 import { learnFromRun } from './learner.js';
 import { generateLearningsMarkdown } from './learner-markdown.js';
+import { getHealthSnapshot, getRunInsights } from './learner-sqlite.js';
+import { pushRun as syncPushRun } from './sync/client.js';
 
 function escapeXml(str) {
   return String(str)
@@ -150,7 +152,7 @@ export function loadHistoryRun(screenshotsDir, runId) {
 }
 
 /** Persists a run to both filesystem history and SQLite (never throws). */
-export function persistRun(report, config, suiteName) {
+export async function persistRun(report, config, suiteName) {
   const runId = saveHistory(report, config.screenshotsDir, config.maxHistoryRuns);
   let runDbId = null;
 
@@ -175,6 +177,17 @@ export function persistRun(report, config, suiteName) {
         }
       }
     }
+    
+    // Sync push if in agent mode with autoSync enabled
+    if (config.sync?.mode === 'agent' && config.sync?.agent?.autoSync !== false) {
+      try {
+        const project = { name: config.projectName, slug: config.projectName.toLowerCase().replace(/[^a-z0-9]+/g, '-') };
+        const enrichedReport = { ...report, runId, suiteName, triggeredBy: config.triggeredBy };
+        await syncPushRun(config, project, enrichedReport);
+      } catch (syncErr) {
+        process.stderr.write(`[e2e-runner] Sync push failed: ${syncErr.message}\n`);
+      }
+    }
   } catch (err) {
     process.stderr.write(`[e2e-runner] SQLite write failed: ${err.message}\n`);
   }
@@ -260,3 +273,71 @@ export function printReport(report, screenshotsDir) {
     console.log(`${C.dim}Screenshots: ${screenshotsDir}${C.reset}\n`);
   }
 }
+
+/** Prints a compact learnings/health block after the run report. Never throws. */
+export function printInsights(report, config) {
+  try {
+    if (config.learningsEnabled === false) return;
+
+    const projectId = ensureProject(config._cwd, config.projectName, config.screenshotsDir, config.testsDir);
+    const health = getHealthSnapshot(projectId);
+    const insights = getRunInsights(projectId, report);
+
+    // Nothing to show if no historical data and no insights
+    if (!health && insights.length === 0) return;
+
+    const lines = [];
+    const LINE = `${C.dim}${'─'.repeat(42)}${C.reset}`;
+
+    // Run-specific insights
+    const newFailures = insights.filter(i => i.type === 'new-failure');
+    const flaky = insights.filter(i => i.type === 'flaky');
+    const recovered = insights.filter(i => i.type === 'recovered');
+    const unstable = insights.find(i => i.type === 'unstable-selectors');
+
+    if (newFailures.length > 0) {
+      lines.push(`  ${C.red}!${C.reset}  ${newFailures.length} new failure(s) (previously stable)`);
+      for (const f of newFailures.slice(0, 3)) {
+        lines.push(`     ${C.dim}- ${f.test}${C.reset}`);
+      }
+      if (newFailures.length > 3) lines.push(`     ${C.dim}... and ${newFailures.length - 3} more${C.reset}`);
+    }
+    if (recovered.length > 0) {
+      lines.push(`  ${C.green}+${C.reset}  ${recovered.length} recovered test(s)`);
+    }
+    if (flaky.length > 0) {
+      lines.push(`  ${C.yellow}~${C.reset}  ${flaky.length} known flaky test(s) passed this time`);
+    }
+    if (unstable) {
+      const sels = unstable.selectors.slice(0, 3).join(', ');
+      lines.push(`  ${C.red}!${C.reset}  ${unstable.selectors.length} unstable selector(s): ${C.dim}${sels}${C.reset}`);
+    }
+
+    // Health snapshot
+    if (health) {
+      const rateColor = health.passRate >= 90 ? C.green : health.passRate >= 70 ? C.yellow : C.red;
+      const trendIcon = health.passRateTrend === 'improving' ? `${C.green}^${C.reset}` : health.passRateTrend === 'declining' ? `${C.red}v${C.reset}` : `${C.dim}=${C.reset}`;
+      const deltaStr = health.trendDelta !== 0 ? `, ${health.trendDelta > 0 ? '+' : ''}${health.trendDelta}%` : '';
+      lines.push(`  ${trendIcon}  Pass rate: ${rateColor}${health.passRate}%${C.reset} (${health.passRateTrend}${deltaStr})`);
+
+      if (health.topErrorPattern) {
+        const cat = health.topErrorPattern.category || health.topErrorPattern.pattern || 'unknown';
+        const label = cat.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+        lines.push(`  ${C.dim}!${C.reset}  Top error: ${C.dim}${label} (${health.topErrorPattern.count}x)${C.reset}`);
+      }
+    }
+
+    if (lines.length === 0) return;
+
+    console.log('');
+    console.log(`${C.dim}── ${C.reset}${C.bold}Learnings${C.reset} ${LINE}`);
+    for (const line of lines) console.log(line);
+    console.log(`  ${C.dim}Run 'e2e-runner learnings' for full details${C.reset}`);
+    if (config.learningsMarkdown !== false) {
+      console.log(`  ${C.dim}Updated: e2e/learnings.md${C.reset}`);
+    }
+    console.log(LINE);
+  } catch {
+    // Never fail the run
+  }
+}