@matware/e2e-runner 1.2.1 → 1.3.1

package/src/pool.js

@@ -1,7 +1,12 @@
 /**
  * Pool Management
  *
- * Connectivity to the Chrome Pool (browserless/chrome) and Docker Compose lifecycle.
+ * Connectivity to browser pools and Docker Compose lifecycle.
+ * Supports multiple pool drivers:
+ *   - "browserless" — browserless/chrome with /pressure and /sessions HTTP API
+ *   - "cdp"         — generic CDP pool (Lightpanda, raw Chrome, etc.) using /json/version health check
+ *   - "steel"       — Steel Browser with /v1/sessions REST API and session lifecycle
+ *   - "auto"        — detect driver by probing endpoints: /pressure → browserless, /v1/sessions → steel, fallback → cdp
  */
 
 import puppeteer from 'puppeteer-core';
@@ -18,22 +23,267 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-/** Waits for the Chrome Pool to become available */
-export async function waitForPool(poolUrl, maxWaitMs = 30000) {
-  const poolHttpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
-  const pressureUrl = `${poolHttpUrl}/pressure`;
+// ── Driver detection cache ────────────────────────────────────────────────────
+
+/** Caches detected driver per pool URL to avoid re-probing on every status call. */
+const driverCache = new Map();
+
+/** Clears the driver cache (useful for tests or pool restarts). */
+export function clearDriverCache() {
+  driverCache.clear();
+}
+
+/** Returns the cached driver for a pool URL, or null if not yet detected. */
+export function getCachedDriver(poolUrl) {
+  return driverCache.get(poolUrl) || null;
+}
+
+/**
+ * Detects the pool driver by probing HTTP endpoints.
+ * Probe order: /pressure (browserless) → /v1/sessions (steel) → fallback (cdp).
+ */
+async function detectPoolDriver(poolUrl) {
+  if (driverCache.has(poolUrl)) return driverCache.get(poolUrl);
+
+  const httpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
+
+  // Probe browserless
+  try {
+    const res = await fetch(`${httpUrl}/pressure`, { signal: AbortSignal.timeout(3000) });
+    if (res.ok) {
+      const data = await res.json();
+      if (data.pressure !== undefined) {
+        driverCache.set(poolUrl, 'browserless');
+        return 'browserless';
+      }
+    }
+  } catch { /* not browserless */ }
+
+  // Probe Steel
+  try {
+    const res = await fetch(`${httpUrl}/v1/sessions`, { signal: AbortSignal.timeout(3000) });
+    if (res.ok) {
+      const data = await res.json();
+      if (data.sessions !== undefined) {
+        driverCache.set(poolUrl, 'steel');
+        return 'steel';
+      }
+    }
+  } catch { /* not steel */ }
+
+  // Fallback: generic CDP
+  driverCache.set(poolUrl, 'cdp');
+  return 'cdp';
+}
+
+/**
+ * Resolves the effective driver string.
+ * Maps config values: 'auto' → detect, 'lightpanda' → 'cdp', explicit → pass through.
+ */
+async function resolveDriver(poolUrl, poolDriver) {
+  if (!poolDriver || poolDriver === 'auto') return detectPoolDriver(poolUrl);
+  if (poolDriver === 'lightpanda') return 'cdp';
+  return poolDriver;
+}
+
+// ── CDP driver: status via /json/version health check ─────────────────────────
+
+/**
+ * Local session tracker for CDP pools (no remote management API).
+ * Maps poolUrl → Set of session IDs currently in use.
+ */
+const cdpSessions = new Map();
+
+export function trackCdpSession(poolUrl, sessionId) {
+  if (!cdpSessions.has(poolUrl)) cdpSessions.set(poolUrl, new Set());
+  cdpSessions.get(poolUrl).add(sessionId);
+}
+
+export function releaseCdpSession(poolUrl, sessionId) {
+  const sessions = cdpSessions.get(poolUrl);
+  if (sessions) {
+    sessions.delete(sessionId);
+    if (sessions.size === 0) cdpSessions.delete(poolUrl);
+  }
+}
+
+function getCdpSessionCount(poolUrl) {
+  return cdpSessions.get(poolUrl)?.size || 0;
+}
+
+async function getPoolStatusViaCDP(poolUrl, maxSessions) {
+  const httpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
+  try {
+    const res = await fetch(`${httpUrl}/json/version`, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok) throw new Error(`/json/version returned ${res.status}`);
+
+    const running = getCdpSessionCount(poolUrl);
+    return {
+      available: running < maxSessions,
+      running,
+      maxConcurrent: maxSessions,
+      queued: 0,
+      sessions: [],
+      driver: 'cdp',
+    };
+  } catch (error) {
+    return {
+      available: false,
+      error: error.message,
+      running: 0,
+      maxConcurrent: maxSessions,
+      queued: 0,
+      sessions: [],
+      driver: 'cdp',
+    };
+  }
+}
+
+// ── Browserless driver: status via /pressure + /sessions ──────────────────────
+
+async function getPoolStatusViaBrowserless(poolUrl) {
+  const httpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
+  const [pressureRes, sessionsRes] = await Promise.all([
+    fetch(`${httpUrl}/pressure`),
+    fetch(`${httpUrl}/sessions`),
+  ]);
+
+  const pressure = pressureRes.ok ? await pressureRes.json() : null;
+  const sessions = sessionsRes.ok ? await sessionsRes.json() : null;
+
+  return {
+    available: pressure?.pressure?.isAvailable ?? false,
+    running: pressure?.pressure?.running ?? 0,
+    maxConcurrent: pressure?.pressure?.maxConcurrent ?? 0,
+    queued: pressure?.pressure?.queued ?? 0,
+    sessions: sessions || [],
+    driver: 'browserless',
+  };
+}
+
+// ── Steel driver: status via /v1/sessions REST API ────────────────────────────
+
+/**
+ * Tracks Steel session IDs created by this process so we can release them.
+ * Maps poolUrl → Map<browserId, steelSessionId>.
+ */
+const steelSessionMap = new Map();
+
+function trackSteelSession(poolUrl, browserId, steelSessionId) {
+  if (!steelSessionMap.has(poolUrl)) steelSessionMap.set(poolUrl, new Map());
+  steelSessionMap.get(poolUrl).set(browserId, steelSessionId);
+}
+
+function getSteelSessionId(poolUrl, browserId) {
+  return steelSessionMap.get(poolUrl)?.get(browserId) || null;
+}
+
+function removeSteelSession(poolUrl, browserId) {
+  const sessions = steelSessionMap.get(poolUrl);
+  if (sessions) {
+    sessions.delete(browserId);
+    if (sessions.size === 0) steelSessionMap.delete(poolUrl);
+  }
+}
+
+async function getPoolStatusViaSteel(poolUrl, maxSessions) {
+  const httpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
+  try {
+    const res = await fetch(`${httpUrl}/v1/sessions`, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok) throw new Error(`/v1/sessions returned ${res.status}`);
+    const data = await res.json();
+    const activeSessions = (data.sessions || []).filter(s => s.status === 'live' || s.status === 'idle');
+    return {
+      available: activeSessions.length < maxSessions,
+      running: activeSessions.length,
+      maxConcurrent: maxSessions,
+      queued: 0,
+      sessions: activeSessions.map(s => ({ id: s.id, status: s.status, duration: s.duration })),
+      driver: 'steel',
+    };
+  } catch (error) {
+    return {
+      available: false,
+      error: error.message,
+      running: 0,
+      maxConcurrent: maxSessions,
+      queued: 0,
+      sessions: [],
+      driver: 'steel',
+    };
+  }
+}
+
+/** Creates a Steel session and connects Puppeteer to it. */
+async function connectToSteelPool(poolUrl, retries = 3, delay = 2000) {
+  const httpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      // Create a new Steel session
+      const sessionRes = await fetch(`${httpUrl}/v1/sessions`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(15000),
+      });
+      if (!sessionRes.ok) throw new Error(`Steel session creation failed: ${sessionRes.status}`);
+      const session = await sessionRes.json();
+
+      // Rewrite the internal WS URL (0.0.0.0:3000) to match our host:port
+      const wsUrl = poolUrl.endsWith('/') ? poolUrl : poolUrl + '/';
+
+      const browser = await puppeteer.connect({
+        browserWSEndpoint: wsUrl,
+        timeout: 30000,
+      });
+
+      // Track session for cleanup
+      const browserId = browser.wsEndpoint();
+      trackSteelSession(poolUrl, browserId, session.id);
+
+      return browser;
+    } catch (error) {
+      if (attempt === retries) {
+        throw new Error(`Failed to connect to Steel pool: ${error.message}`);
+      }
+      log('🔄', `Attempt ${attempt}/${retries} failed, retrying...`);
+      await sleep(delay);
+    }
+  }
+}
+
+/**
+ * Releases a Steel session after browser disconnect.
+ * Call this in the finally block of test execution.
+ */
+export async function releaseSteelSession(poolUrl, browser) {
+  if (!browser) return;
+  const browserId = browser.wsEndpoint();
+  const sessionId = getSteelSessionId(poolUrl, browserId);
+  if (!sessionId) return;
+
+  const httpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
+  try {
+    await fetch(`${httpUrl}/v1/sessions/${sessionId}/release`, {
+      method: 'POST',
+      signal: AbortSignal.timeout(5000),
+    });
+  } catch { /* best effort */ }
+  removeSteelSession(poolUrl, browserId);
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/** Waits for the pool to become available */
+export async function waitForPool(poolUrl, maxWaitMs = 30000, options = {}) {
   const start = Date.now();
 
   while (Date.now() - start < maxWaitMs) {
     try {
-      const res = await fetch(pressureUrl);
-      if (res.ok) {
-        const data = await res.json();
-        if (data.pressure?.isAvailable) {
-          return data.pressure;
-        }
-        log('⏳', `Pool busy (${data.pressure.running}/${data.pressure.maxConcurrent}), waiting...`);
-      }
+      const status = await getPoolStatus(poolUrl, options);
+      if (status.available) return status;
+      log('⏳', `Pool busy (${status.running}/${status.maxConcurrent}), waiting...`);
     } catch {
       // Pool not ready
     }
@@ -42,8 +292,13 @@ export async function waitForPool(poolUrl, maxWaitMs = 30000) {
   throw new Error(`Chrome Pool unavailable after ${maxWaitMs / 1000}s. Verify the container is running.`);
 }
 
-/** Connects to the pool with retries */
+/** Connects to the pool with retries. For Steel pools, creates a session first. */
 export async function connectToPool(poolUrl, retries = 3, delay = 2000) {
+  const driver = getCachedDriver(poolUrl);
+  if (driver === 'steel') {
+    return connectToSteelPool(poolUrl, retries, delay);
+  }
+
   for (let attempt = 1; attempt <= retries; attempt++) {
     try {
       return await puppeteer.connect({
@@ -60,6 +315,19 @@ export async function connectToPool(poolUrl, retries = 3, delay = 2000) {
   }
 }
 
+/**
+ * Disconnects from a pool, releasing any driver-specific resources.
+ * For Steel pools, releases the session via REST API.
+ */
+export async function disconnectFromPool(browser, poolUrl) {
+  if (!browser) return;
+  const driver = getCachedDriver(poolUrl);
+  if (driver === 'steel') {
+    await releaseSteelSession(poolUrl, browser);
+  }
+  try { await browser.disconnect(); } catch { /* */ }
+}
+
 /** Generates docker-compose.yml and starts the pool */
 export function startPool(config, cwd = null) {
   cwd = cwd || process.cwd();
@@ -112,26 +380,27 @@ export function restartPool(config, cwd = null) {
   startPool(config, cwd);
 }
 
-/** Gets pool status */
-export async function getPoolStatus(poolUrl) {
-  const poolHttpUrl = poolUrl.replace('ws://', 'http://').replace('wss://', 'https://');
+/**
+ * Gets pool status using the appropriate driver.
+ * @param {string} poolUrl - WebSocket URL of the pool
+ * @param {object} [options] - { poolDriver: 'auto'|'browserless'|'lightpanda'|'cdp'|'steel', maxSessions: number }
+ */
+export async function getPoolStatus(poolUrl, options = {}) {
+  const { poolDriver = 'auto', maxSessions = 10 } = options;
 
-  try {
-    const [pressureRes, sessionsRes] = await Promise.all([
-      fetch(`${poolHttpUrl}/pressure`),
-      fetch(`${poolHttpUrl}/sessions`),
-    ]);
+  const driver = await resolveDriver(poolUrl, poolDriver);
 
-    const pressure = pressureRes.ok ? await pressureRes.json() : null;
-    const sessions = sessionsRes.ok ? await sessionsRes.json() : null;
+  if (driver === 'steel') {
+    return getPoolStatusViaSteel(poolUrl, maxSessions);
+  }
 
-    return {
-      available: pressure?.pressure?.isAvailable ?? false,
-      running: pressure?.pressure?.running ?? 0,
-      maxConcurrent: pressure?.pressure?.maxConcurrent ?? 0,
-      queued: pressure?.pressure?.queued ?? 0,
-      sessions: sessions || [],
-    };
+  if (driver === 'cdp') {
+    return getPoolStatusViaCDP(poolUrl, maxSessions);
+  }
+
+  // Browserless driver
+  try {
+    return await getPoolStatusViaBrowserless(poolUrl);
   } catch (error) {
     return {
       available: false,
@@ -140,6 +409,7 @@ export async function getPoolStatus(poolUrl) {
       maxConcurrent: 0,
       queued: 0,
       sessions: [],
+      driver: 'browserless',
     };
   }
 }

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,13 +152,16 @@ 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);
-    runDbId = saveRunToDb(projectId, report, runId, suiteName || null, config.triggeredBy || null);
+    // Derive actual pool driver from test results (resolves 'auto' to real driver)
+    const drivers = [...new Set((report.results || []).map(r => r.poolDriver).filter(Boolean))];
+    const resolvedDriver = drivers.length === 1 ? drivers[0] : drivers.length > 1 ? drivers.join(',') : config.poolDriver || null;
+    runDbId = saveRunToDb(projectId, report, runId, suiteName || null, config.triggeredBy || null, resolvedDriver);
 
     // Fire-and-forget: learn from this run (never blocks or crashes the runner)
     if (config.learningsEnabled !== false) {
@@ -175,6 +180,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 +276,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
+  }
+}