@matware/e2e-runner 1.1.0 → 1.2.1

package/src/mcp-tools.js

@@ -13,14 +13,19 @@ import path from 'path';
 import http from 'http';
 
 import { loadConfig } from './config.js';
-import { waitForPool, getPoolStatus } from './pool.js';
+import { waitForPool, getPoolStatus, connectToPool } from './pool.js';
 import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from './runner.js';
 import { generateReport, saveReport, persistRun } from './reporter.js';
+import { narrateTest } from './narrate.js';
 import { startDashboard, stopDashboard } from './dashboard.js';
-import { lookupScreenshotHash } from './db.js';
+import { lookupScreenshotHash, ensureProject, computeScreenshotHash, registerScreenshotHash, getNetworkLogs } from './db.js';
 import { fetchIssue, checkCliAuth, detectProvider } from './issues.js';
 import { buildPrompt, hasApiKey } from './ai-generate.js';
 import { verifyIssue } from './verify.js';
+import { listModules } from './module-resolver.js';
+import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestHistory, getPageHistory, getSelectorHistory } from './learner-sqlite.js';
+import { queryGraph } from './learner-neo4j.js';
+import { startNeo4j, stopNeo4j, getNeo4jStatus } from './neo4j-pool.js';
 
 // ── Tool definitions ──────────────────────────────────────────────────────────
 
@@ -56,6 +61,10 @@ export const TOOLS = [
           type: 'number',
           description: 'Number of retries for failed tests',
         },
