@matware/e2e-runner 1.1.1 → 1.3.0

package/src/db.js

@@ -107,6 +107,13 @@ function migrate(db) {
     db.exec('ALTER TABLE test_results ADD COLUMN network_logs TEXT');
   }
 
+  // Add actions_json column if upgrading from older schema
+  try {
+    db.prepare('SELECT actions_json FROM test_results LIMIT 0').run();
+  } catch {
+    db.exec('ALTER TABLE test_results ADD COLUMN actions_json TEXT');
+  }
+
   // Add triggered_by column if upgrading from older schema
   try {
     db.prepare('SELECT triggered_by FROM runs LIMIT 0').run();
@@ -125,6 +132,137 @@ function migrate(db) {
     );
     CREATE INDEX IF NOT EXISTS idx_ss_path ON screenshot_hashes(file_path);
   `);
+
+  // ── Learning system tables ──────────────────────────────────────────────────
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS test_learnings (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id    INTEGER NOT NULL REFERENCES projects(id),
+      run_id        INTEGER REFERENCES runs(id) ON DELETE CASCADE,
+      test_name     TEXT NOT NULL,
+      success       INTEGER NOT NULL,
+      duration_ms   INTEGER,
+      flaky         INTEGER DEFAULT 0,
+      attempt       INTEGER DEFAULT 1,
+      max_attempts  INTEGER DEFAULT 1,
+      error_pattern TEXT,
+      created_at    TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_tl_project ON test_learnings(project_id);
+    CREATE INDEX IF NOT EXISTS idx_tl_test    ON test_learnings(test_name);
+    CREATE INDEX IF NOT EXISTS idx_tl_created ON test_learnings(created_at);
+
+    CREATE TABLE IF NOT EXISTS selector_learnings (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id    INTEGER NOT NULL REFERENCES projects(id),
+      run_id        INTEGER REFERENCES runs(id) ON DELETE CASCADE,
+      selector      TEXT NOT NULL,
+      action_type   TEXT NOT NULL,
+      success       INTEGER NOT NULL,
+      page_url      TEXT,
+      test_name     TEXT,
+      error         TEXT,
+      created_at    TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_sl_project  ON selector_learnings(project_id);
+    CREATE INDEX IF NOT EXISTS idx_sl_selector ON selector_learnings(selector);
+
+    CREATE TABLE IF NOT EXISTS page_learnings (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id      INTEGER NOT NULL REFERENCES projects(id),
+      run_id          INTEGER REFERENCES runs(id) ON DELETE CASCADE,
+      url_path        TEXT NOT NULL,
+      load_time_ms    INTEGER,
+      console_errors  INTEGER DEFAULT 0,
+      console_warns   INTEGER DEFAULT 0,
+      network_errors  INTEGER DEFAULT 0,
+      test_name       TEXT,
+      success         INTEGER NOT NULL,
+      created_at      TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_pl_project ON page_learnings(project_id);
+    CREATE INDEX IF NOT EXISTS idx_pl_url     ON page_learnings(url_path);
+
+    CREATE TABLE IF NOT EXISTS api_learnings (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id    INTEGER NOT NULL REFERENCES projects(id),
+      run_id        INTEGER REFERENCES runs(id) ON DELETE CASCADE,
+      endpoint      TEXT NOT NULL,
+      method        TEXT NOT NULL,
+      status        INTEGER,
+      duration_ms   INTEGER,
+      is_error      INTEGER DEFAULT 0,
+      test_name     TEXT,
+      created_at    TEXT DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_al_project  ON api_learnings(project_id);
+    CREATE INDEX IF NOT EXISTS idx_al_endpoint ON api_learnings(endpoint);
+
+    CREATE TABLE IF NOT EXISTS error_patterns (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id      INTEGER NOT NULL REFERENCES projects(id),
+      pattern         TEXT NOT NULL,
+      category        TEXT NOT NULL,
+      occurrence_count INTEGER DEFAULT 1,
+      first_seen      TEXT DEFAULT (datetime('now')),
+      last_seen       TEXT DEFAULT (datetime('now')),
+      example_error   TEXT,
+      example_test    TEXT,
+      UNIQUE(project_id, pattern)
+    );
+    CREATE INDEX IF NOT EXISTS idx_ep_project ON error_patterns(project_id);
+    CREATE INDEX IF NOT EXISTS idx_ep_cat     ON error_patterns(category);
+
+    CREATE TABLE IF NOT EXISTS learning_summary (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id      INTEGER NOT NULL UNIQUE REFERENCES projects(id),
+      total_runs      INTEGER DEFAULT 0,
+      total_tests     INTEGER DEFAULT 0,
+      overall_pass_rate REAL DEFAULT 0,
+      avg_duration_ms REAL DEFAULT 0,
+      flaky_tests     TEXT,
+      slow_tests      TEXT,
+      unstable_selectors TEXT,
+      failing_pages   TEXT,
+      api_issues      TEXT,
+      top_errors      TEXT,
+      updated_at      TEXT DEFAULT (datetime('now'))
+    );
+  `);
+
+  // ── Variables table ──────────────────────────────────────────────────────────
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS variables (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER NOT NULL REFERENCES projects(id),
+      scope      TEXT NOT NULL DEFAULT 'project',
+      key        TEXT NOT NULL,
+      value      TEXT NOT NULL,
+      created_at TEXT DEFAULT (datetime('now')),
+      updated_at TEXT DEFAULT (datetime('now')),
+      UNIQUE(project_id, scope, key)
+    );
+    CREATE INDEX IF NOT EXISTS idx_vars_project ON variables(project_id);
+    CREATE INDEX IF NOT EXISTS idx_vars_scope   ON variables(project_id, scope);
+  `);
+
+  // Add pool_url column for multi-pool tracking
+  try {
+    db.prepare('SELECT pool_url FROM test_results LIMIT 0').run();
+  } catch {
+    db.exec('ALTER TABLE test_results ADD COLUMN pool_url TEXT');
+  }
+
+  // Migrations: add metadata columns to screenshot_hashes
+  const ssColumns = db.pragma('table_info(screenshot_hashes)').map(c => c.name);
+  if (!ssColumns.includes('test_name')) {
+    db.exec('ALTER TABLE screenshot_hashes ADD COLUMN test_name TEXT');
+    db.exec('ALTER TABLE screenshot_hashes ADD COLUMN step_index INTEGER');
+    db.exec('ALTER TABLE screenshot_hashes ADD COLUMN page_url TEXT');
+    db.exec('ALTER TABLE screenshot_hashes ADD COLUMN screenshot_type TEXT');
+  }
 }
 
 /** Upsert a project row. Returns the project id. */
@@ -169,17 +307,19 @@ export function computeScreenshotHash(filePath) {
   return crypto.createHash('sha256').update(filePath).digest('hex').slice(0, 8);
 }
 
-/** Register a screenshot hash. INSERT OR IGNORE avoids duplicates. */
-export function registerScreenshotHash(hash, filePath, projectId, runDbId) {
+/** Register a screenshot hash. INSERT OR IGNORE avoids duplicates. Optional metadata: testName, stepIndex, pageUrl, screenshotType. */
+export function registerScreenshotHash(hash, filePath, projectId, runDbId, meta = {}) {
   const d = getDb();
-  d.prepare('INSERT OR IGNORE INTO screenshot_hashes (hash, file_path, project_id, run_id) VALUES (?, ?, ?, ?)').run(hash, filePath, projectId || null, runDbId || null);
+  d.prepare(
+    'INSERT OR IGNORE INTO screenshot_hashes (hash, file_path, project_id, run_id, test_name, step_index, page_url, screenshot_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?)'
+  ).run(hash, filePath, projectId || null, runDbId || null, meta.testName || null, meta.stepIndex ?? null, meta.pageUrl || null, meta.screenshotType || null);
 }
 
-/** Look up a screenshot by hash. Strips optional "ss:" prefix. Returns { hash, file_path, project_id } or null. */
+/** Look up a screenshot by hash. Strips optional "ss:" prefix. Returns { hash, file_path, project_id, test_name, step_index, page_url, screenshot_type } or null. */
 export function lookupScreenshotHash(rawHash) {
   const d = getDb();
   const hash = rawHash.replace(/^ss:/, '');
-  return d.prepare('SELECT hash, file_path, project_id FROM screenshot_hashes WHERE hash = ?').get(hash) || null;
+  return d.prepare('SELECT hash, file_path, project_id, test_name, step_index, page_url, screenshot_type FROM screenshot_hashes WHERE hash = ?').get(hash) || null;
 }
 
 /** Batch lookup: given an array of file paths, returns { [path]: hash } map. */
@@ -206,11 +346,11 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
   `);
 
   const insertTest = d.prepare(`
-    INSERT INTO test_results (run_id, name, success, error, start_time, end_time, duration_ms, attempt, max_attempts, error_screenshot, console_logs, network_errors, screenshots, network_logs)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO test_results (run_id, name, success, error, start_time, end_time, duration_ms, attempt, max_attempts, error_screenshot, console_logs, network_errors, screenshots, network_logs, actions_json, pool_url)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
 
-  const insertHash = d.prepare('INSERT OR IGNORE INTO screenshot_hashes (hash, file_path, project_id, run_id) VALUES (?, ?, ?, ?)');
+  const insertHash = d.prepare('INSERT OR IGNORE INTO screenshot_hashes (hash, file_path, project_id, run_id, test_name, step_index, page_url, screenshot_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?)');
 
   const tx = d.transaction(() => {
     const runInfo = insertRun.run(
@@ -237,6 +377,19 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
         .filter(a => a.type === 'screenshot' && a.result?.screenshot)
         .map(a => a.result.screenshot);
 
+      // Condensed actions for narrative display
+      const actionsCondensed = (r.actions || []).map(a => ({
+        type: a.type,
+        selector: a.selector || undefined,
+        value: a.value || undefined,
+        text: a.text || undefined,
+        success: a.success,
+        duration: a.duration,
+        narrative: a.narrative || undefined,
+        error: a.error || undefined,
+        actionRetries: a.actionRetries || undefined,
+      }));
+
       insertTest.run(
         runDbId,
         r.name,
@@ -252,17 +405,25 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
         r.networkErrors ? JSON.stringify(r.networkErrors) : null,
         screenshots.length ? JSON.stringify(screenshots) : null,
         r.networkLogs?.length ? JSON.stringify(r.networkLogs) : null,
+        actionsCondensed.length ? JSON.stringify(actionsCondensed) : null,
+        r.poolUrl || null,
       );
 
-      // Register screenshot hashes
-      for (const ssPath of screenshots) {
-        insertHash.run(computeScreenshotHash(ssPath), ssPath, projectId, runDbId);
+      // Register screenshot hashes with metadata
+      const ssActions = (r.actions || []).filter(a => a.type === 'screenshot' && a.result?.screenshot);
+      for (let si = 0; si < ssActions.length; si++) {
+        const a = ssActions[si];
+        const actionIdx = r.actions.indexOf(a);
+        insertHash.run(computeScreenshotHash(a.result.screenshot), a.result.screenshot, projectId, runDbId, r.name, actionIdx, null, 'action');
       }
       if (r.errorScreenshot) {
-        insertHash.run(computeScreenshotHash(r.errorScreenshot), r.errorScreenshot, projectId, runDbId);
+        insertHash.run(computeScreenshotHash(r.errorScreenshot), r.errorScreenshot, projectId, runDbId, r.name, null, null, 'error');
       }
       if (r.verificationScreenshot) {
-        insertHash.run(computeScreenshotHash(r.verificationScreenshot), r.verificationScreenshot, projectId, runDbId);
+        insertHash.run(computeScreenshotHash(r.verificationScreenshot), r.verificationScreenshot, projectId, runDbId, r.name, null, null, 'verification');
+      }
+      if (r.baselineScreenshot) {
+        insertHash.run(computeScreenshotHash(r.baselineScreenshot), r.baselineScreenshot, projectId, runDbId, r.name, null, null, 'baseline');
       }
     }
 
@@ -272,6 +433,33 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy) {
   return tx();
 }
 
+/** Save a run from sync (remote instance). Returns the run's DB id. */
+export function persistRunFromSync({ projectId, runId, total, passed, failed, passRate, duration, generatedAt, suiteName, triggeredBy, syncInstanceId, syncOrigin }) {
+  const d = getDb();
+  
+  const stmt = d.prepare(`
+    INSERT INTO runs (project_id, run_id, total, passed, failed, pass_rate, duration, generated_at, suite_name, triggered_by, sync_instance_id, sync_origin, synced_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+  `);
+  
+  const result = stmt.run(
+    projectId,
+    runId,
+    total,
+    passed,
+    failed,
+    passRate,
+    duration,
+    generatedAt,
+    suiteName || null,
+    triggeredBy || null,
+    syncInstanceId || null,
+    syncOrigin || 'remote'
+  );
+  
+  return result.lastInsertRowid;
+}
+
 /** List all projects with aggregated stats. */
 export function listProjects() {
   const d = getDb();
@@ -352,7 +540,9 @@ export function getRunDetail(runDbId) {
         consoleLogs: t.console_logs ? JSON.parse(t.console_logs) : [],
         networkErrors: t.network_errors ? JSON.parse(t.network_errors) : [],
         networkLogs: t.network_logs ? JSON.parse(t.network_logs) : [],
+        actions: t.actions_json ? JSON.parse(t.actions_json) : [],
         screenshotHashes,
+        poolUrl: t.pool_url || null,
       };
     }),
   };
@@ -378,7 +568,139 @@ export function getRunCount() {
   return row.cnt;
 }
 
+/** Query network logs for a run with optional filters.
+ * Filters: testName, method, statusMin, statusMax, urlPattern, errorsOnly, includeHeaders, includeBodies.
+ * By default returns only: url, method, status, statusText, duration.
+ */
+export function getNetworkLogs(runDbId, filters = {}) {
+  const d = getDb();
+
+  let query = 'SELECT name, network_logs FROM test_results WHERE run_id = ?';
+  const params = [runDbId];
+
+  if (filters.testName) {
+    query += ' AND name = ?';
+    params.push(filters.testName);
+  }
+
+  const rows = d.prepare(query).all(...params);
+  const results = [];
+
+  for (const row of rows) {
+    if (!row.network_logs) continue;
+    let logs = JSON.parse(row.network_logs);
+
+    if (filters.method) {
+      logs = logs.filter(l => l.method === filters.method.toUpperCase());
+    }
+    if (filters.statusMin !== undefined) {
+      logs = logs.filter(l => l.status >= filters.statusMin);
+    }
+    if (filters.statusMax !== undefined) {
+      logs = logs.filter(l => l.status <= filters.statusMax);
+    }
+    if (filters.urlPattern) {
+      const re = new RegExp(filters.urlPattern, 'i');
+      logs = logs.filter(l => re.test(l.url));
+    }
+    if (filters.errorsOnly) {
+      logs = logs.filter(l => l.status >= 400);
+    }
+
+    const mapped = logs.map(l => {
+      const entry = { url: l.url, method: l.method, status: l.status, statusText: l.statusText, duration: l.duration };
+      if (filters.includeHeaders || filters.includeBodies) {
+        entry.requestHeaders = l.requestHeaders;
+        entry.responseHeaders = l.responseHeaders;
+      }
+      if (filters.includeBodies) {
+        entry.requestBody = l.requestBody;
+        entry.responseBody = l.responseBody;
+      }
+      return entry;
+    });
+
+    if (mapped.length > 0) {
+      results.push({ testName: row.name, logs: mapped });
+    }
+  }
+
+  return results;
+}
+
+// ── Variables CRUD ────────────────────────────────────────────────────────────
+
+/** Upsert a variable. Scope is 'project' or a suite name. */
+export function setVariable(projectId, scope, key, value) {
+  const d = getDb();
+  d.prepare(`
+    INSERT INTO variables (project_id, scope, key, value, updated_at)
+    VALUES (?, ?, ?, ?, datetime('now'))
+    ON CONFLICT(project_id, scope, key)
+    DO UPDATE SET value = excluded.value, updated_at = datetime('now')
+  `).run(projectId, scope, key, value);
+}
+
+/** Get variables for a specific scope. Returns { key: value } map. */
+export function getVariables(projectId, scope) {
+  const d = getDb();
+  const rows = d.prepare('SELECT key, value FROM variables WHERE project_id = ? AND scope = ?').all(projectId, scope);
+  const map = {};
+  for (const r of rows) map[r.key] = r.value;
+  return map;
+}
+
+/** Delete a variable. Returns true if deleted. */
+export function deleteVariable(projectId, scope, key) {
+  const d = getDb();
+  const info = d.prepare('DELETE FROM variables WHERE project_id = ? AND scope = ? AND key = ?').run(projectId, scope, key);
+  return info.changes > 0;
+}
+
+/** List all variables for a project, grouped by scope. Returns { scope: { key: value } }. */
+export function listVariables(projectId) {
+  const d = getDb();
+  const rows = d.prepare('SELECT scope, key, value FROM variables WHERE project_id = ? ORDER BY scope, key').all(projectId);
+  const grouped = {};
+  for (const r of rows) {
+    if (!grouped[r.scope]) grouped[r.scope] = {};
+    grouped[r.scope][r.key] = r.value;
+  }
+  return grouped;
+}
+
 /** Close the database connection. */
+/** Projects with sparkline data (last N run pass rates, oldest→newest). */
+export function listProjectsWithSparklines(sparklineSize = 20) {
+  const d = getDb();
+  const projects = d.prepare(`
+    SELECT
+      p.id, p.cwd, p.name, p.screenshots_dir, p.tests_dir, p.created_at, p.updated_at,
+      COUNT(r.id)          AS runCount,
+      MAX(r.generated_at)  AS lastRunAt,
+      (SELECT r2.pass_rate FROM runs r2 WHERE r2.project_id = p.id ORDER BY r2.generated_at DESC LIMIT 1) AS lastPassRate
+    FROM projects p
+    LEFT JOIN runs r ON r.project_id = p.id
+    GROUP BY p.id
+    ORDER BY p.updated_at DESC
+  `).all();
+
+  const sparkStmt = d.prepare(`
+    SELECT CAST(pass_rate AS REAL) AS rate
+    FROM runs
+    WHERE project_id = ?
+    ORDER BY generated_at DESC
+    LIMIT ?
+  `);
+
+  return projects.map(p => {
+    const rawRates = sparkStmt.all(p.id, sparklineSize).map(r => r.rate);
+    // Reverse to oldest→newest
+    rawRates.reverse();
+    return { ...p, sparkline: rawRates };
+  });
+}
+
 export function closeDb() {
   if (db) {
     db.close();

package/src/index.js

@@ -9,6 +9,7 @@
 
 export { loadConfig } from './config.js';
 export { waitForPool, connectToPool, startPool, stopPool, restartPool, getPoolStatus } from './pool.js';
+export { getPoolUrls, getAllPoolStatuses, getAggregatedPoolStatus, waitForAnyPool, selectPool, selectAndConnect } from './pool-manager.js';
 export { executeAction } from './actions.js';
 export { runTest, runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from './runner.js';
 export { generateReport, generateJUnitXML, saveReport, printReport, saveHistory, loadHistory, loadHistoryRun } from './reporter.js';
@@ -16,9 +17,15 @@ export { startDashboard, stopDashboard } from './dashboard.js';
 export { fetchIssue, parseIssueUrl, detectProvider, checkCliAuth } from './issues.js';
 export { buildPrompt, generateTests, hasApiKey } from './ai-generate.js';
 export { verifyIssue } from './verify.js';
+export { resolveTestData, loadModuleRegistry, listModules } from './module-resolver.js';
+export { learnFromRun, categorizeError } from './learner.js';
+export { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestCreationContext, generateImprovements } from './learner-sqlite.js';
+export { generateLearningsMarkdown } from './learner-markdown.js';
+export { writeToGraph, queryGraph, closeNeo4j } from './learner-neo4j.js';
+export { startNeo4j, stopNeo4j, getNeo4jStatus } from './neo4j-pool.js';
 
 import { loadConfig } from './config.js';
-import { waitForPool } from './pool.js';
+import { waitForAnyPool, getPoolUrls } from './pool-manager.js';
 import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites } from './runner.js';
 import { generateReport, saveReport, printReport } from './reporter.js';
 
@@ -35,8 +42,8 @@ export async function createRunner(userConfig = {}) {
 
     /** Runs all test suites from the tests directory */
     async runAll() {
-      await waitForPool(config.poolUrl);
-      const { tests, hooks } = loadAllSuites(config.testsDir);
+      await waitForAnyPool(getPoolUrls(config));
+      const { tests, hooks } = loadAllSuites(config.testsDir, config.modulesDir, config.exclude);
       const results = await runTestsParallel(tests, config, hooks);
       const report = generateReport(results);
       saveReport(report, config.screenshotsDir, config);
@@ -46,8 +53,8 @@ export async function createRunner(userConfig = {}) {
 
     /** Runs a single suite by name */
     async runSuite(name) {
-      await waitForPool(config.poolUrl);
-      const { tests, hooks } = loadTestSuite(name, config.testsDir);
+      await waitForAnyPool(getPoolUrls(config));
+      const { tests, hooks } = loadTestSuite(name, config.testsDir, config.modulesDir);
       const results = await runTestsParallel(tests, config, hooks);
       const report = generateReport(results);
       saveReport(report, config.screenshotsDir, config);
@@ -57,7 +64,7 @@ export async function createRunner(userConfig = {}) {
 
     /** Runs an array of test objects */
     async runTests(tests) {
-      await waitForPool(config.poolUrl);
+      await waitForAnyPool(getPoolUrls(config));
       const results = await runTestsParallel(tests, config);
       const report = generateReport(results);
       saveReport(report, config.screenshotsDir, config);
@@ -67,8 +74,8 @@ export async function createRunner(userConfig = {}) {
 
     /** Runs tests from a JSON file path */
     async runFile(filePath) {
-      await waitForPool(config.poolUrl);
-      const { tests, hooks } = loadTestFile(filePath);
+      await waitForAnyPool(getPoolUrls(config));
+      const { tests, hooks } = loadTestFile(filePath, config.modulesDir);
       const results = await runTestsParallel(tests, config, hooks);
       const report = generateReport(results);
       saveReport(report, config.screenshotsDir, config);

package/src/learner-markdown.js

@@ -0,0 +1,177 @@
+/**
+ * Learnings markdown generator.
+ *
+ * Generates {cwd}/e2e/learnings.md after each run, reading from SQLite.
+ * The file is designed to be portable, versionable in git, and human-readable.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {
+  getLearningsSummary,
+  getFlakySummary,
+  getSelectorStability,
+  getPageHealth,
+  getApiHealth,
+  getErrorPatterns,
+  getTestTrends,
+} from './learner-sqlite.js';
+
+/**
+ * Generates the learnings.md file for a project.
+ * Reads from SQLite and writes to {cwd}/e2e/learnings.md.
+ */
+export function generateLearningsMarkdown(projectId, config) {
+  const days = config?.learningsDays || 30;
+  const summary = getLearningsSummary(projectId);
+  const flaky = getFlakySummary(projectId, days);
+  const selectors = getSelectorStability(projectId, days);
+  const pages = getPageHealth(projectId, days);
+  const apis = getApiHealth(projectId, days);
+  const errors = getErrorPatterns(projectId);
+  const trendsResult = getTestTrends(projectId, 7);
+  const trends = trendsResult.data || trendsResult;
+  const trendsGranularity = trendsResult.granularity || 'daily';
+
+  const lines = [];
+
+  lines.push('# E2E Test Learnings');
+  lines.push('');
+  lines.push(`> Auto-generated after each test run. Analysis window: **${days} days**.`);
+  lines.push(`> Last updated: ${summary.updatedAt || 'never'}`);
+  lines.push('');
+
+  // ── Health Overview ─────────────────────────────────────────────────────────
+  lines.push('## Health Overview');
+  lines.push('');
+  lines.push('| Metric | Value |');
+  lines.push('|--------|-------|');
+  lines.push(`| Total Runs | ${summary.totalRuns} |`);
+  lines.push(`| Total Tests | ${summary.totalTests} |`);
+  lines.push(`| Pass Rate | ${summary.overallPassRate}% |`);
+  lines.push(`| Avg Duration | ${formatDuration(summary.avgDurationMs)} |`);
+  lines.push(`| Flaky Tests | ${flaky.length} |`);
+  lines.push(`| Unstable Selectors | ${selectors.length} |`);
+
+  // Trend arrow (compare last 2 days)
+  if (trends.length >= 2) {
+    const latest = trends[trends.length - 1];
+    const prev = trends[trends.length - 2];
+    const diff = latest.pass_rate - prev.pass_rate;
+    const arrow = diff > 0 ? 'improving' : diff < 0 ? 'declining' : 'stable';
+    lines.push(`| 7-Day Trend | ${arrow} (${diff > 0 ? '+' : ''}${diff.toFixed(1)}%) |`);
+  }
+  lines.push('');
+
+  // ── Flaky Tests ─────────────────────────────────────────────────────────────
+  if (flaky.length > 0) {
+    lines.push('## Flaky Tests');
+    lines.push('');
+    lines.push('Tests that pass only after retries — potential stability issues.');
+    lines.push('');
+    lines.push('| Test | Flaky Rate | Occurrences | Total Runs | Last Flaky | Avg Attempts |');
+    lines.push('|------|-----------|-------------|------------|------------|-------------|');
+    for (const f of flaky) {
+      lines.push(`| ${f.test_name} | ${f.flaky_rate}% | ${f.flaky_count} | ${f.total_runs} | ${formatDate(f.last_flaky)} | ${f.avg_attempts} |`);
+    }
+    lines.push('');
+  }
+
+  // ── Unstable Selectors ──────────────────────────────────────────────────────
+  if (selectors.length > 0) {
+    lines.push('## Unstable Selectors');
+    lines.push('');
+    lines.push('CSS selectors that fail intermittently — candidates for improvement.');
+    lines.push('');
+    lines.push('| Selector | Action | Fail Rate | Uses | Tests | Page | Error |');
+    lines.push('|----------|--------|-----------|------|-------|------|-------|');
+    for (const s of selectors.slice(0, 20)) {
+      const selector = truncate(s.selector, 40);
+      const error = truncate(s.last_error || '-', 30);
+      lines.push(`| \`${selector}\` | ${s.action_type} | ${s.fail_rate}% | ${s.total_uses} | ${s.used_by_tests} | ${s.page_url || '-'} | ${error} |`);
+    }
+    lines.push('');
+  }
+
+  // ── Failing Pages ───────────────────────────────────────────────────────────
+  const failingPages = pages.filter(p => p.fail_rate > 0);
+  if (failingPages.length > 0) {
+    lines.push('## Failing Pages');
+    lines.push('');
+    lines.push('| Page | Fail Rate | Visits | Tests | Console Errors | Network Errors | Avg Load |');
+    lines.push('|------|-----------|--------|-------|---------------|----------------|----------|');
+    for (const p of failingPages.slice(0, 20)) {
+      lines.push(`| ${p.url_path} | ${p.fail_rate}% | ${p.total_visits} | ${p.tested_by} | ${p.console_errors} | ${p.network_errors} | ${formatDuration(p.avg_load_ms)} |`);
+    }
+    lines.push('');
+  }
+
+  // ── API Issues ──────────────────────────────────────────────────────────────
+  const apiIssues = apis.filter(a => a.error_rate > 0);
+  if (apiIssues.length > 0) {
+    lines.push('## API Issues');
+    lines.push('');
+    lines.push('| Endpoint | Error Rate | Calls | Avg Duration | Max Duration | Status Codes |');
+    lines.push('|----------|-----------|-------|-------------|-------------|-------------|');
+    for (const a of apiIssues.slice(0, 20)) {
+      lines.push(`| ${truncate(a.endpoint, 40)} | ${a.error_rate}% | ${a.total_calls} | ${formatDuration(a.avg_duration_ms)} | ${formatDuration(a.max_duration_ms)} | ${a.status_codes || '-'} |`);
+    }
+    lines.push('');
+  }
+
+  // ── Error Patterns ──────────────────────────────────────────────────────────
+  if (errors.length > 0) {
+    lines.push('## Error Patterns');
+    lines.push('');
+    lines.push('| Pattern | Category | Count | First Seen | Last Seen | Example Test |');
+    lines.push('|---------|----------|-------|------------|-----------|-------------|');
+    for (const e of errors.slice(0, 20)) {
+      lines.push(`| ${truncate(e.pattern, 50)} | ${e.category} | ${e.occurrence_count} | ${formatDate(e.first_seen)} | ${formatDate(e.last_seen)} | ${e.example_test || '-'} |`);
+    }
+    lines.push('');
+  }
+
+  // ── Recent Trend ────────────────────────────────────────────────────────────
+  if (trends.length > 0) {
+    const label = trendsGranularity === 'hourly' ? 'Recent Trend (hourly)' : 'Recent Trend (7 days)';
+    const col1 = trendsGranularity === 'hourly' ? 'Hour' : 'Date';
+    lines.push(`## ${label}`);
+    lines.push('');
+    lines.push(`| ${col1} | Pass Rate | Tests | Passed | Failed | Flaky | Avg Duration |`);
+    lines.push('|------|-----------|-------|--------|--------|-------|-------------|');
+    for (const t of trends) {
+      lines.push(`| ${t.date} | ${t.pass_rate}% | ${t.total_tests} | ${t.passed} | ${t.failed} | ${t.flaky_count} | ${formatDuration(t.avg_duration_ms)} |`);
+    }
+    lines.push('');
+  }
+
+  // Write the file
+  const cwd = config?._cwd || process.cwd();
+  const e2eDir = path.join(cwd, 'e2e');
+  if (!fs.existsSync(e2eDir)) {
+    fs.mkdirSync(e2eDir, { recursive: true });
+  }
+
+  const mdPath = path.join(e2eDir, 'learnings.md');
+  fs.writeFileSync(mdPath, lines.join('\n') + '\n');
+
+  return mdPath;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function formatDuration(ms) {
+  if (ms == null || isNaN(ms)) return '-';
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function formatDate(dateStr) {
+  if (!dateStr) return '-';
+  return dateStr.split('T')[0] || dateStr.slice(0, 10);
+}
+
+function truncate(str, max) {
+  if (!str) return '-';
+  return str.length > max ? str.slice(0, max - 3) + '...' : str;
+}