@matware/e2e-runner 1.3.1 → 1.5.1

package/src/actions.js

@@ -9,7 +9,59 @@
 
 import path from 'path';
 import fs from 'fs';
-import { assertVisualMatch } from './visual-diff.js';
+import { assertVisualMatch, isBlankImage } from './visual-diff.js';
+
+/**
+ * Returns false when the page has nothing useful to capture — used to
+ * skip screenshots that would otherwise be saved as pure-color PNGs
+ * (about:blank, fresh tab before navigation, DOM-only drivers that
+ * never paint, etc). Fails open: on any evaluation error we assume
+ * there *is* content so we don't lose legitimate captures.
+ */
+export async function pageHasRenderableContent(page) {
+  try {
+    const url = page.url();
+    if (!url || url === 'about:blank' || url === 'about:srcdoc') return false;
+    return await page
+      .evaluate(() => {
+        if (!document.body) return false;
+        if (document.body.children.length > 0) return true;
+        return (document.body.innerText || '').trim().length > 0;
+      })
+      .catch(() => true);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Heuristic post-capture guard: PNGs compressed under this size at
+ * typical viewport resolutions are almost certainly near-uniform color
+ * (about:blank, default Chrome BG, broken render). Catches cases the
+ * pre-capture DOM check can't — e.g. browserless rendering example.com
+ * to a 99%-gray frame even though navigation succeeded.
+ *
+ * 20 KB sits cleanly between the observed blank cluster (5 KB – 18 KB)
+ * and the smallest real captures in this project (~23 KB+).
+ */
+export const BLANK_PNG_BYTE_THRESHOLD = 20000;
+export const BLANK_JPEG_BYTE_THRESHOLD = 8000;
+
+export function looksLikeBlankCapture(buf, format = 'png') {
+  if (!Buffer.isBuffer(buf)) return false;
+  const threshold = format === 'jpeg' ? BLANK_JPEG_BYTE_THRESHOLD : BLANK_PNG_BYTE_THRESHOLD;
+  if (buf.length < threshold) return true;
+  // Byte size alone misses larger near-uniform frames (e.g. a white page
+  // whose PNG still compresses above 20 KB). For PNGs we can decode and
+  // check pixel uniformity directly — ≥98% of sampled pixels within
+  // tolerance of the mean color means there is nothing worth keeping.
+  // JPEGs (step captures) can't be decoded without deps, so they keep
+  // the byte heuristic only. Fails open on decode errors.
+  if (format === 'png') {
+    return isBlankImage(buf, { tolerance: 12, maxOutlierFraction: 0.02 }).blank;
+  }
+  return false;
+}
 
 /** All recognized action types — single source of truth for validation. */
 export const KNOWN_ACTION_TYPES = new Set([
@@ -20,7 +72,7 @@ export const KNOWN_ACTION_TYPES = new Set([
   'assert_no_network_errors', 'assert_storage',
   'get_text', 'select', 'clear', 'clear_cookies', 'press', 'scroll', 'hover',
   'navigate', 'evaluate',
-  'type_react', 'click_regex', 'click_option', 'focus_autocomplete', 'click_chip',
+  'type_react', 'click_regex', 'click_option', 'select_combobox', 'focus_autocomplete', 'click_chip',
   'set_storage', 'click_icon', 'click_menu_item', 'click_in_context',
   'assert_text_in', 'assert_no_text',
   'gql', 'wait_network_idle',
@@ -50,16 +102,35 @@ export async function executeAction(page, action, config) {
         await page.click(selector);
       } else if (text) {
         const clickTextSelector = 'button, a, [role="button"], [role="tab"], [role="menuitem"], [role="option"], [role="listitem"], div[class*="cursor"], span, li, td, th, label, p, h1, h2, h3, h4, h5, h6, dd, dt';
+        // Optional refinements (backward-compatible — defaults match old behavior):
+        //   scope: "dialog" → only match inside an open [role=dialog]/MuiDialog
+        //   visible: true   → skip hidden/zero-size matches (implied by scope:dialog)
+        //   last: true      → click the LAST match instead of the first
+        const scopeSel = action.scope === 'dialog' ? '[role="dialog"], .MuiDialog-root' : null;
+        const wantVisible = action.visible === true || action.scope === 'dialog';
+        const wantLast = action.last === true;
         await page.waitForFunction(
-          (t, sel) => [...document.querySelectorAll(sel)]
-            .find(el => el.textContent.includes(t)),
+          (t, sel, scope, vis) => {
+            const roots = scope ? [...document.querySelectorAll(scope)] : [document];
+            const isVis = el => { if (!vis) return true; const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.display !== 'none' && s.visibility !== 'hidden'; };
+            for (const root of roots) {
+              if ([...root.querySelectorAll(sel)].some(el => el.textContent.includes(t) && isVis(el))) return true;
+            }
+            return false;
+          },
           { timeout },
-          text, clickTextSelector
+          text, clickTextSelector, scopeSel, wantVisible
         );
-        await page.$$eval(clickTextSelector, (els, t) => {
-          const el = els.find(e => e.textContent.includes(t));
-          if (el) el.click();
-        }, text);
+        const clicked = await page.evaluate((t, sel, scope, vis, last) => {
+          const roots = scope ? [...document.querySelectorAll(scope)] : [document];
+          const isVis = el => { if (!vis) return true; const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.display !== 'none' && s.visibility !== 'hidden'; };
+          const matches = [];
+          for (const root of roots) matches.push(...[...root.querySelectorAll(sel)].filter(el => el.textContent.includes(t) && isVis(el)));
+          const el = last ? matches[matches.length - 1] : matches[0];
+          if (el) { el.click(); return true; }
+          return false;
+        }, text, clickTextSelector, scopeSel, wantVisible, wantLast);
+        if (!clicked) throw new Error(`click failed: no element containing "${text}"${scopeSel ? ' in an open dialog' : ''} found`);
       }
       break;
 
@@ -71,8 +142,34 @@ export async function executeAction(page, action, config) {
       await page.type(selector, value, { delay: 20 });
       break;
 
-    case 'wait':
-      if (selector) {
+    case 'wait': {
+      // Condition waits (preferred over fixed sleeps):
+      //   { selector }            → wait until it appears
+      //   { text }                → wait until text appears in the page
+      //   { gone: "<css>" }       → wait until that selector disappears/hides (e.g. spinner)
+      //   { gone: true, selector }→ same, selector form
+      //   { gone: true, text }    → wait until text disappears
+      //   { value: "<ms>" }       → fixed sleep (last resort)
+      const goneSel = typeof action.gone === 'string' ? action.gone : (action.gone === true ? selector : null);
+      const goneTxt = action.gone === true && !selector ? text : null;
+      if (goneSel) {
+        try {
+          await page.waitForFunction((sel) => {
+            const el = document.querySelector(sel);
+            if (!el) return true;
+            const r = el.getBoundingClientRect(); const s = getComputedStyle(el);
+            return (r.width === 0 && r.height === 0) || s.display === 'none' || s.visibility === 'hidden' || s.opacity === '0';
+          }, { timeout }, goneSel);
+        } catch (e) {
+          throw new Error(`wait failed: "${goneSel}" still present/visible after ${timeout}ms`);
+        }
+      } else if (goneTxt) {
+        try {
+          await page.waitForFunction((t) => !document.body.innerText.includes(t), { timeout }, goneTxt);
+        } catch (e) {
+          throw new Error(`wait failed: text "${goneTxt}" still present after ${timeout}ms`);
+        }
+      } else if (selector) {
         try {
           await page.waitForSelector(selector, { timeout });
         } catch (e) {
@@ -92,6 +189,7 @@ export async function executeAction(page, action, config) {
         await sleep(parseInt(value));
       }
       break;
+    }
 
     case 'screenshot': {
       let filename = value || `screenshot-${Date.now()}.png`;
@@ -108,7 +206,20 @@ export async function executeAction(page, action, config) {
         filename = `${base}-${Date.now()}${ext}`;
       }
       const filepath = path.join(screenshotsDir, filename);
-      await page.screenshot({ path: filepath, fullPage: action.fullPage || false });
+      // Skip capture when page is at about:blank or DOM is empty — these
+      // produce uniform-color PNGs that pollute screenshotsDir with no
+      // diagnostic value.
+      if (!(await pageHasRenderableContent(page))) {
+        return { screenshot: null, skipped: 'blank-page' };
+      }
+      // Capture to buffer first so we can post-filter near-uniform frames
+      // (e.g. browserless returning a 99%-gray render). Only persist if
+      // the encoded PNG carries enough entropy to be informative.
+      const ssBuf = await page.screenshot({ fullPage: action.fullPage || false });
+      if (looksLikeBlankCapture(ssBuf, 'png')) {
+        return { screenshot: null, skipped: 'blank-render', bytes: ssBuf.length };
+      }
+      fs.writeFileSync(filepath, ssBuf);
       return { screenshot: filepath };
     }
 
@@ -356,8 +467,11 @@ export async function executeAction(page, action, config) {
     case 'type_react': {
       // Types into React controlled inputs using the native value setter.
       // This bypasses React's synthetic event system which ignores programmatic .value changes.
+      // Optional: blur (commit on blur for fields that validate then),
+      //           waitAfter (ms to wait after — e.g. for debounced autocomplete dropdowns).
       await page.waitForSelector(selector, { timeout });
-      await page.evaluate((sel, val) => {
+      const trBlur = action.blur === true;
+      await page.evaluate((sel, val, doBlur) => {
         const input = document.querySelector(sel);
         if (!input) throw new Error(`type_react: element "${sel}" not found`);
         const proto = input instanceof HTMLTextAreaElement
@@ -367,11 +481,13 @@ export async function executeAction(page, action, config) {
         if (!descriptor || !descriptor.set) {
           throw new Error(`type_react: element "${sel}" has no writable value property`);
         }
+        input.focus();
         descriptor.set.call(input, val);
         input.dispatchEvent(new Event('input', { bubbles: true }));
         input.dispatchEvent(new Event('change', { bubbles: true }));
-        input.focus();
-      }, selector, value);
+        if (doBlur) input.blur();
+      }, selector, value, trBlur);
+      if (action.waitAfter) await sleep(parseInt(action.waitAfter));
       break;
     }
 
@@ -418,6 +534,56 @@ export async function executeAction(page, action, config) {
       break;
     }
 
+    case 'select_combobox': {
+      // Open a MUI Autocomplete / Select, optionally type to filter, then click the
+      // option matching `text` (case-insensitive substring). Falls back across
+      // [role=option], MuiAutocomplete-option and MuiMenuItem so it works for both
+      // Autocomplete listboxes and Select dropdowns.
+      //   selector: combobox input (default input[role='combobox'])
+      //   text:     option to pick (required)
+      //   filter:   text typed into the input before picking (optional)
+      //   openWait/filterWait: ms tuning for async/debounced option loaders
+      const cbInput = selector || "input[role='combobox']";
+      const cbOption = text || action.option;
+      if (!cbOption) throw new Error("select_combobox requires 'text' (option to pick)");
+      const cbFilter = action.filter || '';
+      const cbOpenWait = action.openWait ? parseInt(action.openWait) : 400;
+      const cbFilterWait = action.filterWait ? parseInt(action.filterWait) : 600;
+      await page.waitForSelector(cbInput, { timeout });
+      await page.evaluate((sel, flt) => {
+        const input = document.querySelector(sel);
+        if (!input) throw new Error(`select_combobox: input "${sel}" not found`);
+        input.focus();
+        if (typeof input.click === 'function') input.click();
+        if (flt) {
+          const proto = input instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+          const setter = Object.getOwnPropertyDescriptor(proto, 'value').set;
+          setter.call(input, flt);
+          input.dispatchEvent(new Event('input', { bubbles: true }));
+          input.dispatchEvent(new Event('change', { bubbles: true }));
+        }
+      }, cbInput, cbFilter);
+      await sleep(cbFilter ? cbFilterWait : cbOpenWait);
+      const cbOptionSel = '[role="option"], .MuiAutocomplete-option, li.MuiMenuItem-root, .MuiList-root li';
+      try {
+        await page.waitForFunction(
+          (sels, t) => [...document.querySelectorAll(sels)].some(o => (o.textContent || '').toLowerCase().includes(t.toLowerCase())),
+          { timeout }, cbOptionSel, cbOption
+        );
+      } catch (e) {
+        throw new Error(`select_combobox: no option matching "${cbOption}" appeared (filter="${cbFilter}")`);
+      }
+      const cbPicked = await page.evaluate((sels, t) => {
+        const c = [...document.querySelectorAll(sels)];
+        const m = c.find(o => (o.textContent || '').toLowerCase().includes(t.toLowerCase()));
+        if (m) { m.click(); return (m.textContent || '').trim().slice(0, 80); }
+        return null;
+      }, cbOptionSel, cbOption);
+      if (cbPicked === null) throw new Error(`select_combobox: option "${cbOption}" vanished before click`);
+      if (action.waitAfter) await sleep(parseInt(action.waitAfter));
+      break;
+    }
+
     case 'focus_autocomplete': {
       // Focus an autocomplete/combobox input by its label text.
       // Supports MUI Autocomplete (.MuiAutocomplete-root) and generic [role="combobox"].

package/src/config.js

@@ -60,6 +60,12 @@ const DEFAULTS = {
   screencastMaxWidth: 800,
   screencastMaxHeight: 600,
   screencastEveryNthFrame: 1,
+  // Auto-capture a thumbnail after each action so the storyline view is fully visual.
+  // Adds ~50-100ms per action; set false in CI if you only need final/error screenshots.
+  autoCaptureSteps: true,
+  autoCaptureWidth: 480,
+  autoCaptureHeight: 300,
+  autoCaptureQuality: 60,
   anthropicApiKey: null,
   anthropicModel: 'claude-sonnet-4-5-20250929',
   authToken: null,

package/src/dashboard.js

@@ -16,12 +16,13 @@ import { createRequire } from 'module';
 import { createWebSocketServer } from './websocket.js';
 import { getPoolUrls, getAggregatedPoolStatus, waitForAnyPool } from './pool-manager.js';
 import { runTestsParallel, loadAllSuites, loadTestSuite, listSuites } from './runner.js';
+import { runModuleAnalysis } from './module-analysis.js';
 import { generateReport, generateJUnitXML, saveReport, persistRun, loadHistory, loadHistoryRun } from './reporter.js';
-import { listProjects as dbListProjects, listProjectsWithSparklines as dbListProjectsWithSparklines, getProjectRuns as dbGetProjectRuns, getRunDetail as dbGetRunDetail, getAllRuns as dbGetAllRuns, getRunCount as dbGetRunCount, getProjectScreenshotsDir as dbGetProjectScreenshotsDir, getProjectTestsDir as dbGetProjectTestsDir, getProjectCwd as dbGetProjectCwd, lookupScreenshotHash as dbLookupScreenshotHash, ensureProject as dbEnsureProject, getNetworkLogs as dbGetNetworkLogs, listVariables as dbListVariables, setVariable as dbSetVariable, deleteVariable as dbDeleteVariable, closeDb } from './db.js';
+import { listProjects as dbListProjects, listProjectsWithSparklines as dbListProjectsWithSparklines, getProjectRuns as dbGetProjectRuns, getRunDetail as dbGetRunDetail, getAllRuns as dbGetAllRuns, getRunCount as dbGetRunCount, getProjectScreenshotsDir as dbGetProjectScreenshotsDir, getProjectTestsDir as dbGetProjectTestsDir, getProjectCwd as dbGetProjectCwd, lookupScreenshotHash as dbLookupScreenshotHash, getScreenshotMetaByPaths as dbGetScreenshotMetaByPaths, ensureProject as dbEnsureProject, getNetworkLogs as dbGetNetworkLogs, listVariables as dbListVariables, setVariable as dbSetVariable, deleteVariable as dbDeleteVariable, closeDb } from './db.js';
 import { loadConfig } from './config.js';
 import { log, colors as C } from './logger.js';
 import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getHealthSnapshot, getActionHealthScores } from './learner-sqlite.js';
-import { compareImages } from './visual-diff.js';
+import { compareImages, isBlankImage } from './visual-diff.js';
 import { handleSyncRoutes } from './sync/hub-routes.js';
 import { migrateSyncSchema } from './sync/schema.js';
 
@@ -36,6 +37,25 @@ const { version: VERSION } = _require('../package.json');
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// Blank-PNG verdicts cached per path+size+mtime so the gallery listing
+// doesn't re-decode every PNG on each request. Non-PNG files are never
+// flagged (isBlankImage fails open on undecodable input).
+const blankVerdictCache = new Map();
+function isBlankScreenshotCached(filePath) {
+  if (!/\.png$/i.test(filePath)) return false;
+  try {
+    const st = fs.statSync(filePath);
+    const key = `${filePath}:${st.size}:${st.mtimeMs}`;
+    if (blankVerdictCache.has(key)) return blankVerdictCache.get(key);
+    const blank = isBlankImage(filePath).blank;
+    if (blankVerdictCache.size > 5000) blankVerdictCache.clear();
+    blankVerdictCache.set(key, blank);
+    return blank;
+  } catch {
+    return false;
+  }
+}
+
 /** Starts the dashboard server */
 export async function startDashboard(config) {
   const port = config.dashboardPort || 8484;
@@ -89,11 +109,16 @@ export async function startDashboard(config) {
     const url = new URL(req.url, `http://localhost:${port}`);
     const pathname = url.pathname;
 
-    // CORS — restrict to same-origin (localhost on dashboard port)
+    // CORS — allow same-origin (Origin's host matches the Host header)
+    // and the explicit whitelist (localhost/127.0.0.1 on dashboard port).
     const allowedOrigins = [`http://localhost:${port}`, `http://127.0.0.1:${port}`];
     const origin = req.headers.origin;
-    if (origin && allowedOrigins.includes(origin)) {
-      res.setHeader('Access-Control-Allow-Origin', origin);
+    if (origin) {
+      let allowOrigin = allowedOrigins.includes(origin);
+      if (!allowOrigin && req.headers.host) {
+        try { allowOrigin = new URL(origin).host === req.headers.host; } catch { /* */ }
+      }
+      if (allowOrigin) res.setHeader('Access-Control-Allow-Origin', origin);
     }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, Mcp-Session-Id');
@@ -338,7 +363,9 @@ export async function startDashboard(config) {
         return;
       }
 
-      // API: DB — project screenshots list
+      // API: DB — project screenshots list (blank PNGs are hidden — they
+      // have no debug value and only waste gallery space; the blank-scan
+      // endpoint still finds them on disk for bulk deletion)
       const projectScreenshotsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/screenshots$/);
       if (projectScreenshotsMatch) {
         try {
@@ -349,7 +376,52 @@ export async function startDashboard(config) {
             return;
           }
           const files = fs.readdirSync(dir).filter(f => /\.(png|jpg|jpeg|gif|webp)$/i.test(f)).sort();
-          jsonResponse(res, files.map(f => ({ name: f, path: path.join(dir, f) })));
+          const visible = files.filter(f => !isBlankScreenshotCached(path.join(dir, f)));
+          const fullPaths = visible.map(f => path.join(dir, f));
+          const meta = dbGetScreenshotMetaByPaths(fullPaths);
+          // Filenames embed the SANITIZED test name (runner's safeName); build a map
+          // back to the real name from DB-known entries so legacy files (no DB row)
+          // land in the same group as their DB-registered siblings
+          const sanitize = (s) => String(s).replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+          const sanitizedToReal = {};
+          for (const m of Object.values(meta)) {
+            if (m.testName) sanitizedToReal[sanitize(m.testName)] = m.testName;
+          }
+          jsonResponse(res, visible.map(f => {
+            const fp = path.join(dir, f);
+            const m = meta[fp];
+            // Fallback for files predating DB metadata: parse the test name out of
+            // runner-generated filenames (step-/error-/baseline-/verify-/current-/diff-<test>-<ts>.<ext>)
+            let testName = m?.testName || null;
+            let type = m?.type || null;
+            if (!testName) {
+              const fm = f.match(/^(step|error|baseline|verify|current|diff)-(.+?)(?:-\d{3})?-\d{10,}\.(?:png|jpe?g|gif|webp)$/i);
+              if (fm) { type = type || fm[1].toLowerCase(); testName = sanitizedToReal[fm[2]] || fm[2]; }
+            }
+            return { name: f, path: fp, testName, type };
+          }));
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
+      // API: DB — scan a project's screenshots for blank (uniform-color) images
+      const blankScanMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/screenshots\/blank-scan$/);
+      if (blankScanMatch) {
+        try {
+          const projectId = parseInt(blankScanMatch[1], 10);
+          const dir = dbGetProjectScreenshotsDir(projectId);
+          if (!dir || !fs.existsSync(dir)) { jsonResponse(res, { blanks: [], scanned: 0 }); return; }
+          // Only PNGs are decodable; other formats are skipped (never flagged).
+          const files = fs.readdirSync(dir).filter(f => /\.png$/i.test(f)).sort();
+          const blanks = [];
+          for (const f of files) {
+            const fp = path.join(dir, f);
+            const r = isBlankImage(fp);
+            if (r.blank) blanks.push({ name: f, path: fp, color: r.color, brightness: r.brightness });
+          }
+          jsonResponse(res, { blanks, scanned: files.length });
         } catch (error) {
           jsonResponse(res, { error: error.message }, 500);
         }
@@ -458,6 +530,68 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: Tools — proxy to MCP tool handlers
+      // Generic helper: resolve projectId from POST body → cwd, then call dispatchTool.
+      if (pathname.startsWith('/api/tool/') && req.method === 'POST') {
+        const tool = pathname.replace('/api/tool/', '');
+        const map = { capture: 'e2e_capture', analyze: 'e2e_analyze', 'issue-verify': 'e2e_issue' };
+        const mcpName = map[tool];
+        if (!mcpName) { jsonResponse(res, { error: 'Unknown tool: ' + tool }, 400); return; }
+        let body = '';
+        let oversize = false;
+        req.on('data', chunk => { body += chunk; if (body.length > MAX_BODY) { oversize = true; req.destroy(); } });
+        req.on('end', async () => {
+          if (oversize) { jsonResponse(res, { error: 'Payload too large' }, 413); return; }
+          try {
+            const args = body ? JSON.parse(body) : {};
+            if (args.projectId) {
+              const pcwd = dbGetProjectCwd(parseInt(args.projectId, 10));
+              if (pcwd) args.cwd = pcwd;
+              delete args.projectId;
+            }
+            if (tool === 'issue-verify') args.mode = 'verify';
+            const result = await dispatchTool(mcpName, args);
+            // dispatchTool returns MCP-style { content:[{type,text}], isError? }.
+            // Convert to a friendlier shape for the dashboard.
+            let payload = result;
+            if (result && Array.isArray(result.content)) {
+              const text = result.content.map(c => c.text || '').join('\n');
+              let parsed = null; try { parsed = JSON.parse(text); } catch { /* */ }
+              payload = parsed || { text };
+              if (result.isError) payload.error = payload.error || payload.text || 'Tool returned error';
+            }
+            jsonResponse(res, payload);
+          } catch (error) {
+            jsonResponse(res, { error: error.message }, 500);
+          }
+        });
+        return;
+      }
+
+      // API: Tools — module analysis
+      // Reads all tests + modules in a project, finds repeated 3-8-action
+      // subsequences that appear in 2+ tests (extraction candidates), and
+      // counts current module usage. Returns a report ready for the
+      // dashboard to display + a prompt the user can paste into Claude Code
+      // to ask the test-improver agent for deeper analysis.
+      const modAnalysisMatch = pathname.match(/^\/api\/tools\/module-analysis\/(\d+)$/);
+      if (modAnalysisMatch) {
+        try {
+          const projectId = parseInt(modAnalysisMatch[1], 10);
+          const cwd = dbGetProjectCwd(projectId);
+          const testsDir = dbGetProjectTestsDir(projectId);
+          if (!cwd || !testsDir || !fs.existsSync(testsDir)) {
+            jsonResponse(res, { error: 'Project tests directory not found' }, 404);
+            return;
+          }
+          const modulesDir = path.join(cwd, 'e2e', 'modules');
+          jsonResponse(res, runModuleAnalysis(testsDir, modulesDir, projectId));
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
       // API: DB — project variables (set/upsert)
       if (projectVarsMatch && req.method === 'PUT') {
         let body = '';
@@ -545,6 +679,47 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: delete screenshots — { paths: [...] }, each validated against known dirs
+      if (pathname === '/api/screenshots/delete' && req.method === 'POST') {
+        let body = '';
+        let oversize = false;
+        req.on('data', chunk => { body += chunk; if (body.length > MAX_BODY) { oversize = true; req.destroy(); } });
+        req.on('end', () => {
+          if (oversize) { jsonResponse(res, { error: 'Payload too large' }, 413); return; }
+          try {
+            const { paths } = body ? JSON.parse(body) : {};
+            if (!Array.isArray(paths) || !paths.length) { jsonResponse(res, { error: 'Missing paths array' }, 400); return; }
+            // Build the allow-list of directories deletions may touch.
+            const allowedDirs = [path.resolve(config.screenshotsDir)];
+            try {
+              for (const p of dbListProjects()) {
+                const dir = p.screenshots_dir || path.join(p.cwd, 'e2e', 'screenshots');
+                allowedDirs.push(path.resolve(dir));
+              }
+            } catch { /* db may be unavailable */ }
+            let deleted = 0;
+            const failed = [];
+            for (const raw of paths) {
+              try {
+                if (typeof raw !== 'string' || !path.isAbsolute(raw)) { failed.push({ path: raw, error: 'Invalid path' }); continue; }
+                const real = fs.realpathSync(raw);
+                const inAllowed = allowedDirs.some(dir => real.startsWith(dir + path.sep) || real === dir);
+                if (!inAllowed) { failed.push({ path: raw, error: 'Access denied' }); continue; }
+                if (!/\.(png|jpg|jpeg|gif|webp)$/i.test(real)) { failed.push({ path: raw, error: 'Not an image' }); continue; }
+                fs.unlinkSync(real);
+                deleted++;
+              } catch (e) {
+                failed.push({ path: raw, error: e.message });
+              }
+            }
+            jsonResponse(res, { deleted, failed });
+          } catch (error) {
+            jsonResponse(res, { error: error.message }, 500);
+          }
+        });
+        return;
+      }
+
       // API: visual diff — compare two screenshots on demand
       if (pathname === '/api/visual-diff') {
         try {
@@ -627,9 +802,10 @@ export async function startDashboard(config) {
           return;
         }
         const ext = path.extname(realPath).toLowerCase();
-        const mimeTypes = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
+        // .json covers step data captures (raw API responses saved instead of screenshots)
+        const mimeTypes = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.json': 'application/json' };
         if (!mimeTypes[ext]) {
-          jsonResponse(res, { error: 'Not an image' }, 400);
+          jsonResponse(res, { error: 'Unsupported file type' }, 400);
           return;
         }
         res.writeHead(200, { 'Content-Type': mimeTypes[ext], 'Cache-Control': 'no-store' });

package/src/db.js

@@ -375,6 +375,20 @@ export function getScreenshotHashes(filePaths) {
   return result;
 }
 
+/** Batch lookup with metadata: given an array of file paths, returns
+ *  { [path]: { hash, testName, type } } for paths registered in screenshot_hashes. */
+export function getScreenshotMetaByPaths(filePaths) {
+  if (!filePaths || filePaths.length === 0) return {};
+  const d = getDb();
+  const stmt = d.prepare('SELECT hash, file_path, test_name, screenshot_type FROM screenshot_hashes WHERE file_path = ?');
+  const result = {};
+  for (const fp of filePaths) {
+    const row = stmt.get(fp);
+    if (row) result[fp] = { hash: row.hash, testName: row.test_name || null, type: row.screenshot_type || null };
+  }
+  return result;
+}
+
 /** Save a run + its test results in a single transaction. Returns the run's DB id. */
 export function saveRun(projectId, report, runId, suiteName, triggeredBy, poolDriver) {
   const d = getDb();
@@ -429,6 +443,9 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy, poolDr
         narrative: a.narrative || undefined,
         error: a.error || undefined,
         actionRetries: a.actionRetries || undefined,
+        autoScreenshot: a.autoScreenshot || undefined,
+        dataCapture: a.dataCapture || undefined,
+        screenshot: a.result?.screenshot || undefined,
       }));
 
       insertTest.run(
@@ -461,6 +478,15 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy, poolDr
         const actionIdx = r.actions.indexOf(a);
         insertHash.run(computeScreenshotHash(a.result.screenshot), a.result.screenshot, projectId, runDbId, r.name, actionIdx, null, 'action');
       }
+
+      // Auto-captured per-step thumbnails for the storyline view
+      (r.actions || []).forEach((a, idx) => {
+        if (a.autoScreenshot) {
+          try {
+            insertHash.run(computeScreenshotHash(a.autoScreenshot), a.autoScreenshot, projectId, runDbId, r.name, idx, null, 'step');
+          } catch { /* best effort */ }
+        }
+      });
       if (r.errorScreenshot) {
         insertHash.run(computeScreenshotHash(r.errorScreenshot), r.errorScreenshot, projectId, runDbId, r.name, null, null, 'error');
       }