@matware/e2e-runner 1.1.1 → 1.3.0

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

@@ -6,6 +6,11 @@ import fs from 'fs';
 import path from 'path';
 import { colors as C } from './logger.js';
 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)
@@ -147,17 +152,47 @@ 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;
 
   try {
     const projectId = ensureProject(config._cwd, config.projectName, config.screenshotsDir, config.testsDir);
-    saveRunToDb(projectId, report, runId, suiteName || null, config.triggeredBy || null);
+    runDbId = saveRunToDb(projectId, report, runId, suiteName || null, config.triggeredBy || null);
+
+    // Fire-and-forget: learn from this run (never blocks or crashes the runner)
+    if (config.learningsEnabled !== false) {
+      try {
+        learnFromRun(projectId, runDbId, report, config, suiteName);
+      } catch (learnErr) {
+        process.stderr.write(`[e2e-runner] Learning write failed: ${learnErr.message}\n`);
+      }
+
+      // Generate learnings markdown if enabled
+      if (config.learningsMarkdown !== false) {
+        try {
+          generateLearningsMarkdown(projectId, config);
+        } catch (mdErr) {
+          process.stderr.write(`[e2e-runner] Learnings markdown failed: ${mdErr.message}\n`);
+        }
+      }
+    }
+    
+    // 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`);
   }
 
-  return runId;
+  return { runId, runDbId };
 }
 
 /** Prints a formatted report summary to the console */
@@ -222,8 +257,87 @@ export function printReport(report, screenshotsDir) {
     });
   }
 
+  // Print step-by-step narrative for each test
+  console.log(`\n${C.bold}NARRATIVE:${C.reset}`);
+  for (const result of report.results) {
+    const icon = result.success ? `${C.green}✓${C.reset}` : `${C.red}✗${C.reset}`;
+    console.log(`  ${icon} ${C.bold}${result.name}${C.reset}`);
+    const steps = narrateTest(result);
+    for (const step of steps) {
+      console.log(`    ${C.dim}${step}${C.reset}`);
+    }
+  }
+
   if (screenshotsDir) {
     console.log(`\n${C.dim}Report: ${path.join(screenshotsDir, 'report.json')}${C.reset}`);
     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
+  }
+}