@matware/e2e-runner 1.5.0 → 1.5.1

package/src/mcp-tools.js

@@ -23,11 +23,12 @@ import { lookupScreenshotHash, ensureProject, computeScreenshotHash, registerScr
 import { fetchIssue, checkCliAuth, detectProvider } from './issues.js';
 import { buildPrompt, hasApiKey, generateHindsightHint } from './ai-generate.js';
 import { verifyIssue } from './verify.js';
-import { listModules } from './module-resolver.js';
+import { listModules, loadModuleRegistry } from './module-resolver.js';
 import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestHistory, getPageHistory, getSelectorHistory, getHealthSnapshot, getTestCreationContext, generateImprovements, getActionHealthScores } from './learner-sqlite.js';
 import { queryGraph } from './learner-neo4j.js';
 import { startNeo4j, stopNeo4j, getNeo4jStatus } from './neo4j-pool.js';
 import { getAppPoolStatus, isAppPoolEnabled } from './app-pool.js';
+import { looksLikeBlankCapture } from './actions.js';
 
 /**
  * Resolves auth token from config: uses static authToken if set,
@@ -103,7 +104,7 @@ export const TOOLS = [
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -117,7 +118,7 @@ export const TOOLS = [
       properties: {
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -125,66 +126,19 @@ export const TOOLS = [
   {
     name: 'e2e_create_test',
     description:
-      `Create a new E2E test JSON file. IMPORTANT: prefer built-in actions over evaluate blocks.
-
-## Action selection guide (use instead of evaluate)
-
-**Clicking elements by text** — DON'T write evaluate to find+click elements:
-  click:           { type: "click", text: "Submit" }              — searches button, a, [role=tab], span, etc.
-  click_regex:     { type: "click_regex", text: "save|guardar" }  — regex match, case-insensitive
-  click_menu_item: { type: "click_menu_item", text: "Delete" }    — [role=menuitem], .MenuItem, etc.
-  click_option:    { type: "click_option", text: "Option A" }     — [role=option] in dropdowns
-  click_chip:      { type: "click_chip", text: "Active" }         — MUI Chip / tag elements
-  click_icon:      { type: "click_icon", value: "edit" }          — SVG/icon by data-testid, aria-label, class
-  click_in_context:{ type: "click_in_context", text: "Row text", selector: "button" } — child within container
-  click (in dialog):{ type: "click", text: "Confirm", scope: "dialog", last: true } — only [role=dialog]/MuiDialog; visible:true skips hidden; last:true picks last match
-
-**Selecting from a MUI Autocomplete/Select** — DON'T write evaluate to open+filter+pick:
-  select_combobox: { type: "select_combobox", selector: "input[role='combobox']", filter: "cardio", text: "Cardiología" }
-                   — opens the combobox, types optional filter, clicks the matching option (role=option / MuiAutocomplete-option / MuiMenuItem)
-
-**Asserting text presence/absence** — DON'T write evaluate with body.includes():
-  assert_text:     { type: "assert_text", text: "Welcome" }      — text IS on page (case-sensitive). Uses: text
-  assert_no_text:  { type: "assert_no_text", text: "Error" }     — text is NOT on page. Uses: text
-  assert_text_in:  { type: "assert_text_in", selector: "[class*='Drawer']", text: "profesional|doctor" }
-                   — scoped regex in container (case-insensitive default). Uses: selector + text (+ value:"exact")
-
-**Asserting elements** — DON'T write evaluate to count or check visibility:
-  assert_visible:      { type: "assert_visible", selector: ".modal" }           — Uses: selector (NOT text)
-  assert_not_visible:  { type: "assert_not_visible", selector: ".loader" }      — Uses: selector (NOT text)
-  assert_count:        { type: "assert_count", selector: "input", value: ">= 2" } — Uses: selector + value
-  assert_element_text: { type: "assert_element_text", selector: "h1", text: "Dashboard" } — Uses: selector + text
-  assert_matches:      { type: "assert_matches", selector: ".date", value: "\\\\d{2}/\\\\d{2}" } — Uses: selector + value (regex)
-  assert_attribute:    { type: "assert_attribute", selector: "button", value: "disabled" } — Uses: selector + value
-  assert_url:          { type: "assert_url", value: "/dashboard" }              — Uses: value
-  assert_input_value:  { type: "assert_input_value", selector: "#email", value: "@" } — Uses: selector + value
-
-IMPORTANT field rules:
-  - assert_text / assert_no_text: use "text" field only (checks full page body)
-  - assert_visible / assert_not_visible: use "selector" field only (CSS selector, NOT text)
-  - To verify text absence: use assert_no_text (NOT assert_not_visible with text)
-
-**Navigation & waiting** — DON'T write evaluate with setTimeout polling:
-  goto:            { type: "goto", value: "/login" }              — full page navigation
-  navigate:        { type: "navigate", value: "/settings" }       — SPA-friendly (won't fail if no page load)
-  wait:            { type: "wait", text: "Loading complete" }     — wait for text to appear in body
-  wait:            { type: "wait", selector: ".results" }         — wait for element to appear
-  wait (gone):     { type: "wait", gone: ".MuiBackdrop-root" }    — wait until a selector disappears/hides (spinner, closing dialog)
-  wait:            { type: "wait", value: "2000" }                — fixed delay (last resort — prefer gone/selector/text)
-  wait_network_idle: { type: "wait_network_idle", value: "500" }  — wait until no network for N ms
-
-**Form interaction** — DON'T write evaluate with native value setters (unless React):
-  type:            { type: "type", selector: "#email", value: "a@b.com" } — clears + types
-  type_react:      { type: "type_react", selector: "#email", value: "a@b.com", waitAfter: "400" } — React controlled inputs; optional blur:true / waitAfter ms
-  select:          { type: "select", selector: "select#country", value: "US" }
-  clear:           { type: "clear", selector: "#search" }
-  press:           { type: "press", value: "Enter" }
-  focus_autocomplete: { type: "focus_autocomplete", text: "City" } — focus MUI Autocomplete by label
-
-**When evaluate IS appropriate**: computed styles, complex conditional logic, GraphQL via window.__e2eGql, math calculations, reading window/app state.
-
-## Modules
-Use { "$use": "module-name", "params": {...} } to reference reusable modules from e2e/modules/. Modules compose — a module can $use other modules. Check e2e_list to see available modules for the project.`,
+      `Create a new E2E test JSON file. Prefer built-in actions over evaluate — more robust and readable. Full catalog: the e2e-testing skill / references/action-types.md.
+
+Action cheat-sheet:
+- Click: click (by text), click_regex, click_menu_item, click_option, click_chip, click_icon, click_in_context; in a dialog use click with scope:"dialog" (+ last/visible).
+- Select (MUI): select_combobox (open+optional filter+pick), select, focus_autocomplete.
+- Assert text: assert_text (present), assert_no_text (absent), assert_text_in (scoped regex), assert_element_text, assert_matches.
+- Assert elements (selector, NOT text): assert_visible, assert_not_visible, assert_count, assert_attribute, assert_input_value, assert_url.
+- Nav/wait: goto, navigate (SPA), wait {text|selector|gone|value(ms)}, wait_network_idle.
+- Form: type, type_react (React inputs; optional blur/waitAfter), clear, press.
+
+Field rules: assert_text/assert_no_text use "text" (whole page); assert_visible/assert_not_visible use "selector"; for text absence use assert_no_text. Use evaluate only for computed styles, complex logic, GraphQL (window.__e2eGql), or app state.
+
+Modules: { "$use": "module-name", "params": {...} } references reusable modules in e2e/modules/ (they compose). Run e2e_list to see available modules.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -239,7 +193,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['name', 'tests'],
@@ -254,7 +208,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
       properties: {
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -301,7 +255,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -327,7 +281,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -364,7 +318,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['url'],
@@ -412,7 +366,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['url'],
@@ -464,7 +418,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['url'],
@@ -539,7 +493,7 @@ Good module candidates: auth setup, page navigation, tab clicking, opening sideb
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['query'],
@@ -1010,6 +964,65 @@ async function handleCreateTest(args) {
     }
   } catch { /* modules dir may not exist */ }
 