+        failOnNetworkError: {
+          type: 'boolean',
+          description: 'Fail tests when network requests fail (e.g. ERR_CONNECTION_REFUSED). Default: false.',
+        },
         cwd: {
           type: 'string',
           description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
@@ -80,7 +89,7 @@ export const TOOLS = [
   {
     name: 'e2e_create_test',
     description:
-      'Create a new E2E test JSON file. Provide the suite name and an array of test objects, each with a name and actions array.',
+      'Create a new E2E test JSON file. Provide the suite name and an array of test objects, each with a name and actions array. Actions can include { "$use": "module-name", "params": {...} } to reference reusable modules.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -95,6 +104,7 @@ export const TOOLS = [
             type: 'object',
             properties: {
               name: { type: 'string', description: 'Test name' },
+              expect: { type: 'string', description: 'Human-readable description of the expected visual outcome. After the test runs, a verification screenshot is captured and Claude Code judges pass/fail against this description.' },
               actions: {
                 type: 'array',
                 description: 'Sequential browser actions',
@@ -103,7 +113,7 @@ export const TOOLS = [
                   properties: {
                     type: {
                       type: 'string',
-                      description: 'Action type: goto, click, type, wait, assert_text, assert_url, assert_visible, assert_count, screenshot, select, clear, press, scroll, hover, evaluate, navigate',
+                      description: 'Action type: goto, click, click_regex, click_option, click_chip, type, type_react, focus_autocomplete, wait, assert_text, assert_element_text, assert_attribute, assert_class, assert_visible, assert_not_visible, assert_input_value, assert_matches, assert_url, assert_count, assert_no_network_errors, get_text, screenshot, select, clear, clear_cookies, press, scroll, hover, evaluate, navigate',
                     },
                     selector: { type: 'string', description: 'CSS selector' },
                     value: { type: 'string', description: 'Value for the action' },
@@ -206,6 +216,62 @@ export const TOOLS = [
           description:
             'prompt = return issue + prompt for Claude Code to create tests (default). verify = auto-generate tests via Claude API and run them.',
         },
+        testType: {
+          type: 'string',
+          enum: ['e2e', 'api'],
+          description: "Test category: 'e2e' (default) for UI-driven tests, 'api' for backend API tests",
+        },
+        authToken: {
+          type: 'string',
+          description: 'JWT or auth token to inject into localStorage before running tests (for authenticated apps)',
+        },
+        authStorageKey: {
+          type: 'string',
+          description: 'localStorage key name for the auth token (default: "accessToken")',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'e2e_capture',
+    description:
+      'Capture a screenshot of any URL on demand. Connects to the Chrome pool, navigates to the URL, takes a screenshot, and returns the image with its ss:HASH.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'Full URL to capture (e.g. "https://example.com" or "http://host.docker.internal:3000/dashboard")',
+        },
+        filename: {
+          type: 'string',
+          description: 'Output filename (default: capture-<timestamp>.png)',
+        },
+        fullPage: {
+          type: 'boolean',
+          description: 'Capture full scrollable page (default: false)',
+        },
+        selector: {
+          type: 'string',
+          description: 'Wait for this CSS selector before capturing',
+        },
+        delay: {
+          type: 'number',
+          description: 'Wait N milliseconds after page load before capturing (default: 0)',
+        },
+        authToken: {
+          type: 'string',
+          description: 'JWT or auth token to inject into localStorage before navigating (for authenticated pages)',
+        },
+        authStorageKey: {
+          type: 'string',
+          description: 'localStorage key name for the auth token (default: "accessToken")',
+        },
         cwd: {
           type: 'string',
           description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
@@ -214,6 +280,146 @@ export const TOOLS = [
       required: ['url'],
     },
   },
+  {
+    name: 'e2e_create_module',
+    description:
+      'Create a reusable module for E2E tests. Modules define action sequences that can be referenced from tests via { "$use": "module-name", "params": {...} }. Useful for auth setup, navigation patterns, and other repeated sequences.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Module name (used in $use references, e.g. "auth-jwt", "navigate-patient")',
+        },
+        description: {
+          type: 'string',
+          description: 'Human-readable description of what this module does',
+        },
+        params: {
+          type: 'object',
+          description: 'Parameter definitions. Each key is a param name, value is { required: boolean, default?: string, description?: string }',
+          additionalProperties: {
+            type: 'object',
+            properties: {
+              required: { type: 'boolean' },
+              default: { type: 'string' },
+              description: { type: 'string' },
+            },
+          },
+        },
+        actions: {
+          type: 'array',
+          description: 'Sequential actions with {{param}} placeholders for substitution',
+          items: {
+            type: 'object',
+            properties: {
+              type: { type: 'string', description: 'Action type (goto, click, evaluate, wait, etc.) or omit for $use references' },
+              selector: { type: 'string' },
+              value: { type: 'string' },
+              text: { type: 'string' },
+              $use: { type: 'string', description: 'Reference another module by name' },
+              params: { type: 'object', description: 'Parameters for nested $use' },
+            },
+          },
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory.',
+        },
+      },
+      required: ['name', 'actions'],
+    },
+  },
+  {
+    name: 'e2e_learnings',
+    description:
+      'Query the E2E learning system for insights about test stability, flaky tests, selector health, page health, API health, error patterns, and trends. Builds knowledge across runs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'What to query: "summary" (full overview), "flaky" (flaky tests), "selectors" (selector stability), "pages" (page health), "apis" (API health), "errors" (error patterns), "trends" (7-day trend). Drill-down: "test:<name>", "page:<path>", "selector:<value>".',
+        },
+        days: {
+          type: 'number',
+          description: 'Analysis window in days (default: 30)',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'e2e_neo4j',
+    description:
+      'Manage the Neo4j knowledge graph container for E2E learnings. Requires Docker.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['start', 'stop', 'status'],
+          description: 'Container lifecycle action',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory.',
+        },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'e2e_network_logs',
+    description:
+      'Query network request/response logs for a specific test run. Returns filtered logs from SQLite. Use the runDbId from e2e_run results to drill down into network details on demand.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        runDbId: {
+          type: 'number',
+          description: 'The run database ID (returned by e2e_run in the summary)',
+        },
+        testName: {
+          type: 'string',
+          description: 'Filter by test name',
+        },
+        method: {
+          type: 'string',
+          description: 'Filter by HTTP method (GET, POST, etc.)',
+        },
+        statusMin: {
+          type: 'number',
+          description: 'Minimum HTTP status code (e.g. 400 for errors only)',
+        },
+        statusMax: {
+          type: 'number',
+          description: 'Maximum HTTP status code',
+        },
+        urlPattern: {
+          type: 'string',
+          description: 'Regex pattern to match against request URLs',
+        },
+        errorsOnly: {
+          type: 'boolean',
+          description: 'Only return requests with status >= 400',
+        },
+        includeHeaders: {
+          type: 'boolean',
+          description: 'Include request/response headers (default: false)',
+        },
+        includeBodies: {
+          type: 'boolean',
+          description: 'Include request/response bodies (default: false, implies includeHeaders)',
+        },
+      },
+      required: ['runDbId'],
+    },
+  },
 ];
 
 /** Tools exposed on the dashboard — excludes dashboard start/stop (already running). */
