@matware/e2e-runner 1.1.0 → 1.2.1

package/src/actions.js

@@ -31,13 +31,14 @@ export async function executeAction(page, action, config) {
         await page.waitForSelector(selector, { timeout });
         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';
         await page.waitForFunction(
-          (t) => [...document.querySelectorAll('button, a, [role="button"], [role="tab"], [role="menuitem"], div[class*="cursor"], span')]
+          (t, sel) => [...document.querySelectorAll(sel)]
             .find(el => el.textContent.includes(t)),
           { timeout },
-          text
+          text, clickTextSelector
         );
-        await page.$$eval('button, a, [role="button"], [role="tab"], [role="menuitem"], div[class*="cursor"], span', (els, t) => {
+        await page.$$eval(clickTextSelector, (els, t) => {
           const el = els.find(e => e.textContent.includes(t));
           if (el) el.click();
         }, text);
@@ -54,13 +55,21 @@ export async function executeAction(page, action, config) {
 
     case 'wait':
       if (selector) {
-        await page.waitForSelector(selector, { timeout });
+        try {
+          await page.waitForSelector(selector, { timeout });
+        } catch (e) {
+          throw new Error(`wait failed: selector "${selector}" not found after ${timeout}ms`);
+        }
       } else if (text) {
-        await page.waitForFunction(
-          (t) => document.body.innerText.includes(t),
-          { timeout },
-          text
-        );
+        try {
+          await page.waitForFunction(
+            (t) => document.body.innerText.includes(t),
+            { timeout },
+            text
+          );
+        } catch (e) {
+          throw new Error(`wait failed: text "${text}" not found after ${timeout}ms`);
+        }
       } else if (value) {
         await sleep(parseInt(value));
       }
@@ -73,6 +82,13 @@ export async function executeAction(page, action, config) {
       }
       // Sanitize: use only the basename to prevent path traversal
       filename = path.basename(filename);
+      // Inject timestamp before extension to make filenames unique per run
+      // (prevents overwriting previous runs' screenshots)
+      if (value) {
+        const ext = path.extname(filename);
+        const base = filename.slice(0, -ext.length);
+        filename = `${base}-${Date.now()}${ext}`;
+      }
       const filepath = path.join(screenshotsDir, filename);
       await page.screenshot({ path: filepath, fullPage: action.fullPage || false });
       return { screenshot: filepath };
@@ -88,8 +104,26 @@ export async function executeAction(page, action, config) {
 
     case 'assert_url': {
       const currentUrl = page.url();
-      if (!currentUrl.includes(value)) {
-        throw new Error(`assert_url failed: expected "${value}", got "${currentUrl}"`);
+      let match = false;
+      if (value.startsWith('/')) {
+        // Path-only comparison: extract pathname (+ query if value has ?)
+        try {
+          const parsed = new URL(currentUrl);
+          const compareTo = value.includes('?') ? parsed.pathname + parsed.search : parsed.pathname;
+          match = compareTo === value || compareTo.startsWith(value);
+        } catch {
+          match = currentUrl.includes(value);
+        }
+        if (!match) {
+          const pathname = (() => { try { return new URL(currentUrl).pathname; } catch { return currentUrl; } })();
+          throw new Error(`assert_url failed: expected path "${value}", got "${pathname}" (full: ${currentUrl})`);
+        }
+      } else {
+        // Full URL comparison (backwards compatible)
+        match = currentUrl.includes(value);
+        if (!match) {
+          throw new Error(`assert_url failed: expected "${value}", got "${currentUrl}"`);
+        }
       }
       break;
     }
@@ -111,13 +145,107 @@ export async function executeAction(page, action, config) {
 
     case 'assert_count': {
       const count = await page.$$eval(selector, els => els.length);
-      const expected = parseInt(value);
-      if (count !== expected) {
-        throw new Error(`assert_count failed: "${selector}" has ${count} elements, expected ${expected}`);
+      const opMatch = value.match(/^(>=|<=|>|<)\s*(\d+)$/);
+      if (opMatch) {
+        const [, op, numStr] = opMatch;
+        const expected = parseInt(numStr);
+        const passed = op === '>' ? count > expected
+          : op === '>=' ? count >= expected
+          : op === '<' ? count < expected
+          : count <= expected;
+        if (!passed) {
+          throw new Error(`assert_count failed: "${selector}" has ${count} elements, expected ${op}${expected}`);
+        }
+      } else {
+        const expected = parseInt(value);
+        if (count !== expected) {
+          throw new Error(`assert_count failed: "${selector}" has ${count} elements, expected ${expected}`);
+        }
+      }
+      break;
+    }
+
+    case 'assert_element_text': {
+      await page.waitForSelector(selector, { timeout });
+      const elText = await page.$eval(selector, el => el.textContent);
+      if (value === 'exact') {
+        if (elText.trim() !== text) {
+          throw new Error(`assert_element_text failed: "${selector}" text is "${elText.trim()}", expected exact "${text}"`);
+        }
+      } else {
+        if (!elText.includes(text)) {
+          throw new Error(`assert_element_text failed: "${selector}" text "${elText.trim()}" does not contain "${text}"`);
+        }
+      }
+      break;
+    }
+
+    case 'assert_attribute': {
+      await page.waitForSelector(selector, { timeout });
+      const eqIndex = value.indexOf('=');
+      if (eqIndex === -1) {
+        const hasAttr = await page.$eval(selector, (el, attr) => el.hasAttribute(attr), value);
+        if (!hasAttr) {
+          throw new Error(`assert_attribute failed: "${selector}" does not have attribute "${value}"`);
+        }
+      } else {
+        const attrName = value.slice(0, eqIndex);
+        const expectedVal = value.slice(eqIndex + 1);
+        const actual = await page.$eval(selector, (el, attr) => el.getAttribute(attr), attrName);
+        if (actual !== expectedVal) {
+          throw new Error(`assert_attribute failed: "${selector}" attribute "${attrName}" is "${actual}", expected "${expectedVal}"`);
+        }
       }
       break;
     }
 
+    case 'assert_class': {
+      await page.waitForSelector(selector, { timeout });
+      const hasClass = await page.$eval(selector, (el, cls) => el.classList.contains(cls), value);
+      if (!hasClass) {
+        throw new Error(`assert_class failed: "${selector}" does not have class "${value}"`);
+      }
+      break;
+    }
+
+    case 'assert_not_visible': {
+      const notVisEl = await page.$(selector);
+      if (notVisEl) {
+        const isVisible = await page.$eval(selector, (e) => {
+          const style = window.getComputedStyle(e);
+          return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+        });
+        if (isVisible) {
+          throw new Error(`assert_not_visible failed: "${selector}" is visible`);
+        }
+      }
+      break;
+    }
+
+    case 'assert_input_value': {
+      await page.waitForSelector(selector, { timeout });
+      const inputVal = await page.$eval(selector, el => el.value);
+      if (!inputVal.includes(value)) {
+        throw new Error(`assert_input_value failed: "${selector}" value is "${inputVal}", expected to contain "${value}"`);
+      }
+      break;
+    }
+
+    case 'assert_matches': {
+      await page.waitForSelector(selector, { timeout });
+      const matchText = await page.$eval(selector, el => el.textContent);
+      if (!new RegExp(value).test(matchText)) {
+        throw new Error(`assert_matches failed: "${selector}" text "${matchText.trim()}" does not match pattern /${value}/`);
+      }
+      break;
+    }
+
+    case 'get_text': {
+      await page.waitForSelector(selector, { timeout });
+      const getText = await page.$eval(selector, el => el.textContent.trim());
+      return { value: getText };
+    }
+
     case 'select':
       await page.waitForSelector(selector, { timeout });
       await page.select(selector, value);
@@ -162,10 +290,145 @@ export async function executeAction(page, action, config) {
       break;
     }
 
-    case 'evaluate':
-      // Intentional: runs JS in browser page context (from test JSON files)
-      await page.evaluate(value);
+    case 'clear_cookies': {
+      const client = await page.createCDPSession();
+      await client.send('Network.clearBrowserCookies');
+      await client.send('Storage.clearDataForOrigin', {
+        origin: value || baseUrl || page.url(),
+        storageTypes: 'cookies,local_storage,session_storage',
+      });
+      await client.detach();
+      break;
+    }
+
+    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.
+      await page.waitForSelector(selector, { timeout });
+      await page.evaluate((sel, val) => {
+        const input = document.querySelector(sel);
+        if (!input) throw new Error(`type_react: element "${sel}" not found`);
+        const proto = input instanceof HTMLTextAreaElement
+          ? window.HTMLTextAreaElement.prototype
+          : window.HTMLInputElement.prototype;
+        const descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
+        if (!descriptor || !descriptor.set) {
+          throw new Error(`type_react: element "${sel}" has no writable value property`);
+        }
+        descriptor.set.call(input, val);
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+        input.focus();
+      }, selector, value);
+      break;
+    }
+
+    case 'click_regex': {
+      // Click an element whose textContent matches a regex pattern.
+      // text = regex pattern (always case-insensitive)
+      // selector = optional CSS scope (defaults to common clickable elements)
+      // value = "last" to click the last match (default: first)
+      const matchSelector = selector || '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';
+      const matchLast = value === 'last';
+      await page.waitForFunction(
+        (regex, sel) => [...document.querySelectorAll(sel)].some(el => new RegExp(regex, 'i').test(el.textContent)),
+        { timeout },
+        text, matchSelector
+      );
+      const clicked = await page.$$eval(matchSelector, (els, regex, last) => {
+        const matches = els.filter(el => new RegExp(regex, 'i').test(el.textContent));
+        if (matches.length === 0) return false;
+        const target = last ? matches[matches.length - 1] : matches[0];
+        target.click();
+        return true;
+      }, text, matchLast);
+      if (!clicked) {
+        throw new Error(`click_regex failed: no element matching /${text}/i found`);
+      }
+      break;
+    }
+
+    case 'click_option': {
+      // Click a [role="option"] element by text content — common in autocomplete dropdowns.
+      await page.waitForFunction(
+        (t) => [...document.querySelectorAll('[role="option"]')].some(el => el.textContent.includes(t)),
+        { timeout },
+        text
+      );
+      const optionClicked = await page.$$eval('[role="option"]', (els, t) => {
+        const match = els.find(el => el.textContent.includes(t));
+        if (match) { match.click(); return true; }
+        return false;
+      }, text);
+      if (!optionClicked) {
+        throw new Error(`click_option failed: no [role="option"] containing "${text}" found`);
+      }
+      break;
+    }
+
+    case 'focus_autocomplete': {
+      // Focus an autocomplete/combobox input by its label text.
+      // Supports MUI Autocomplete (.MuiAutocomplete-root) and generic [role="combobox"].
+      const focused = await page.evaluate((labelText) => {
+        const containers = [
+          ...document.querySelectorAll('.MuiAutocomplete-root'),
+          ...document.querySelectorAll('[role="combobox"]'),
+        ];
+        const match = containers.find(c => {
+          const label = c.querySelector('label');
+          return label && label.textContent.includes(labelText);
+        });
+        if (!match) return null;
+        const input = match.querySelector('input');
+        if (!input) return null;
+        input.focus();
+        input.click();
+        return input.id || 'focused';
+      }, text);
+      if (!focused) {
+        throw new Error(`focus_autocomplete failed: no autocomplete with label "${text}" found`);
+      }
+      break;
+    }
+
+    case 'click_chip': {
+      // Click a chip/tag element by text content.
+      // Searches MUI Chip classes and common chip patterns.
+      const chipClicked = await page.evaluate((chipText) => {
+        const chips = Array.from(document.querySelectorAll(
+          '[class*="Chip"], [class*="chip"], [data-chip], [role="option"][aria-selected]'
+        ));
+        const match = chips.find(c => c.textContent.includes(chipText));
+        if (!match) return false;
+        match.click();
+        return true;
+      }, text);
+      if (!chipClicked) {
+        throw new Error(`click_chip failed: no chip containing "${text}" found`);
+      }
       break;
+    }
+
+    case 'evaluate': {
+      // Intentional: runs JS in browser page context (from test JSON files)
+      const jsSnippet = value.length > 120 ? value.slice(0, 120) + '...' : value;
+      let evalResult;
+      try {
+        evalResult = await page.evaluate(value);
+      } catch (evalErr) {
+        const pageUrl = page.url();
+        throw new Error(`evaluate threw on ${pageUrl}: ${evalErr.message}\n  JS: ${jsSnippet}`);
+      }
+      if (typeof evalResult === 'string' && /^(FAIL|ERROR|FAILED)[\s:]/i.test(evalResult)) {
+        const pageUrl = page.url();
+        throw new Error(`evaluate failed on ${pageUrl}: ${evalResult}\n  JS: ${jsSnippet}`);
+      }
+      if (evalResult === false) {
+        const pageUrl = page.url();
+        throw new Error(`evaluate returned false on ${pageUrl}\n  JS: ${jsSnippet}`);
+      }
+      return evalResult !== undefined && evalResult !== null ? { value: evalResult } : null;
+    }
 
     default:
       log('⚠️', `Unknown action: ${type}`);

package/src/ai-generate.js

@@ -7,6 +7,7 @@
  */
 
 import fs from 'fs';
+import path from 'path';
 import { listSuites } from './runner.js';
 
 const SYSTEM_PROMPT = `You are an E2E test generator for a JSON-driven browser test runner.
@@ -26,30 +27,118 @@ The test format is:
       { "type": "wait", "text": "Expected text" },
       { "type": "wait", "value": "2000" },
       { "type": "assert_text", "text": "Expected text on page" },
+      { "type": "assert_element_text", "selector": "#title", "text": "Dashboard" },
+      { "type": "assert_element_text", "selector": "#title", "text": "Dashboard", "value": "exact" },
+      { "type": "assert_attribute", "selector": "input#email", "value": "type=email" },
+      { "type": "assert_attribute", "selector": "button", "value": "disabled" },
+      { "type": "assert_class", "selector": ".nav-item", "value": "active" },
+      { "type": "assert_not_visible", "selector": ".error-banner" },
+      { "type": "assert_input_value", "selector": "#email", "value": "user@example.com" },
+      { "type": "assert_matches", "selector": ".phone", "value": "\\\\d{3}-\\\\d{3}-\\\\d{4}" },
       { "type": "assert_url", "value": "/expected-path" },
       { "type": "assert_visible", "selector": ".element" },
       { "type": "assert_count", "selector": ".items", "value": "5" },
+      { "type": "assert_count", "selector": ".rows", "value": ">3" },
+      { "type": "assert_count", "selector": ".errors", "value": "0" },
+      { "type": "get_text", "selector": "#patient-name" },
       { "type": "screenshot", "value": "step-name.png" },
       { "type": "select", "selector": "select#role", "value": "admin" },
       { "type": "clear", "selector": "input" },
       { "type": "press", "value": "Enter" },
       { "type": "scroll", "selector": ".target" },
       { "type": "hover", "selector": ".menu" },
-      { "type": "evaluate", "value": "document.title" }
+      { "type": "evaluate", "value": "document.title" },
+      { "type": "type_react", "selector": "input#search", "value": "search term" },
+      { "type": "click_regex", "text": "submit order", "selector": "button", "value": "last" },
+      { "type": "click_option", "text": "Option Label" },
+      { "type": "focus_autocomplete", "text": "Search by label" },
+      { "type": "click_chip", "text": "Tag Name" }
     ]
   }
 ]
 
+Framework-aware action reference (prefer these over evaluate for React/MUI apps):
+- type_react: types into React controlled inputs using native value setter + input/change events (works with both input and textarea)
+- click_regex: click element by regex text match (case-insensitive). Use "value": "last" for last match. Optional "selector" scopes the search
+- click_option: click a [role="option"] element by text — for autocomplete/select dropdowns
+- focus_autocomplete: focus an autocomplete input by its label text (supports MUI .MuiAutocomplete-root and [role="combobox"])
+- click_chip: click a chip/tag element by text (searches [class*="Chip"], [data-chip])
+
+Assertion action reference:
+- assert_text: checks if text appears anywhere in the page body
+- assert_element_text: checks textContent of a specific element (use "value": "exact" for strict match)
+- assert_attribute: checks HTML attributes — "attr=value" for value check, "attr" alone for existence
+- assert_class: checks if element has a CSS class via classList.contains
+- assert_visible / assert_not_visible: checks element visibility (display, visibility, opacity)
+- assert_input_value: checks the .value of input/select/textarea elements
+- assert_matches: checks element textContent against a regex pattern
+- assert_count: counts matching elements — exact number or operators (">3", ">=1", "<10", "<=5")
+- assert_url: checks if current URL contains the value
+- get_text: extracts element text (non-assertion, returns { value })
+
+Reusable modules:
+- Tests can reference shared action sequences: { "$use": "module-name", "params": { "key": "value" } }
+- Use modules for repeated flows like login, navigation, or setup
+
 Rules:
 - Output a JSON array of test objects
-- Use only the action types listed above
+- NEVER use evaluate with inline JS for assertions that can be done with native action types:
+  * Use assert_element_text instead of evaluate to check element textContent
+  * Use assert_attribute instead of evaluate to check HTML attributes
+  * Use assert_class instead of evaluate to check CSS classes
+  * Use assert_input_value instead of evaluate to check input/select/textarea values
+  * Use assert_matches instead of evaluate for regex text matching
+  * Use assert_not_visible instead of evaluate to verify elements are hidden
+  * Use type_react instead of evaluate with native value setter for React controlled inputs
+  * Use click_regex instead of evaluate with Array.from(querySelectorAll).filter(regex) patterns
+  * Use click_option instead of evaluate with querySelectorAll('[role="option"]') patterns
+  * Use focus_autocomplete instead of evaluate with MuiAutocomplete-root label search patterns
+  * Use click_chip instead of evaluate with querySelectorAll('[class*="Chip"]') patterns
+  * Reserve evaluate ONLY for complex logic that cannot be expressed with existing action types
 - "click" with "text" (no selector) finds buttons/links by visible text
 - "goto" values starting with "/" are relative to the app's base URL
 - Include a screenshot action before key assertions for debugging
 - For bug reports: write tests that assert the CORRECT behavior. If the test fails, the bug is confirmed
 - Keep test names descriptive and kebab-case
 - Prefer CSS selectors that are stable (data-testid, name, role) over fragile ones (nth-child, classes)
-- If the issue description is vague, create a reasonable test that covers the described scenario`;
+- If the issue description is vague, create a reasonable test that covers the described scenario
+- If project context is provided (from CLAUDE.md), use the REAL routes, selectors, and UI patterns described there — never invent routes or selectors`;
+
+const E2E_RULES = `
+CRITICAL — UI-first testing rules:
+- Every test MUST start with a "goto" action to navigate to a real page
+- Tests MUST interact with UI elements: click, type, select, hover, scroll
+- Verify results through visible page state: assert_text, assert_visible, assert_element_text, assert_url
+- NEVER use evaluate to call APIs directly (no fetch, no GraphQL, no XHR, no window.__e2e.gql)
+- NEVER use evaluate to set up or verify data — use the UI workflow instead
+- Test the user journey as a real person would use the application
+- Include screenshot actions before key assertions for debugging
+`;
+
+const API_RULES = `
+API testing rules:
+- Tests verify backend API behavior directly via evaluate actions
+- Each test should: set up context → call API → assert response shape and values
+- Use evaluate for GraphQL mutations, queries, and REST calls
+- Name tests clearly describing the API operation (e.g. "createUser-returns-new-user")
+- Include error case tests (invalid input, missing fields, auth failures)
+- No need for goto/click/type — this is not UI testing
+`;
+
+/**
+ * Reads the project's CLAUDE.md for app context (routes, selectors, UI structure).
+ * Returns the content or empty string if not found.
+ */
+function loadProjectContext(cwd) {
+  if (!cwd) return '';
+  const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+  if (!fs.existsSync(claudeMdPath)) return '';
+  try {
+    return fs.readFileSync(claudeMdPath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
 
 /**
  * Returns a structured prompt + issue data for Claude Code to consume.
@@ -60,13 +149,20 @@ Rules:
  * @param {object} config - Loaded config
  * @returns {object}
  */
-export function buildPrompt(issue, config) {
+export function buildPrompt(issue, config, testType = 'e2e') {
   let existingSuites = [];
   try {
     existingSuites = listSuites(config.testsDir).map(s => s.name);
   } catch { /* no suites yet */ }
 
-  const prompt = `Based on the following issue, generate E2E test actions using the e2e_create_test tool.
+  const projectContext = loadProjectContext(config._cwd);
+  const contextBlock = projectContext
+    ? `\n## Project Context (from CLAUDE.md)\nUse these REAL routes, selectors, and UI patterns — do NOT invent your own.\n\n${projectContext}\n`
+    : '';
+
+  const categoryRules = testType === 'api' ? API_RULES : E2E_RULES;
+
+  const prompt = `Based on the following issue, generate ${testType === 'api' ? 'API' : 'E2E'} test actions using the e2e_create_test tool.
 
 ## Issue: ${issue.title}
 **Repo:** ${issue.repo}
@@ -76,9 +172,11 @@ export function buildPrompt(issue, config) {
 
 ### Description
 ${issue.body || 'No description provided.'}
-
+${contextBlock}
+## Test Category: ${testType}
+${categoryRules}
 ## Instructions
-1. Analyze the issue and determine what user flows to test
+1. Analyze the issue and determine what ${testType === 'api' ? 'API operations' : 'user flows'} to test
 2. Create one or more tests that verify the expected behavior
 3. For bug reports: assert the CORRECT behavior (test failure = bug confirmed)
 4. Use the \`e2e_create_test\` tool with suite name \`issue-${issue.number}\`
@@ -119,7 +217,7 @@ export function hasApiKey(config = {}) {
  * @param {object} config - Loaded config
  * @returns {Promise<{ tests: object[], suiteName: string }>}
  */
-export async function generateTests(issue, config) {
+export async function generateTests(issue, config, testType = 'e2e') {
   const apiKey = config.anthropicApiKey || process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error('ANTHROPIC_API_KEY is required for test generation. Set it as an environment variable or in config.');
@@ -128,7 +226,14 @@ export async function generateTests(issue, config) {
   const model = config.anthropicModel || 'claude-sonnet-4-5-20250929';
   const suiteName = `issue-${issue.number}`;
 
-  const userMessage = `Generate E2E tests for this issue:
+  const projectContext = loadProjectContext(config._cwd);
+  const contextBlock = projectContext
+    ? `\n## Project Context (from CLAUDE.md)\nIMPORTANT: Use these REAL routes, selectors, and UI patterns — do NOT invent your own.\n\n${projectContext}\n`
+    : '';
+
+  const categoryRules = testType === 'api' ? API_RULES : E2E_RULES;
+
+  const userMessage = `Generate ${testType === 'api' ? 'API' : 'E2E'} tests for this issue:
 
 Title: ${issue.title}
 Repo: ${issue.repo}
@@ -137,7 +242,9 @@ State: ${issue.state}
 
 Description:
 ${issue.body || 'No description provided.'}
-
+${contextBlock}
+Test Category: ${testType}
+${categoryRules}
 Base URL: ${config.baseUrl}
 
 Output a JSON array of test objects. Nothing else.`;
@@ -151,7 +258,7 @@ Output a JSON array of test objects. Nothing else.`;
     },
     body: JSON.stringify({
       model,
-      max_tokens: 4096,
+      max_tokens: 16384,
       system: SYSTEM_PROMPT,
       messages: [{ role: 'user', content: userMessage }],
     }),
@@ -168,6 +275,10 @@ Output a JSON array of test objects. Nothing else.`;
     throw new Error('Claude API returned empty response');
   }
 
+  if (result.stop_reason === 'max_tokens') {
+    throw new Error(`Claude API response was truncated (hit max_tokens). The issue may be too complex. Try simplifying the issue description or increasing anthropicMaxTokens.`);
+  }
+
   // Parse JSON — strip markdown fences if present
   const cleaned = text.replace(/^```(?:json)?\s*\n?/m, '').replace(/\n?```\s*$/m, '').trim();
   let tests;

package/src/config.js

@@ -16,6 +16,7 @@ const DEFAULTS = {
   baseUrl: 'http://host.docker.internal:3000',
   poolUrl: 'ws://localhost:3333',
   testsDir: 'e2e/tests',
+  modulesDir: 'e2e/modules',
   screenshotsDir: 'e2e/screenshots',
   concurrency: 3,
   viewport: { width: 1280, height: 720 },
@@ -33,8 +34,23 @@ const DEFAULTS = {
   dashboardPort: 8484,
   maxHistoryRuns: 100,
   projectName: null,
+  exclude: [],
+  failOnNetworkError: false,
+  actionRetries: 0,
+  actionRetryDelay: 500,
   anthropicApiKey: null,
   anthropicModel: 'claude-sonnet-4-5-20250929',
+  authToken: null,
+  authStorageKey: 'accessToken',
+  learningsEnabled: true,
+  learningsMarkdown: true,
+  learningsNeo4j: false,
+  learningsDays: 30,
+  neo4jBoltUrl: 'bolt://localhost:7687',
+  neo4jUser: 'neo4j',
+  neo4jPassword: 'e2erunner',
+  neo4jBoltPort: 7687,
+  neo4jHttpPort: 7474,
 };
 
 function loadEnvVars() {
@@ -42,6 +58,7 @@ function loadEnvVars() {
   if (process.env.BASE_URL) env.baseUrl = process.env.BASE_URL;
   if (process.env.CHROME_POOL_URL) env.poolUrl = process.env.CHROME_POOL_URL;
   if (process.env.TESTS_DIR) env.testsDir = process.env.TESTS_DIR;
+  if (process.env.MODULES_DIR) env.modulesDir = process.env.MODULES_DIR;
   if (process.env.SCREENSHOTS_DIR) env.screenshotsDir = process.env.SCREENSHOTS_DIR;
   if (process.env.CONCURRENCY) env.concurrency = parseInt(process.env.CONCURRENCY);
   if (process.env.DEFAULT_TIMEOUT) env.defaultTimeout = parseInt(process.env.DEFAULT_TIMEOUT);
@@ -53,8 +70,22 @@ function loadEnvVars() {
   if (process.env.OUTPUT_FORMAT) env.outputFormat = process.env.OUTPUT_FORMAT;
   if (process.env.E2E_ENV) env.env = process.env.E2E_ENV;
   if (process.env.PROJECT_NAME) env.projectName = process.env.PROJECT_NAME;
+  if (process.env.FAIL_ON_NETWORK_ERROR) env.failOnNetworkError = process.env.FAIL_ON_NETWORK_ERROR === 'true' || process.env.FAIL_ON_NETWORK_ERROR === '1';
+  if (process.env.ACTION_RETRIES) env.actionRetries = parseInt(process.env.ACTION_RETRIES);
+  if (process.env.ACTION_RETRY_DELAY) env.actionRetryDelay = parseInt(process.env.ACTION_RETRY_DELAY);
   if (process.env.ANTHROPIC_API_KEY) env.anthropicApiKey = process.env.ANTHROPIC_API_KEY;
   if (process.env.ANTHROPIC_MODEL) env.anthropicModel = process.env.ANTHROPIC_MODEL;
+  if (process.env.AUTH_TOKEN) env.authToken = process.env.AUTH_TOKEN;
+  if (process.env.AUTH_STORAGE_KEY) env.authStorageKey = process.env.AUTH_STORAGE_KEY;
+  if (process.env.LEARNINGS_ENABLED) env.learningsEnabled = process.env.LEARNINGS_ENABLED !== 'false' && process.env.LEARNINGS_ENABLED !== '0';
+  if (process.env.LEARNINGS_MARKDOWN) env.learningsMarkdown = process.env.LEARNINGS_MARKDOWN !== 'false' && process.env.LEARNINGS_MARKDOWN !== '0';
+  if (process.env.LEARNINGS_NEO4J) env.learningsNeo4j = process.env.LEARNINGS_NEO4J === 'true' || process.env.LEARNINGS_NEO4J === '1';
+  if (process.env.LEARNINGS_DAYS) env.learningsDays = parseInt(process.env.LEARNINGS_DAYS);
+  if (process.env.NEO4J_BOLT_URL) env.neo4jBoltUrl = process.env.NEO4J_BOLT_URL;
+  if (process.env.NEO4J_USER) env.neo4jUser = process.env.NEO4J_USER;
+  if (process.env.NEO4J_PASSWORD) env.neo4jPassword = process.env.NEO4J_PASSWORD;
+  if (process.env.NEO4J_BOLT_PORT) env.neo4jBoltPort = parseInt(process.env.NEO4J_BOLT_PORT);
+  if (process.env.NEO4J_HTTP_PORT) env.neo4jHttpPort = parseInt(process.env.NEO4J_HTTP_PORT);
   return env;
 }
 
@@ -76,8 +107,32 @@ async function loadConfigFile(cwd) {
   return {};
 }
 
+/** Load .env file from cwd into process.env (no deps, KEY=VALUE format). */
+function loadDotEnv(cwd) {
+  const envPath = path.join(cwd, '.env');
+  if (!fs.existsSync(envPath)) return;
+  const lines = fs.readFileSync(envPath, 'utf-8').split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    let val = trimmed.slice(eqIdx + 1).trim();
+    // Strip surrounding quotes
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    // Don't override existing env vars
+    if (!(key in process.env)) {
+      process.env[key] = val;
+    }
+  }
+}
+
 export async function loadConfig(cliArgs = {}, cwd = null) {
   cwd = cwd || process.cwd();
+  loadDotEnv(cwd);
   const fileConfig = await loadConfigFile(cwd);
   const envConfig = loadEnvVars();
 
@@ -99,6 +154,9 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
   if (!path.isAbsolute(config.testsDir)) {
     config.testsDir = path.join(cwd, config.testsDir);
   }
+  if (config.modulesDir && !path.isAbsolute(config.modulesDir)) {
+    config.modulesDir = path.join(cwd, config.modulesDir);
+  }
   if (!path.isAbsolute(config.screenshotsDir)) {
     config.screenshotsDir = path.join(cwd, config.screenshotsDir);
   }