+  // ── #2/#3: nudge module reuse and flag extractable duplication ──
+  try {
+    const fullModules = [...loadModuleRegistry(config.modulesDir).values()];
+
+    // #2 — submitted actions already match an existing module verbatim
+    const matches = detectModuleMatches(args.tests, fullModules);
+    for (const h of matches) {
+      const req = h.params ? Object.entries(h.params).filter(([, d]) => d?.required).map(([n]) => n) : [];
+      const paramHint = req.length ? `, "params": { ${req.map(n => `"${n}": ...`).join(', ')} }` : '';
+      warnings.push(`♻️ Test "${h.test}" repeats the ${h.len} actions of existing module "${h.module}" inline. ` +
+        `Replace them with { "$use": "${h.module}"${paramHint} }.`);
+    }
+
+    // #3 — action sequences duplicated across tests that aren't a module yet
+    const matchedTests = new Set(matches.map(m => m.test));
+    const testsActions = args.tests
+      .filter(t => t.actions && !t.actions.some(a => a && a.$use) && !matchedTests.has(t.name))
+      .map(t => ({ name: t.name, sigs: actionsSigList(t.actions) }));
+
+    // include existing test files (excluding the one just written) for cross-file duplication
+    try {
+      if (fs.existsSync(config.testsDir)) {
+        for (const f of fs.readdirSync(config.testsDir).filter(x => x.endsWith('.json'))) {
+          const fp = path.join(config.testsDir, f);
+          if (fp === filePath) continue;
+          let parsed;
+          try { parsed = JSON.parse(fs.readFileSync(fp, 'utf-8')); } catch { continue; }
+          const list = Array.isArray(parsed) ? parsed : (parsed.tests || []);
+          for (const t of list) {
+            if (t && t.actions && !t.actions.some(a => a && a.$use)) {
+              testsActions.push({ name: `${f}:${t.name}`, sigs: actionsSigList(t.actions) });
+            }
+          }
+        }
+      }
+    } catch { /* ignore unreadable test files */ }
+
+    // windows already covered by an existing module → don't re-suggest extracting them
+    const moduleWindowSet = new Set();
+    for (const m of fullModules) {
+      const sigs = actionsSigList((m.actions || []).filter(a => a && !a.$use));
+      for (const w of sigWindows(sigs, 2, 6)) moduleWindowSet.add(w);
+    }
+
+    const extractable = detectExtractableSequences(testsActions, moduleWindowSet);
+    for (const e of extractable) {
+      const sample = e.tests.slice(0, 3).join(', ') + (e.tests.length > 3 ? '…' : '');
+      warnings.push(`🧩 A sequence of ${e.len} actions appears in ${e.count} tests (${sample}) but isn't a module yet. ` +
+        `Consider extracting it with e2e_create_module and referencing it via $use.`);
+    }
+  } catch { /* never fail test creation */ }
+
+  // ── Verification coverage: tests whose outcome is never checked ──
+  try {
+    let registry;
+    try { registry = loadModuleRegistry(config.modulesDir); } catch { registry = new Map(); }
+    warnings.push(...detectUnverifiedTests(args.tests, registry));
+  } catch { /* never fail test creation */ }
+
   const warningBlock = warnings.length > 0 ? '\n\n' + warnings.join('\n\n') : '';
 
   // Enrich with learnings context for smarter test authoring