@@ -262,21 +468,23 @@ async function handleRun(args) {
   if (args.concurrency) configOverrides.concurrency = args.concurrency;
   if (args.baseUrl) configOverrides.baseUrl = args.baseUrl;
   if (args.retries !== undefined) configOverrides.retries = args.retries;
+  if (args.failOnNetworkError !== undefined) configOverrides.failOnNetworkError = args.failOnNetworkError;
 
   const config = await loadConfig(configOverrides, args.cwd);
+  config.triggeredBy = 'mcp';
 
   await waitForPool(config.poolUrl);
 
   let tests, hooks;
 
   if (args.all) {
-    ({ tests, hooks } = loadAllSuites(config.testsDir));
+    ({ tests, hooks } = loadAllSuites(config.testsDir, config.modulesDir, config.exclude));
   } else if (args.suite) {
-    ({ tests, hooks } = loadTestSuite(args.suite, config.testsDir));
+    ({ tests, hooks } = loadTestSuite(args.suite, config.testsDir, config.modulesDir));
   } else if (args.file) {
     const cwd = args.cwd || process.cwd();
     const filePath = path.isAbsolute(args.file) ? args.file : path.resolve(cwd, args.file);
-    ({ tests, hooks } = loadTestFile(filePath));
+    ({ tests, hooks } = loadTestFile(filePath, config.modulesDir));
   } else {
     return errorResult('Provide one of: all (true), suite (name), or file (path)');
   }
@@ -298,7 +506,7 @@ async function handleRun(args) {
 
   const report = generateReport(results);
   saveReport(report, config.screenshotsDir, config);
-  persistRun(report, config, args.suite || null);
+  const { runDbId } = persistRun(report, config, args.suite || null);
 
   const failures = report.results
     .filter(r => !r.success)
@@ -316,6 +524,7 @@ async function handleRun(args) {
     ...report.summary,
     reportPath: path.join(config.screenshotsDir, 'report.json'),
   };
+  if (runDbId) summary.runDbId = runDbId;
 
   const consoleErrors = report.results
     .filter(r => r.consoleLogs?.some(l => l.type === 'error' || l.type === 'warning'))
@@ -324,10 +533,93 @@ async function handleRun(args) {
     .filter(r => r.networkErrors?.length > 0)
     .map(r => ({ name: r.name, errors: r.networkErrors }));
 
+  // Compact network summary — full logs available on-demand via e2e_network_logs
+  const networkSummary = report.results
+    .filter(r => r.networkLogs?.length > 0)
+    .map(r => {
+      const logs = r.networkLogs;
+      const statusDist = { '2xx': 0, '3xx': 0, '4xx': 0, '5xx': 0, other: 0 };
+      let totalDuration = 0;
+      for (const l of logs) {
+        const s = l.status;
+        if (s >= 200 && s < 300) statusDist['2xx']++;
+        else if (s >= 300 && s < 400) statusDist['3xx']++;
+        else if (s >= 400 && s < 500) statusDist['4xx']++;
+        else if (s >= 500 && s < 600) statusDist['5xx']++;
+        else statusDist.other++;
+        totalDuration += l.duration || 0;
+      }
+      const failed = logs.filter(l => l.status >= 400).map(l => ({ url: l.url, method: l.method, status: l.status }));
+      const slowest = [...logs].sort((a, b) => (b.duration || 0) - (a.duration || 0)).slice(0, 3).map(l => ({ url: l.url, method: l.method, status: l.status, duration: l.duration }));
+      return {
+        name: r.name,
+        totalRequests: logs.length,
+        statusDistribution: statusDist,
+        avgDurationMs: logs.length > 0 ? Math.round(totalDuration / logs.length) : 0,
+        failedRequests: failed,
+        slowestRequests: slowest,
+      };
+    });
+
+  const verifications = report.results
+    .filter(r => r.expect && r.verificationScreenshot)
+    .map(r => ({
+      name: r.name,
+      expect: r.expect,
+      success: r.success,
+      screenshotHash: 'ss:' + computeScreenshotHash(r.verificationScreenshot),
+    }));
+
   if (flaky.length > 0) summary.flaky = flaky;
   if (failures.length > 0) summary.failures = failures;
   if (consoleErrors.length > 0) summary.consoleErrors = consoleErrors;
-  if (networkErrors.length > 0) summary.networkErrors = networkErrors;
+  if (networkErrors.length > 0) {
+    summary.networkErrors = networkErrors;
+    // Warn when tests pass but have network errors and failOnNetworkError is off
+    if (!config.failOnNetworkError) {
+      const totalNetErrors = networkErrors.reduce((sum, r) => sum + r.errors.length, 0);
+      const passingWithErrors = networkErrors.filter(r => report.results.find(rr => rr.name === r.name)?.success).length;
+      if (passingWithErrors > 0) {
+        summary.networkWarning = `⚠️ ${passingWithErrors} test(s) PASSED but had ${totalNetErrors} network error(s). Set failOnNetworkError: true to fail these tests.`;
+      }
+    }
+  }
+  if (networkSummary.length > 0) {
+    summary.networkSummary = networkSummary;
+    if (runDbId) summary.networkLogsHint = 'Full network logs available via e2e_network_logs tool using the runDbId above.';
+  }
+  if (verifications.length > 0) {
+    summary.verifications = verifications;
+    summary.verificationInstructions = 'For each verification, call e2e_screenshot with the screenshotHash to view the screenshot. Then compare what you see against the "expect" description. Report any mismatches as FAIL.';
+  }
+
+  // Build per-test narrative: a step-by-step human-readable story of what happened
+  const narratives = report.results.map(r => ({
+    name: r.name,
+    status: r.success ? 'PASSED' : 'FAILED',
+    steps: narrateTest(r),
+  }));
+  if (narratives.length > 0) summary.narratives = narratives;
+
+  // Enrich with learning insights (fire-and-forget — never fails the response)
+  if (config.learningsEnabled !== false) {
+    try {
+      const projectId = ensureProject(config._cwd, config.projectName, config.screenshotsDir, config.testsDir);
+      const insights = getRunInsights(projectId, report);
+      if (insights.length > 0) {
+        summary.learnings = {
+          insights,
+          tip: insights.find(i => i.type === 'new-failure')
+            ? 'New test failure detected — this test was previously stable. Check recent code changes.'
+            : insights.find(i => i.type === 'unstable-selectors')
+            ? 'Unstable selectors detected in this run. Consider using more specific selectors or data-testid attributes.'
+            : insights.find(i => i.type === 'flaky')
+            ? 'Known flaky tests in this run. Consider increasing timeouts or adding waits.'
+            : null,
+        };
+      }
+    } catch { /* never fail the run response */ }
+  }
 
   return textResult(JSON.stringify(summary, null, 2));
 }
@@ -336,13 +628,26 @@ async function handleList(args) {
   const config = await loadConfig({}, args.cwd);
   const suites = listSuites(config.testsDir);
 
+  const lines = [];
+
   if (suites.length === 0) {
-    return textResult('No test suites found in ' + config.testsDir);
+    lines.push('No test suites found in ' + config.testsDir);
+  } else {
+    lines.push(...suites.map(s =>
+      `${s.name} (${s.testCount} tests): ${s.tests.join(', ')}`
+    ));
   }
 
-  const lines = suites.map(s =>
-    `${s.name} (${s.testCount} tests): ${s.tests.join(', ')}`
-  );
+  // List available modules
+  const modules = listModules(config.modulesDir);
+  if (modules.length > 0) {
+    lines.push('');
+    lines.push('Available modules:');
+    for (const mod of modules) {
+      const paramNames = mod.params.map(p => p.required ? p.name : `${p.name}?`).join(', ');
+      lines.push(`  ${mod.name} (${paramNames}) — ${mod.description || mod.file}`);
+    }
+  }
 
   return textResult(lines.join('\n'));
 }
@@ -370,7 +675,22 @@ async function handleCreateTest(args) {
   }
 
   fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + '\n');
-  return textResult(`Created test file: ${filePath}\n\n${args.tests.length} test(s) defined.`);
+
+  // Warn about beforeAll pitfall
+  let warning = '';
+  const beforeAll = args.hooks?.beforeAll;
+  if (beforeAll?.length) {
+    const stateActions = beforeAll.filter(a =>
+      ['evaluate', 'goto', 'navigate', 'clear_cookies', 'type', 'click', 'select'].includes(a.type)
+    );
+    if (stateActions.length > 0) {
+      warning = '\n\n⚠️ Warning: beforeAll runs on a separate browser page that is closed before tests start. ' +
+        'Actions that set browser state (evaluate, goto, cookies, etc.) will NOT carry over to individual tests. ' +
+        'Use beforeEach instead if tests need this setup.';
+    }
+  }
+
+  return textResult(`Created test file: ${filePath}\n\n${args.tests.length} test(s) defined.${warning}`);
 }
 
 async function handlePoolStatus(args) {
@@ -409,9 +729,16 @@ async function handleScreenshot(args) {
   const filename = path.basename(row.file_path);
   const hash = row.hash;
 
+  // Build description with metadata if available
+  const metaParts = [`Screenshot ss:${hash} (${filename})`];
+  if (row.test_name) metaParts.push(`Test: ${row.test_name}`);
+  if (row.screenshot_type) metaParts.push(`Type: ${row.screenshot_type}`);
+  if (row.step_index != null) metaParts.push(`Step: ${row.step_index}`);
+  if (row.page_url) metaParts.push(`URL: ${row.page_url}`);
+
   return {
     content: [
-      { type: 'text', text: `Screenshot ss:${hash} (${filename})` },
+      { type: 'text', text: metaParts.join('\n') },
       { type: 'image', data: base64, mimeType },
     ],
   };
@@ -421,6 +748,7 @@ async function handleIssue(args) {
   if (!args.url) return errorResult('Missing required parameter: url');
 
   const mode = args.mode || 'prompt';
+  const testType = args.testType || 'e2e';
   const config = await loadConfig({}, args.cwd);
 
   // Check provider and auth
@@ -441,6 +769,10 @@ async function handleIssue(args) {
       return errorResult('ANTHROPIC_API_KEY is required for verify mode. Set it as an environment variable.');
     }
 
+    if (args.authToken) config.authToken = args.authToken;
+    if (args.authStorageKey) config.authStorageKey = args.authStorageKey;
+    config.testType = testType;
+
     const result = await verifyIssue(args.url, config);
     const status = result.bugConfirmed ? 'BUG CONFIRMED' : 'NOT REPRODUCIBLE';
     const summary = {
@@ -462,11 +794,110 @@ async function handleIssue(args) {
 
   // Default: prompt mode
   const issue = fetchIssue(args.url);
-  const promptData = buildPrompt(issue, config);
+  const promptData = buildPrompt(issue, config, testType);
 
   return textResult(promptData.prompt);
 }
 
+async function handleCreateModule(args) {
+  const config = await loadConfig({}, args.cwd);
+
+  if (!config.modulesDir) {
+    return errorResult('modulesDir not configured');
+  }
+
+  if (!fs.existsSync(config.modulesDir)) {
+    fs.mkdirSync(config.modulesDir, { recursive: true });
+  }
+
+  const safeName = path.basename(args.name);
+  const filename = safeName.endsWith('.json') ? safeName : `${safeName}.json`;
+  const filePath = path.join(config.modulesDir, filename);
+
+  if (fs.existsSync(filePath)) {
+    return errorResult(`Module file already exists: ${filePath}`);
+  }
+
+  const module = {
+    $module: args.name,
+    description: args.description || '',
+    params: args.params || {},
+    actions: args.actions,
+  };
+
+  fs.writeFileSync(filePath, JSON.stringify(module, null, 2) + '\n');
+
+  const paramNames = Object.keys(args.params || {});
+  return textResult(`Created module: ${filePath}\n\nName: ${args.name}\nParams: ${paramNames.length ? paramNames.join(', ') : 'none'}\nActions: ${args.actions.length}\n\nUsage in tests: { "$use": "${args.name}", "params": { ... } }`);
+}
+
+async function handleCapture(args) {
+  if (!args.url) return errorResult('Missing required parameter: url');
+
+  const config = await loadConfig({}, args.cwd);
+
+  await waitForPool(config.poolUrl);
+
+  let browser;
+  try {
+    browser = await connectToPool(config.poolUrl);
+    const page = await browser.newPage();
+    await page.setViewport(config.viewport);
+
+    // Inject auth token into localStorage before navigation
+    const authToken = args.authToken || config.authToken;
+    if (authToken) {
+      const storageKey = args.authStorageKey || config.authStorageKey || 'accessToken';
+      // Navigate to origin first so localStorage is accessible
+      const origin = new URL(args.url).origin;
+      await page.goto(origin, { waitUntil: 'domcontentloaded', timeout: 15000 });
+      await page.evaluate((key, token) => { localStorage.setItem(key, token); }, storageKey, authToken);
+    }
+
+    await page.goto(args.url, { waitUntil: 'networkidle2', timeout: 30000 });
+
+    if (args.selector) {
+      await page.waitForSelector(args.selector, { timeout: 10000 });
+    }
+
+    if (args.delay && args.delay > 0) {
+      await new Promise(r => setTimeout(r, args.delay));
+    }
+
+    // Build filename: sanitize and ensure .png
+    let filename = args.filename || `capture-${Date.now()}.png`;
+    filename = path.basename(filename);
+    if (!filename.endsWith('.png')) filename += '.png';
+
+    if (!fs.existsSync(config.screenshotsDir)) {
+      fs.mkdirSync(config.screenshotsDir, { recursive: true });
+    }
+
+    const screenshotPath = path.join(config.screenshotsDir, filename);
+    await page.screenshot({ path: screenshotPath, fullPage: !!args.fullPage });
+
+    // Register hash in SQLite
+    const cwd = args.cwd || process.cwd();
+    const projectName = config.projectName || path.basename(cwd);
+    const projectId = ensureProject(cwd, projectName, config.screenshotsDir, config.testsDir);
+    const hash = computeScreenshotHash(screenshotPath);
+    registerScreenshotHash(hash, screenshotPath, projectId, null);
+
+    // Read image for response
+    const data = fs.readFileSync(screenshotPath);
+    const base64 = data.toString('base64');
+
+    return {
+      content: [
+        { type: 'text', text: `Screenshot saved: ${screenshotPath}\nHash: ss:${hash}` },
+        { type: 'image', data: base64, mimeType: 'image/png' },
+      ],
+    };
+  } finally {
+    if (browser) browser.disconnect();
+  }
+}
+
 // Module-level state for stdio path only
 let dashboardHandle = null;
 
@@ -490,6 +921,124 @@ async function handleDashboardStop() {
   return textResult('Dashboard stopped');
 }
 
+async function handleNeo4j(args) {
+  if (!args.action) return errorResult('Missing required parameter: action');
+
+  const config = await loadConfig({}, args.cwd);
+
+  switch (args.action) {
+    case 'start':
+      try {
+        startNeo4j(config, args.cwd);
+        return textResult(`Neo4j started. Bolt: bolt://localhost:${config.neo4jBoltPort || 7687}, Browser: http://localhost:${config.neo4jHttpPort || 7474}`);
+      } catch (err) {
+        return errorResult(`Failed to start Neo4j: ${err.message}`);
+      }
+    case 'stop':
+      try {
+        stopNeo4j(config, args.cwd);
+        return textResult('Neo4j stopped');
+      } catch (err) {
+        return errorResult(`Failed to stop Neo4j: ${err.message}`);
+      }
+    case 'status': {
+      const status = getNeo4jStatus(config, args.cwd);
+      const lines = [
+        `Running: ${status.running ? 'yes' : 'no'}`,
+      ];
+      if (status.running) {
+        lines.push(`Bolt: bolt://localhost:${status.boltPort}`);
+        lines.push(`Browser: http://localhost:${status.httpPort}`);
+      }
+      if (status.error) lines.push(`Error: ${status.error}`);
+      return textResult(lines.join('\n'));
+    }
+    default:
+      return errorResult('Unknown action. Use: start, stop, status');
+  }
+}
+
+async function handleLearnings(args) {
+  if (!args.query) return errorResult('Missing required parameter: query');
+
+  const config = await loadConfig({}, args.cwd);
+  const days = Math.min(Math.max(parseInt(args.days || config.learningsDays || 30, 10) || 30, 1), 365);
+  const projectId = ensureProject(config._cwd, config.projectName, config.screenshotsDir, config.testsDir);
+
+  const query = args.query.trim().toLowerCase();
+
+  // Drill-down queries (enriched with graph data when Neo4j is available)
+  if (query.startsWith('test:')) {
+    const testName = args.query.slice(5).trim();
+    const history = getTestHistory(projectId, testName, days);
+    const result = { query: args.query, testName, history };
+    const graphDeps = await queryGraph(config, 'test-dependencies', { testName }).catch(() => null);
+    if (graphDeps) result.relatedTests = graphDeps;
+    return textResult(JSON.stringify(result, null, 2));
+  }
+  if (query.startsWith('page:')) {
+    const urlPath = args.query.slice(5).trim();
+    const history = getPageHistory(projectId, urlPath, days);
+    const result = { query: args.query, urlPath, history };
+    const graphImpact = await queryGraph(config, 'page-impact', { path: urlPath }).catch(() => null);
+    if (graphImpact) result.affectedTests = graphImpact;
+    return textResult(JSON.stringify(result, null, 2));
+  }
+  if (query.startsWith('selector:')) {
+    const selector = args.query.slice(9).trim();
+    const history = getSelectorHistory(projectId, selector, days);
+    const result = { query: args.query, selector, history };
+    const graphUsage = await queryGraph(config, 'selector-usage', { selector }).catch(() => null);
+    if (graphUsage) result.usage = graphUsage;
+    return textResult(JSON.stringify(result, null, 2));
+  }
+
+  // Category queries
+  switch (query) {
+    case 'summary': {
+      const summary = getLearningsSummary(projectId);
+      const trendsResult = getTestTrends(projectId, 7);
+      return textResult(JSON.stringify({ ...summary, recentTrend: trendsResult }, null, 2));
+    }
+    case 'flaky':
+      return textResult(JSON.stringify(getFlakySummary(projectId, days), null, 2));
+    case 'selectors':
+      return textResult(JSON.stringify(getSelectorStability(projectId, days), null, 2));
+    case 'pages':
+      return textResult(JSON.stringify(getPageHealth(projectId, days), null, 2));
+    case 'apis':
+      return textResult(JSON.stringify(getApiHealth(projectId, days), null, 2));
+    case 'errors':
+      return textResult(JSON.stringify(getErrorPatterns(projectId), null, 2));
+    case 'trends':
+      return textResult(JSON.stringify(getTestTrends(projectId, days), null, 2));
+    default:
+      return errorResult(`Unknown query: "${args.query}". Use: summary, flaky, selectors, pages, apis, errors, trends, test:<name>, page:<path>, selector:<value>`);
+  }
+}
+
+async function handleNetworkLogs(args) {
+  if (!args.runDbId) return errorResult('Missing required parameter: runDbId');
+
+  const filters = {};
+  if (args.testName) filters.testName = args.testName;
+  if (args.method) filters.method = args.method;
+  if (args.statusMin !== undefined) filters.statusMin = args.statusMin;
+  if (args.statusMax !== undefined) filters.statusMax = args.statusMax;
+  if (args.urlPattern) filters.urlPattern = args.urlPattern;
+  if (args.errorsOnly) filters.errorsOnly = true;
+  if (args.includeHeaders) filters.includeHeaders = true;
+  if (args.includeBodies) filters.includeBodies = true;
+
+  const results = getNetworkLogs(args.runDbId, filters);
+
+  if (results.length === 0) {
+    return textResult('No network logs found for the given filters.');
+  }
+
+  return textResult(JSON.stringify(results, null, 2));
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 export function textResult(text) {
@@ -521,6 +1070,16 @@ export async function dispatchTool(name, args = {}) {
       return await handleDashboardStop();
     case 'e2e_issue':
       return await handleIssue(args);
+    case 'e2e_create_module':
+      return await handleCreateModule(args);
+    case 'e2e_capture':
+      return await handleCapture(args);
+    case 'e2e_learnings':
+      return await handleLearnings(args);
+    case 'e2e_neo4j':
+      return await handleNeo4j(args);
+    case 'e2e_network_logs':
+      return await handleNetworkLogs(args);
     default:
       return errorResult(`Unknown tool: ${name}`);
   }