@@ -1265,6 +1278,135 @@ function analyzeActionPatterns(tests) {
   return warnings;
 }
 
+// ── Module-reuse detection (#2 exact match, #3 extractable duplication) ──
+
+// Normalized signature of an action for sequence comparison.
+function actionSig(a) {
+  if (!a || typeof a !== 'object') return '∅';
+  if (a.$use) return `$use:${a.$use}`;
+  return `${a.type || '?'}|${a.selector || ''}|${a.text || ''}`;
+}
+function actionsSigList(actions) {
+  return (actions || []).map(actionSig);
+}
+// All contiguous sig windows of length minLen..maxLen, each joined with '»'.
+function sigWindows(sigs, minLen, maxLen) {
+  const out = [];
+  const top = Math.min(maxLen, sigs.length);
+  for (let len = minLen; len <= top; len++) {
+    for (let i = 0; i + len <= sigs.length; i++) {
+      out.push(sigs.slice(i, i + len).join('»'));
+    }
+  }
+  return out;
+}
+
+// #2 — a module field matches a concrete test field; {{param}} placeholders are wildcards.
+function moduleFieldMatch(modVal, testVal) {
+  if (modVal == null || modVal === '') return true;            // module doesn't constrain it
+  if (typeof modVal === 'string' && modVal.includes('{{')) return true; // placeholder → wildcard
+  return modVal === testVal;
+}
+function moduleActionMatch(modA, testA) {
+  if (!modA || !testA || modA.$use || testA.$use) return false;
+  return modA.type === testA.type
+    && moduleFieldMatch(modA.selector, testA.selector)
+    && moduleFieldMatch(modA.text, testA.text);
+}
+// Find modules whose full leaf-action sequence appears as a contiguous run inside a test
+// that doesn't already use modules. Returns [{ module, params, test, len }].
+function detectModuleMatches(tests, fullModules) {
+  const hits = [];
+  for (const mod of fullModules) {
+    const ma = (mod.actions || []).filter(a => a && !a.$use);
+    if (ma.length < 2) continue;
+    for (const test of tests) {
+      const ta = test.actions || [];
+      if (ta.some(a => a && a.$use)) continue; // already modular
+      for (let i = 0; i + ma.length <= ta.length; i++) {
+        let ok = true;
+        for (let j = 0; j < ma.length; j++) {
+          if (!moduleActionMatch(ma[j], ta[i + j])) { ok = false; break; }
+        }
+        if (ok) { hits.push({ module: mod.$module, params: mod.params, test: test.name, len: ma.length }); break; }
+      }
+    }
+  }
+  return hits;
+}
+// #3 — contiguous sig windows (len>=minLen) shared by >=2 distinct tests and not already a module.
+function detectExtractableSequences(testsActions, moduleWindowSet, { minLen = 3, maxLen = 6, cap = 2 } = {}) {
+  const owners = new Map(); // windowKey -> Set(testName)
+  const lenOf = new Map();  // windowKey -> action count
+  for (const t of testsActions) {
+    const seen = new Set();
+    for (const key of sigWindows(t.sigs, minLen, maxLen)) {
+      if (key.includes('$use:') || moduleWindowSet.has(key) || seen.has(key)) continue;
+      seen.add(key);
+      if (!owners.has(key)) { owners.set(key, new Set()); lenOf.set(key, key.split('»').length); }
+      owners.get(key).add(t.name);
+    }
+  }
+  const cands = [];
+  for (const [key, set] of owners) {
+    if (set.size >= 2) cands.push({ key, len: lenOf.get(key), count: set.size, tests: [...set] });
+  }
+  cands.sort((a, b) => b.len - a.len || b.count - a.count); // longest, then most frequent
+  const kept = [];
+  for (const c of cands) {
+    if (kept.some(k => k.key.includes(c.key))) continue; // subsumed by a longer kept window
+    kept.push(c);
+    if (kept.length >= cap) break;
+  }
+  return kept;
+}
+
+// Verification coverage — a test whose interactions are never followed by a check
+// can go green even when the flow silently breaks.
+function isVerifyingAction(a) {
+  if (/^assert_/.test(a.type || '')) return true;
+  if (a.type === 'evaluate' || a.type === 'gql') return true; // strict semantics / inline assertions
+  if (a.type === 'wait' && (a.selector || a.text || a.gone)) return true; // condition waits fail if unmet
+  return false;
+}
+function isInteractingAction(a) {
+  return /^(click|select|type|fill|clear|press|hover|scroll|set_storage|focus_autocomplete|goto|navigate)/.test(a.type || '');
+}
+function detectUnverifiedTests(tests, registry) {
+  const out = [];
+  for (const t of tests || []) {
+    if (!t || !Array.isArray(t.actions) || t.expect) continue; // "expect" verifies the end state visually
+    // expand $use so module-provided assertions count
+    const leaf = [];
+    let resolvable = true;
+    for (const a of t.actions) {
+      if (a && a.$use) {
+        const mod = registry.get(a.$use);
+        if (mod?.actions) leaf.push(...mod.actions.filter(x => x && !x.$use));
+        else { resolvable = false; break; }
+      } else if (a) leaf.push(a);
+    }
+    if (!resolvable) continue;
+    let lastInteract = -1;
+    leaf.forEach((a, i) => { if (isInteractingAction(a)) lastInteract = i; });
+    if (lastInteract === -1) continue; // nothing happens — nothing to verify
+    if (!leaf.some(isVerifyingAction)) {
+      out.push(`🔎 Test "${t.name}" has no assertions and no "expect" field — it can pass without verifying anything. ` +
+        `Close with assert_* actions (assert_url, assert_text, assert_visible) or add an "expect" for visual verification.`);
+    } else if (!leaf.slice(lastInteract + 1).some(isVerifyingAction)) {
+      out.push(`🔎 Test "${t.name}" keeps interacting after its last check — the final steps are unverified. ` +
+        `Close with an assert_* action so the end state is what passes the test.`);
+    } else {
+      const tail = leaf.slice(lastInteract + 1).filter(isVerifyingAction);
+      if (tail.length && tail.every(a => a.type === 'assert_text')) {
+        out.push(`📌 Test "${t.name}" closes with page-wide assert_text only — it matches anywhere on the page. ` +
+          `Scope the final check with assert_element_text or assert_text_in.`);
+      }
+    }
+  }
+  return out;
+}
+
 async function handlePoolStatus(args) {
   const config = await loadConfig({}, args.cwd);
   const poolUrls = getPoolUrls(config);
@@ -1961,7 +2103,19 @@ async function handleAnalyze(args) {
       screenshotBase64 = data.toString('base64');
     }
 
-    const result = { meta, ...structure, suggestedTests };
+    // Surface reusable modules at the decision point, so scaffolds can $use them
+    // instead of duplicating action sequences.
+    let availableModules = [];
+    try {
+      availableModules = listModules(config.modulesDir).map(m => ({
+        name: m.name,
+        params: m.params.map(p => (p.required ? p.name : `${p.name}?`)),
+        description: m.description || undefined,
+        hint: `{ "$use": "${m.name}"${m.params.some(p => p.required) ? ', "params": { ... }' : ''} }`,
+      }));
+    } catch { /* modules dir may not exist */ }
+
+    const result = { meta, ...structure, suggestedTests, availableModules };
     const content = [{ type: 'text', text: JSON.stringify(result, null, 2) }];
 
     if (screenshotBase64) {
@@ -2017,7 +2171,18 @@ async function handleCapture(args) {
     }
 
     const screenshotPath = path.join(config.screenshotsDir, filename);
-    await page.screenshot({ path: screenshotPath, fullPage: !!args.fullPage });
+    const data = await page.screenshot({ fullPage: !!args.fullPage });
+
+    // Blank frame (uniform color — page never rendered): don't save it,
+    // report what happened instead of returning a useless white PNG.
+    if (looksLikeBlankCapture(data, 'png')) {
+      return {
+        content: [
+          { type: 'text', text: `Capture skipped: ${args.url} rendered a blank (uniform-color) frame — nothing saved. The page likely failed to render (auth redirect, JS error, or slow load); try a longer delay or a selector to wait for.` },
+        ],
+      };
+    }
+    fs.writeFileSync(screenshotPath, data);
 
     // Register hash in SQLite
     const cwd = args.cwd || process.cwd();
@@ -2026,8 +2191,6 @@ async function handleCapture(args) {
     const hash = computeScreenshotHash(screenshotPath);
     registerScreenshotHash(hash, screenshotPath, projectId, null);
 
-    // Read image for response
-    const data = fs.readFileSync(screenshotPath);
     const base64 = data.toString('base64');
 
     return {

package/src/narrate.js

@@ -59,6 +59,12 @@ export function narrateAction(action, result) {
     case 'assert_text':
       return `Verified text "${text}" is present on page${time}`;
 
+    case 'assert_no_text':
+      return `Verified text "${text}" is NOT present on page${time}`;
+
+    case 'assert_text_in':
+      return `Verified "${selector}" contains text "${text}"${value === 'exact' ? ' (exact)' : ''}${time}`;
+
     case 'assert_url':
       return `Verified URL contains "${value}"${time}`;
 
@@ -186,6 +192,15 @@ export function narrateAction(action, result) {
       return `Visual comparison against "${value}": ${pct}${time}`;
     }
 
+    case 'gql': {
+      const query = (value || '').replace(/\s+/g, ' ').trim();
+      const snippet = query.length > 60 ? query.slice(0, 57) + '...' : query;
+      return `Executed GraphQL: ${snippet}${selector ? ' (asserted response)' : ''}${time}`;
+    }
+
+    case 'wait_network_idle':
+      return `Waited for network idle (${value || 500}ms)${time}`;
+
     case 'open_tab':
       return `Opened new tab${text ? ` "${text}"` : ''} → ${value}${time}`;
 
@@ -223,6 +238,8 @@ function describeIntent(action) {
       return           `Wait ${value}ms`;
     case 'screenshot': return 'Capture screenshot';
     case 'assert_text':           return `Assert text "${text}" present`;
+    case 'assert_no_text':        return `Assert text "${text}" NOT present`;
+    case 'assert_text_in':        return `Assert "${selector}" contains "${text}"`;
     case 'assert_url':            return `Assert URL contains "${value}"`;
     case 'assert_visible':        return `Assert "${selector}" visible`;
     case 'assert_count':          return `Assert "${selector}" count = ${value}`;
@@ -259,6 +276,8 @@ function describeIntent(action) {
     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 'gql':                    return 'Execute GraphQL query';
+    case 'wait_network_idle':      return 'Wait for network idle';
     case 'open_tab':               return `Open new tab → ${value}`;
     case 'switch_tab':             return `Switch to tab "${value}"`;
     case 'close_tab':              return `Close tab${value ? ` "${value}"` : ''}`;

package/src/runner.js

@@ -9,6 +9,7 @@ import fs from 'fs';
 import path from 'path';
 import http from 'http';
 import https from 'https';
+import crypto from 'crypto';
 import { connectToPool, getCachedDriver, disconnectFromPool } from './pool.js';
 import { getPoolUrls, selectPool, releasePending, resolvePoolsForTest } from './pool-manager.js';
 import { forkAppInstance, destroyFork, isAppPoolEnabled } from './app-pool.js';
@@ -28,9 +29,17 @@ function sleep(ms) {
  * Captures once in memory, writes to disk AND returns base64 so callers
  * can stream the same frame through the live preview WebSocket.
  * Skips silently on any error so it never breaks a test run.
+ *
+ * Content dedup: when the captured frame is byte-identical to the previous
+ * step's frame (tracked per-test via dedupState), reuses the existing file
+ * instead of writing a duplicate, and skips re-streaming the live frame.
+ *
+ * Raw data responses (JSON/plain-text endpoints rendered by Chrome's viewer
+ * as a white page with a single <pre>) are NOT screenshotted — the body is
+ * saved as a minified .json sidecar instead and returned as { dataPath }.
  */
 const NO_AUTO_CAPTURE_TYPES = new Set(['screenshot', 'close_tab']);
-async function tryAutoCaptureStep(page, action, idx, testName, effectiveConfig, alreadyCaptured) {
+async function tryAutoCaptureStep(page, action, idx, testName, effectiveConfig, alreadyCaptured, dedupState) {
   if (!effectiveConfig.autoCaptureSteps) return null;
   if (NO_AUTO_CAPTURE_TYPES.has(action?.type)) return null;
   if (alreadyCaptured) return null;
@@ -40,6 +49,31 @@ async function tryAutoCaptureStep(page, action, idx, testName, effectiveConfig,
   if (!(await pageHasRenderableContent(page))) return null;
   try {
     const safeName = String(testName).replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+    // Raw JSON/text response? Save the body as data, not as a white JPEG.
+    const rawBody = await page.evaluate(() => {
+      const ct = document.contentType || '';
+      const b = document.body;
+      const lonePre = !!(b && b.children.length === 1 && b.children[0].tagName === 'PRE' && b.children[0].children.length === 0);
+      if ((ct && ct !== 'text/html') || lonePre) return (b && b.innerText) || '';
+      return null;
+    }).catch(() => null);
+    if (rawBody !== null) {
+      let text = rawBody.trim();
+      if (!text) return null;
+      try { text = JSON.stringify(JSON.parse(text)); } catch { /* not JSON — keep raw text */ }
+      const dataBuf = Buffer.from(text, 'utf8');
+      const dataHash = crypto.createHash('sha1').update(dataBuf).digest('hex');
+      if (dedupState && dedupState.hash === dataHash && dedupState.path) {
+        return { dataPath: dedupState.path, deduped: true };
+      }
+      const dataPath = path.join(effectiveConfig.screenshotsDir, `step-${safeName}-${String(idx).padStart(3, '0')}-${Date.now()}.json`);
+      fs.writeFileSync(dataPath, dataBuf);
+      if (dedupState) {
+        dedupState.hash = dataHash;
+        dedupState.path = dataPath;
+      }
+      return { dataPath };
+    }
     const filename = `step-${safeName}-${String(idx).padStart(3, '0')}-${Date.now()}.jpg`;
     const filepath = path.join(effectiveConfig.screenshotsDir, filename);
     const buf = await page.screenshot({
@@ -49,7 +83,16 @@ async function tryAutoCaptureStep(page, action, idx, testName, effectiveConfig,
       encoding: 'binary',
     });
     if (looksLikeBlankCapture(buf, 'jpeg')) return null;
+    const contentHash = crypto.createHash('sha1').update(buf).digest('hex');
+    if (dedupState && dedupState.hash === contentHash && dedupState.path) {
+      // Same frame as the previous step — reuse the file, don't re-stream
+      return { path: dedupState.path, base64: null, deduped: true };
+    }
     fs.writeFileSync(filepath, buf);
+    if (dedupState) {
+      dedupState.hash = contentHash;
+      dedupState.path = filepath;
+    }
     return { path: filepath, base64: buf.toString('base64') };
   } catch {
     return null;
@@ -356,16 +399,25 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
       await executeHookActions(page, hooks.beforeEach, effectiveConfig);
     }
 
-    // Auto-capture baseline screenshot if test has "expect" (BEFORE actions)
+    // Auto-capture baseline screenshot if test has "expect" (BEFORE actions).
+    // Blank frames (about:blank, white unrendered page) are not saved —
+    // they have no comparison value and pollute screenshotsDir.
     if (test.expect && page) {
       try {
-        const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
-        const baselinePath = path.join(effectiveConfig.screenshotsDir, `baseline-${safeName}-${Date.now()}.png`);
-        await page.screenshot({ path: baselinePath, fullPage: true });
-        result.baselineScreenshot = baselinePath;
+        const baseBuf = await page.screenshot({ fullPage: true });
+        if (!looksLikeBlankCapture(baseBuf, 'png')) {
+          const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
+          const baselinePath = path.join(effectiveConfig.screenshotsDir, `baseline-${safeName}-${Date.now()}.png`);
+          fs.writeFileSync(baselinePath, baseBuf);
+          result.baselineScreenshot = baselinePath;
+        }
       } catch { /* page may not be ready */ }
     }
 
+    // Tracks the last auto-captured frame (content hash + path) so identical
+    // consecutive step screenshots reuse the same file instead of duplicating
+    const stepCaptureState = { hash: null, path: null };
+
     for (let i = 0; i < test.actions.length; i++) {
       const action = test.actions[i];
       const maxActionRetries = action.retries ?? effectiveConfig.actionRetries ?? 0;
@@ -492,14 +544,15 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
             actionResult = await executeAction(page, action, effectiveConfig);
           }
           const actionDuration = Date.now() - actionStart;
-          const autoShot = await tryAutoCaptureStep(page, action, i, test.name, effectiveConfig, !!actionResult?.screenshot);
+          const autoShot = await tryAutoCaptureStep(page, action, i, test.name, effectiveConfig, !!actionResult?.screenshot, stepCaptureState);
           const actionEntry = {
             ...action,
             success: true,
             duration: actionDuration,
             result: actionResult,
           };
-          if (autoShot) actionEntry.autoScreenshot = autoShot.path;
+          if (autoShot?.path) actionEntry.autoScreenshot = autoShot.path;
+          if (autoShot?.dataPath) actionEntry.dataCapture = autoShot.dataPath;
           if (attempt > 0) actionEntry.actionRetries = attempt;
           actionEntry.narrative = narrateAction(action, actionEntry);
           result.actions.push(actionEntry);
@@ -516,14 +569,15 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
             continue;
           }
           const actionDuration = Date.now() - actionStart;
-          const autoShot = await tryAutoCaptureStep(page, action, i, test.name, effectiveConfig, false);
+          const autoShot = await tryAutoCaptureStep(page, action, i, test.name, effectiveConfig, false, stepCaptureState);
           const failedEntry = {
             ...action,
             success: false,
             duration: actionDuration,
             error: error.message,
           };
-          if (autoShot) failedEntry.autoScreenshot = autoShot.path;
+          if (autoShot?.path) failedEntry.autoScreenshot = autoShot.path;
+          if (autoShot?.dataPath) failedEntry.dataCapture = autoShot.dataPath;
           if (maxActionRetries > 0) failedEntry.actionRetries = attempt;
           failedEntry.narrative = narrateAction(action, failedEntry);
           result.actions.push(failedEntry);
@@ -540,14 +594,18 @@ export async function runTest(test, config, hooks = {}, progressFn = () => {}) {
       throw new Error(`Network errors detected (failOnNetworkError=true): ${result.networkErrors.length} error(s): ${summary}`);
     }
 
-    // Auto-capture verification screenshot if test has "expect"
+    // Auto-capture verification screenshot if test has "expect".
+    // Blank frames are skipped (not saved) — same guard as the baseline.
     if (test.expect && page) {
       result.expect = test.expect;
       try {
         const safeName = test.name.replace(/[^a-zA-Z0-9_\-. ]/g, '_');
-        const verifyPath = path.join(effectiveConfig.screenshotsDir, `verify-${safeName}-${Date.now()}.png`);
-        await page.screenshot({ path: verifyPath, fullPage: true });
-        result.verificationScreenshot = verifyPath;
+        const verifyBuf = await page.screenshot({ fullPage: true });
+        if (!looksLikeBlankCapture(verifyBuf, 'png')) {
+          const verifyPath = path.join(effectiveConfig.screenshotsDir, `verify-${safeName}-${Date.now()}.png`);
+          fs.writeFileSync(verifyPath, verifyBuf);
+          result.verificationScreenshot = verifyPath;
+        }
 
         // Auto visual comparison: compare baseline vs verification screenshot
         if (result.baselineScreenshot && result.verificationScreenshot) {