@matware/e2e-runner 1.1.0 → 1.2.1

package/bin/cli.js

@@ -14,6 +14,7 @@
  *   e2e-runner pool status                Show pool status
  *   e2e-runner pool restart               Restart the pool
  *   e2e-runner dashboard                   Start the web dashboard
+ *   e2e-runner capture <url>              Capture a screenshot of any URL
  *   e2e-runner issue <url>                Fetch issue and show details
  *   e2e-runner issue <url> --generate     Generate test file via Claude API
  *   e2e-runner issue <url> --verify       Generate + run + report bug status
@@ -28,14 +29,18 @@ import path from 'path';
 import http from 'http';
 import { fileURLToPath } from 'url';
 import { loadConfig } from '../src/config.js';
-import { startPool, stopPool, restartPool, getPoolStatus, waitForPool } from '../src/pool.js';
+import { startPool, stopPool, restartPool, getPoolStatus, waitForPool, connectToPool } from '../src/pool.js';
 import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from '../src/runner.js';
 import { generateReport, saveReport, printReport, persistRun } from '../src/reporter.js';
 import { startDashboard } from '../src/dashboard.js';
 import { fetchIssue } from '../src/issues.js';
 import { buildPrompt, generateTests, hasApiKey } from '../src/ai-generate.js';
 import { verifyIssue } from '../src/verify.js';
+import { ensureProject, computeScreenshotHash, registerScreenshotHash } from '../src/db.js';
 import { log, colors as C } from '../src/logger.js';
+import { listModules } from '../src/module-resolver.js';
+import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends } from '../src/learner-sqlite.js';
+import { startNeo4j, stopNeo4j, getNeo4jStatus } from '../src/neo4j-pool.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -59,6 +64,7 @@ function parseCLIConfig() {
   if (getFlag('--base-url')) cliArgs.baseUrl = getFlag('--base-url');
   if (getFlag('--pool-url')) cliArgs.poolUrl = getFlag('--pool-url');
   if (getFlag('--tests-dir')) cliArgs.testsDir = getFlag('--tests-dir');
+  if (getFlag('--modules-dir')) cliArgs.modulesDir = getFlag('--modules-dir');
   if (getFlag('--screenshots-dir')) cliArgs.screenshotsDir = getFlag('--screenshots-dir');
   if (getFlag('--concurrency')) cliArgs.concurrency = parseInt(getFlag('--concurrency'));
   if (getFlag('--pool-port')) cliArgs.poolPort = parseInt(getFlag('--pool-port'));
@@ -72,6 +78,12 @@ function parseCLIConfig() {
   if (getFlag('--port')) cliArgs.dashboardPort = parseInt(getFlag('--port'));
   if (getFlag('--dashboard-port')) cliArgs.dashboardPort = parseInt(getFlag('--dashboard-port'));
   if (getFlag('--project-name')) cliArgs.projectName = getFlag('--project-name');
+  if (hasFlag('--fail-on-network-error')) cliArgs.failOnNetworkError = true;
+  if (getFlag('--action-retries')) cliArgs.actionRetries = parseInt(getFlag('--action-retries'));
+  if (getFlag('--action-retry-delay')) cliArgs.actionRetryDelay = parseInt(getFlag('--action-retry-delay'));
+  if (getFlag('--auth-token')) cliArgs.authToken = getFlag('--auth-token');
+  if (getFlag('--auth-storage-key')) cliArgs.authStorageKey = getFlag('--auth-storage-key');
+  if (getFlag('--test-type')) cliArgs.testType = getFlag('--test-type');
   return cliArgs;
 }
 
@@ -91,22 +103,37 @@ ${C.bold}Usage:${C.reset}
   e2e-runner dashboard                  Start the web dashboard
   e2e-runner dashboard --port <port>    Custom port (default: 8484)
 
+  e2e-runner capture <url>               Capture a screenshot of any URL
+  e2e-runner capture <url> --full-page  Capture full scrollable page
+  e2e-runner capture <url> --selector <sel>  Wait for selector before capture
+  e2e-runner capture <url> --delay <ms> Wait before capturing
+  e2e-runner capture <url> --filename <name> Custom filename
+
   e2e-runner issue <url>                Fetch issue and show details
   e2e-runner issue <url> --generate     Generate test file via Claude API
   e2e-runner issue <url> --verify       Generate + run + report bug status
   e2e-runner issue <url> --prompt       Output the AI prompt (for piping)
+  e2e-runner issue <url> --test-type e2e|api  Test category (default: e2e)
 
   e2e-runner pool start                 Start the Chrome Pool
   e2e-runner pool stop                  Stop the Chrome Pool
   e2e-runner pool status                Show pool status
   e2e-runner pool restart               Restart the Chrome Pool
 
+  e2e-runner learnings                  Show test learnings summary
+  e2e-runner learnings --query <q>      Query: flaky, selectors, pages, apis, errors, trends
+
+  e2e-runner neo4j start                Start the Neo4j knowledge graph
+  e2e-runner neo4j stop                 Stop the Neo4j container
+  e2e-runner neo4j status               Show Neo4j status
+
   e2e-runner init                       Scaffold e2e/ in the current project
 
 ${C.bold}Options:${C.reset}
   --base-url <url>         App base URL (default: http://host.docker.internal:3000)
   --pool-url <ws-url>      Chrome Pool URL (default: ws://localhost:3333)
   --tests-dir <dir>        Tests directory (default: e2e/tests)
+  --modules-dir <dir>      Reusable modules directory (default: e2e/modules)
   --screenshots-dir <dir>  Screenshots directory (default: e2e/screenshots)
   --concurrency <n>        Parallel test workers (default: 3)
   --pool-port <port>       Chrome Pool port (default: 3333)
@@ -118,6 +145,7 @@ ${C.bold}Options:${C.reset}
   --output <format>        Report format: json, junit, both (default: json)
   --env <name>             Environment profile from config (default: default)
   --project-name <name>    Project display name for dashboard (default: directory name)
+  --fail-on-network-error  Fail tests when network requests fail (e.g. ERR_CONNECTION_REFUSED)
 
 ${C.bold}Config:${C.reset}
   Looks for e2e.config.js or e2e.config.json in the current directory.
@@ -128,6 +156,7 @@ ${C.bold}Config:${C.reset}
 async function cmdRun() {
   const cliArgs = parseCLIConfig();
   const config = await loadConfig(cliArgs);
+  config.triggeredBy = 'cli';
   let tests = [];
   let hooks = {};
 
@@ -135,18 +164,18 @@ async function cmdRun() {
   console.log(`${C.dim}Pool: ${config.poolUrl} | Base: ${config.baseUrl} | Concurrency: ${config.concurrency}${C.reset}\n`);
 
   if (hasFlag('--all')) {
-    const loaded = loadAllSuites(config.testsDir);
+    const loaded = loadAllSuites(config.testsDir, config.modulesDir, config.exclude);
     tests = loaded.tests;
     hooks = loaded.hooks;
   } else if (getFlag('--suite')) {
     const name = getFlag('--suite');
-    const loaded = loadTestSuite(name, config.testsDir);
+    const loaded = loadTestSuite(name, config.testsDir, config.modulesDir);
     tests = loaded.tests;
     hooks = loaded.hooks;
     log('📋', `${C.cyan}${name}${C.reset} (${tests.length} tests)`);
   } else if (getFlag('--tests')) {
     const file = getFlag('--tests');
-    const loaded = loadTestFile(path.resolve(file));
+    const loaded = loadTestFile(path.resolve(file), config.modulesDir);
     tests = loaded.tests;
     hooks = loaded.hooks;
     log('📋', `${C.cyan}${file}${C.reset} (${tests.length} tests)`);
@@ -217,6 +246,18 @@ async function cmdList() {
       console.log(`    ${C.dim}- ${test}${C.reset}`);
     }
   }
+
+  const modules = listModules(config.modulesDir);
+  if (modules.length > 0) {
+    console.log(`${C.bold}Available modules:${C.reset}\n`);
+    for (const mod of modules) {
+      const paramNames = mod.params.map(p => p.required ? p.name : `${C.dim}${p.name}?${C.reset}`).join(', ');
+      console.log(`  ${C.cyan}${mod.name}${C.reset} (${paramNames})`);
+      if (mod.description) {
+        console.log(`    ${C.dim}${mod.description}${C.reset}`);
+      }
+    }
+  }
   console.log('');
 }
 
@@ -266,6 +307,7 @@ function cmdInit() {
   // Create directory structure
   const dirs = [
     path.join(cwd, 'e2e', 'tests'),
+    path.join(cwd, 'e2e', 'modules'),
     path.join(cwd, 'e2e', 'screenshots'),
   ];
 
@@ -351,6 +393,69 @@ async function cmdDashboard() {
   process.on('SIGTERM', shutdown);
 }
 
+async function cmdCapture() {
+  const url = args[1];
+  if (!url || url.startsWith('--')) {
+    console.error(`${C.red}Usage: e2e-runner capture <url> [--filename <name>] [--full-page] [--selector <sel>] [--delay <ms>]${C.reset}`);
+    process.exit(1);
+  }
+
+  const cliArgs = parseCLIConfig();
+  const config = await loadConfig(cliArgs);
+
+  console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
+
+  log('🔌', 'Checking Chrome Pool...');
+  await waitForPool(config.poolUrl);
+
+  let browser;
+  try {
+    browser = await connectToPool(config.poolUrl);
+    const page = await browser.newPage();
+    await page.setViewport(config.viewport);
+
+    log('📸', `Navigating to ${C.cyan}${url}${C.reset}`);
+    await page.goto(url, { waitUntil: 'networkidle2', timeout: 30000 });
+
+    const selector = getFlag('--selector');
+    if (selector) {
+      log('⏳', `Waiting for selector: ${C.dim}${selector}${C.reset}`);
+      await page.waitForSelector(selector, { timeout: 10000 });
+    }
+
+    const delay = getFlag('--delay');
+    if (delay) {
+      await new Promise(r => setTimeout(r, parseInt(delay)));
+    }
+
+    // Build filename
+    let filename = getFlag('--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);
+    const fullPage = hasFlag('--full-page');
+    await page.screenshot({ path: screenshotPath, fullPage });
+
+    // Register hash in SQLite
+    const 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);
+
+    log('✅', `Saved: ${C.cyan}${screenshotPath}${C.reset}`);
+    log('🏷️', `Hash:  ${C.bold}ss:${hash}${C.reset}`);
+    console.log('');
+  } finally {
+    if (browser) browser.disconnect();
+  }
+}
+
 async function cmdIssue() {
   const url = args[1];
   if (!url || url.startsWith('--')) {
@@ -360,11 +465,12 @@ async function cmdIssue() {
 
   const cliArgs = parseCLIConfig();
   const config = await loadConfig(cliArgs);
+  const testType = cliArgs.testType || 'e2e';
 
   if (hasFlag('--prompt')) {
     // Output AI prompt as JSON to stdout
     const issue = fetchIssue(url);
-    const promptData = buildPrompt(issue, config);
+    const promptData = buildPrompt(issue, config, testType);
     console.log(JSON.stringify(promptData, null, 2));
     return;
   }
@@ -379,6 +485,7 @@ async function cmdIssue() {
     console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
     log('🔍', 'Fetching issue...');
 
+    config.testType = testType;
     const result = await verifyIssue(url, config);
     const { issue, report, bugConfirmed } = result;
 
@@ -407,9 +514,9 @@ async function cmdIssue() {
 
     const issue = fetchIssue(url);
     log('📋', `${C.cyan}${issue.title}${C.reset}`);
-    log('🤖', 'Generating tests via Claude API...');
+    log('🤖', `Generating ${testType} tests via Claude API...`);
 
-    const { tests, suiteName } = await generateTests(issue, config);
+    const { tests, suiteName } = await generateTests(issue, config, testType);
 
     if (!fs.existsSync(config.testsDir)) {
       fs.mkdirSync(config.testsDir, { recursive: true });
@@ -440,6 +547,155 @@ async function cmdIssue() {
   console.log('');
 }
 
+async function cmdLearnings() {
+  const cliArgs = parseCLIConfig();
+  const config = await loadConfig(cliArgs);
+  const projectId = ensureProject(config._cwd, config.projectName, config.screenshotsDir, config.testsDir);
+  const days = config.learningsDays || 30;
+  const query = getFlag('--query') || 'summary';
+
+  console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
+  console.log(`${C.dim}Project: ${config.projectName} | Analysis window: ${days} days${C.reset}\n`);
+
+  switch (query) {
+    case 'summary': {
+      const summary = getLearningsSummary(projectId);
+      if (summary.totalRuns === 0) {
+        console.log(`${C.dim}No learnings data yet. Run some tests to start building knowledge.${C.reset}\n`);
+        return;
+      }
+      console.log(`${C.bold}Health Overview${C.reset}`);
+      console.log(`${'─'.repeat(50)}`);
+      console.log(`  Total Runs:          ${C.bold}${summary.totalRuns}${C.reset}`);
+      console.log(`  Total Tests:         ${C.bold}${summary.totalTests}${C.reset}`);
+      console.log(`  Pass Rate:           ${summary.overallPassRate >= 90 ? C.green : summary.overallPassRate >= 70 ? '' : C.red}${summary.overallPassRate}%${C.reset}`);
+      console.log(`  Avg Duration:        ${summary.avgDurationMs < 1000 ? summary.avgDurationMs + 'ms' : (summary.avgDurationMs / 1000).toFixed(1) + 's'}`);
+      console.log(`  Flaky Tests:         ${summary.flakyTests.length > 0 ? C.red : C.green}${summary.flakyTests.length}${C.reset}`);
+      console.log(`  Unstable Selectors:  ${summary.unstableSelectors.length > 0 ? C.red : C.green}${summary.unstableSelectors.length}${C.reset}`);
+
+      if (summary.flakyTests.length > 0) {
+        console.log(`\n${C.bold}Top Flaky Tests${C.reset}`);
+        summary.flakyTests.slice(0, 5).forEach(f => {
+          console.log(`  ${C.yellow}⚠${C.reset} ${f.test_name} — ${f.flaky_rate}% flaky`);
+        });
+      }
+      if (summary.topErrors.length > 0) {
+        console.log(`\n${C.bold}Top Errors${C.reset}`);
+        summary.topErrors.slice(0, 5).forEach(e => {
+          console.log(`  ${C.red}✗${C.reset} [${e.category}] ${e.pattern.slice(0, 60)}${e.pattern.length > 60 ? '...' : ''} (${e.occurrence_count}x)`);
+        });
+      }
+      console.log('');
+      break;
+    }
+    case 'flaky': {
+      const flaky = getFlakySummary(projectId, days);
+      if (flaky.length === 0) { console.log(`${C.green}No flaky tests found.${C.reset}\n`); return; }
+      console.log(`${C.bold}Flaky Tests${C.reset}\n`);
+      flaky.forEach(f => {
+        console.log(`  ${C.yellow}⚠${C.reset} ${C.bold}${f.test_name}${C.reset}`);
+        console.log(`    Rate: ${f.flaky_rate}% | Occurrences: ${f.flaky_count}/${f.total_runs} | Avg attempts: ${f.avg_attempts}`);
+      });
+      console.log('');
+      break;
+    }
+    case 'selectors': {
+      const sels = getSelectorStability(projectId, days);
+      if (sels.length === 0) { console.log(`${C.green}All selectors are stable.${C.reset}\n`); return; }
+      console.log(`${C.bold}Unstable Selectors${C.reset}\n`);
+      sels.forEach(s => {
+        console.log(`  ${C.red}✗${C.reset} ${C.dim}${s.selector}${C.reset}`);
+        console.log(`    Action: ${s.action_type} | Fail: ${s.fail_rate}% | Uses: ${s.total_uses} | Tests: ${s.used_by_tests}`);
+      });
+      console.log('');
+      break;
+    }
+    case 'pages': {
+      const pages = getPageHealth(projectId, days);
+      const failing = pages.filter(p => p.fail_rate > 0);
+      if (failing.length === 0) { console.log(`${C.green}All pages are healthy.${C.reset}\n`); return; }
+      console.log(`${C.bold}Failing Pages${C.reset}\n`);
+      failing.forEach(p => {
+        console.log(`  ${C.red}✗${C.reset} ${C.bold}${p.url_path}${C.reset}`);
+        console.log(`    Fail: ${p.fail_rate}% | Visits: ${p.total_visits} | Console errors: ${p.console_errors} | Network errors: ${p.network_errors}`);
+      });
+      console.log('');
+      break;
+    }
+    case 'apis': {
+      const apis = getApiHealth(projectId, days);
+      const issues = apis.filter(a => a.error_rate > 0);
+      if (issues.length === 0) { console.log(`${C.green}All API endpoints are healthy.${C.reset}\n`); return; }
+      console.log(`${C.bold}API Issues${C.reset}\n`);
+      issues.forEach(a => {
+        console.log(`  ${C.red}✗${C.reset} ${C.bold}${a.endpoint}${C.reset}`);
+        console.log(`    Error: ${a.error_rate}% | Calls: ${a.total_calls} | Avg: ${Math.round(a.avg_duration_ms)}ms | Status: ${a.status_codes}`);
+      });
+      console.log('');
+      break;
+    }
+    case 'errors': {
+      const errors = getErrorPatterns(projectId);
+      if (errors.length === 0) { console.log(`${C.green}No error patterns recorded.${C.reset}\n`); return; }
+      console.log(`${C.bold}Error Patterns${C.reset}\n`);
+      errors.forEach(e => {
+        console.log(`  ${C.red}✗${C.reset} [${e.category}] ${e.pattern.slice(0, 70)}${e.pattern.length > 70 ? '...' : ''}`);
+        console.log(`    Count: ${e.occurrence_count} | Last: ${(e.last_seen || '').split('T')[0]} | Test: ${e.example_test || '-'}`);
+      });
+      console.log('');
+      break;
+    }
+    case 'trends': {
+      const trends = getTestTrends(projectId, days);
+      if (trends.length === 0) { console.log(`${C.dim}No trend data available.${C.reset}\n`); return; }
+      console.log(`${C.bold}Test Trends (${days} days)${C.reset}\n`);
+      console.log(`  ${'Date'.padEnd(12)} ${'Pass Rate'.padEnd(11)} ${'Tests'.padEnd(7)} ${'Pass'.padEnd(6)} ${'Fail'.padEnd(6)} Flaky`);
+      console.log(`  ${'─'.repeat(55)}`);
+      trends.forEach(t => {
+        const rateColor = t.pass_rate >= 90 ? C.green : t.pass_rate >= 70 ? '' : C.red;
+        console.log(`  ${t.date.padEnd(12)} ${rateColor}${(t.pass_rate + '%').padEnd(11)}${C.reset} ${String(t.total_tests).padEnd(7)} ${C.green}${String(t.passed).padEnd(6)}${C.reset} ${t.failed > 0 ? C.red : ''}${String(t.failed).padEnd(6)}${C.reset} ${t.flaky_count}`);
+      });
+      console.log('');
+      break;
+    }
+    default:
+      console.error(`${C.red}Unknown query: ${query}. Available: summary, flaky, selectors, pages, apis, errors, trends${C.reset}`);
+      process.exit(1);
+  }
+}
+
+async function cmdNeo4j() {
+  const subCmd = args[1];
+  const cliArgs = parseCLIConfig();
+  const config = await loadConfig(cliArgs);
+
+  switch (subCmd) {
+    case 'start':
+      startNeo4j(config);
+      break;
+    case 'stop':
+      stopNeo4j(config);
+      break;
+    case 'status': {
+      const status = getNeo4jStatus(config);
+      console.log(`\n${C.bold}Neo4j Status:${C.reset}\n`);
+      if (status.running) {
+        console.log(`  Status:   ${C.green}Running${C.reset}`);
+        console.log(`  Bolt:     ${C.cyan}bolt://localhost:${status.boltPort}${C.reset}`);
+        console.log(`  Browser:  ${C.cyan}http://localhost:${status.httpPort}${C.reset}`);
+      } else {
+        console.log(`  Status:   ${C.red}Stopped${C.reset}`);
+        if (status.error) console.log(`  ${C.dim}${status.error}${C.reset}`);
+      }
+      console.log('');
+      break;
+    }
+    default:
+      console.error(`${C.red}Unknown subcommand: ${subCmd}. Available: start, stop, status${C.reset}`);
+      process.exit(1);
+  }
+}
+
 // ==================== Main ====================
 
 async function main() {
@@ -472,10 +728,22 @@ async function main() {
       await cmdDashboard();
       break;
 
+    case 'capture':
+      await cmdCapture();
+      break;
+
     case 'issue':
       await cmdIssue();
       break;
 
+    case 'learnings':
+      await cmdLearnings();
+      break;
+
+    case 'neo4j':
+      await cmdNeo4j();
+      break;
+
     case 'init':
       cmdInit();
       break;

package/commands/create-test.md

@@ -0,0 +1,50 @@
+---
+description: Create a new E2E test by exploring the UI and designing test actions
+user_invocable: true
+allowed_tools:
+  - mcp__e2e-runner__e2e_pool_status
+  - mcp__e2e-runner__e2e_capture
+  - mcp__e2e-runner__e2e_list
+  - mcp__e2e-runner__e2e_create_test
+  - mcp__e2e-runner__e2e_create_module
+  - mcp__e2e-runner__e2e_run
+  - mcp__e2e-runner__e2e_screenshot
+  - Read
+  - Grep
+  - Glob
+---
+
+# Create E2E Test
+
+Help the user create a new E2E test file by exploring the application and designing appropriate test actions.
+
+## Workflow
+
+1. **Understand the goal** — Ask the user what they want to test if not already specified. Identify the page(s), user flow, and expected outcomes.
+
+2. **Check pool** — Call `e2e_pool_status` to ensure the Chrome pool is available.
+
+3. **Explore the UI** — Use `e2e_capture` to screenshot the target page(s). This helps understand the current state of the UI, available elements, and layout.
+
+4. **Check existing tests** — Call `e2e_list` to see what test suites already exist. Read relevant existing test files with `Read` to follow conventions and avoid duplication.
+
+5. **Explore source code** (optional) — If needed, use `Grep` and `Read` to find selectors, form field IDs, API endpoints, or component structure in the application source code.
+
+6. **Design the test** — Based on UI exploration and source code analysis, design the test actions:
+   - Use the most specific selectors available (data-testid > id > class > text)
+   - Prefer granular assertion actions over `evaluate`
+   - Use framework-aware actions for React/MUI (`type_react`, `click_option`, `focus_autocomplete`)
+   - Add `wait` actions before assertions on dynamic content
+   - Add `assert_no_network_errors` after critical page loads
+   - Consider adding an `expect` field for visual verification
+
+7. **Create the test** — Call `e2e_create_test` with the designed test structure. Consider creating reusable modules with `e2e_create_module` for repeated sequences (auth, navigation).
+
+8. **Validate** — Run the newly created test with `e2e_run` using the `suite` parameter. Analyze results and iterate if needed.
+
+## Arguments
+
+The user may provide:
+- A test name: `/e2e-runner:create-test login-flow`
+- A description of what to test: `/e2e-runner:create-test test the checkout process`
+- A URL to start from: `/e2e-runner:create-test http://localhost:3000/checkout`

package/commands/run.md

@@ -0,0 +1,49 @@
+---
+description: Run E2E tests and analyze results with screenshots and network drill-down
+user_invocable: true
+allowed_tools:
+  - mcp__e2e-runner__e2e_pool_status
+  - mcp__e2e-runner__e2e_list
+  - mcp__e2e-runner__e2e_run
+  - mcp__e2e-runner__e2e_screenshot
+  - mcp__e2e-runner__e2e_network_logs
+  - mcp__e2e-runner__e2e_learnings
+---
+
+# Run E2E Tests
+
+Execute E2E tests and provide a complete analysis of results.
+
+## Workflow
+
+1. **Check pool availability** — Call `e2e_pool_status` to confirm the Chrome pool is running. If not available, tell the user to run `npx e2e-runner pool start` via CLI.
+
+2. **List available suites** — Call `e2e_list` to show the user what test suites are available.
+
+3. **Run tests** — Call `e2e_run` based on user input:
+   - If user specified a suite name: use `suite` parameter
+   - If user specified a file: use `file` parameter
+   - If user said "all" or didn't specify: use `all: true`
+   - Always pass `cwd` with the current working directory
+   - Pass any user-specified overrides: `baseUrl`, `concurrency`, `retries`, `failOnNetworkError`
+
+4. **Analyze results** — Parse the run response:
+   - Report pass/fail summary and duration
+   - For failures: show error messages and retrieve error screenshots with `e2e_screenshot`
+   - For verifications (tests with `expect`): retrieve verification screenshots and judge against descriptions
+   - Highlight flaky tests if any
+   - Summarize network activity (failed requests, slow requests)
+
+5. **Drill down if needed** — For failed tests:
+   - Use `e2e_network_logs` with `runDbId` to investigate network failures
+   - Use `e2e_learnings` to check if this is a known pattern or new failure
+
+6. **Report** — Provide a clear summary to the user with actionable next steps.
+
+## Arguments
+
+The user may pass arguments after the command:
+- Suite name: `/e2e-runner:run auth` → run the auth suite
+- `--all`: run all suites
+- `--base-url <url>`: override base URL
+- `--retries <n>`: set retry count

package/commands/verify-issue.md

@@ -0,0 +1,63 @@
+---
+description: Verify a GitHub/GitLab issue by creating and running E2E tests
+user_invocable: true
+allowed_tools:
+  - mcp__e2e-runner__e2e_pool_status
+  - mcp__e2e-runner__e2e_issue
+  - mcp__e2e-runner__e2e_create_test
+  - mcp__e2e-runner__e2e_run
+  - mcp__e2e-runner__e2e_screenshot
+  - mcp__e2e-runner__e2e_network_logs
+  - mcp__e2e-runner__e2e_capture
+  - Read
+  - Grep
+---
+
+# Verify Issue
+
+Turn a GitHub or GitLab bug report into executable E2E tests to confirm or dismiss the bug.
+
+## Workflow
+
+1. **Check pool** — Call `e2e_pool_status` to ensure the Chrome pool is available.
+
+2. **Fetch the issue** — Call `e2e_issue` with the issue URL. Default `mode: "prompt"` returns issue details + a structured prompt for test creation.
+
+3. **Analyze the issue** — Parse the issue details:
+   - Understand the reported bug or expected behavior
+   - Identify affected pages/flows
+   - Note any reproduction steps provided
+
+4. **Explore the app** — Use `e2e_capture` to screenshot relevant pages. Use `Read` and `Grep` to check source code for related components, API endpoints, or selectors.
+
+5. **Design tests** — Create tests that assert the **correct behavior**:
+   - If tests **fail** → bug is confirmed (correct behavior is not working)
+   - If tests **pass** → bug is not reproducible
+
+6. **Create and run** — Use `e2e_create_test` to write the test file, then `e2e_run` to execute it.
+
+7. **Analyze results** — For failures:
+   - Retrieve error screenshots with `e2e_screenshot`
+   - Check network logs with `e2e_network_logs` for API-related issues
+   - Determine if the failure confirms the bug
+
+8. **Report verdict** — Clearly state:
+   - **BUG CONFIRMED**: tests failed, reproducing the issue
+   - **NOT REPRODUCIBLE**: tests passed, correct behavior works as expected
+   - Include evidence (screenshots, error messages, network details)
+
+## Alternative: Verify Mode
+
+If `ANTHROPIC_API_KEY` is set, use `e2e_issue` with `mode: "verify"` for a fully automated flow — it generates tests via Claude API, runs them, and reports the result.
+
+## Arguments
+
+**Required**: GitHub or GitLab issue URL
+
+```
+/e2e-runner:verify-issue https://github.com/org/repo/issues/123
+```
+
+Optional flags:
+- `--test-type api` — generate API tests instead of UI tests
+- `--verify` — use verify mode (requires ANTHROPIC_API_KEY)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matware/e2e-runner",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "mcpName": "io.github.fastslack/e2e-runner",
   "description": "E2E test runner using Chrome Pool (browserless/chrome) with parallel execution",
   "type": "module",
@@ -15,7 +15,12 @@
   "files": [
     "bin/",
     "src/",
-    "templates/"
+    "templates/",
+    ".claude-plugin/",
+    ".mcp.json",
+    "skills/",
+    "commands/",
+    "agents/"
   ],
   "keywords": [
     "e2e",
@@ -33,7 +38,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/fastslack/mtw-e2e-runner.git"
+    "url": "git+https://github.com/fastslack/mtw-e2e-runner.git"
   },
   "homepage": "https://github.com/fastslack/mtw-e2e-runner#readme",
   "dependencies": {
@@ -41,6 +46,9 @@
     "better-sqlite3": "^11.0.0",
     "puppeteer-core": "^24.0.0"
   },
+  "scripts": {
+    "build:dashboard": "node templates/build-dashboard.js"
+  },
   "engines": {
     "node": ">=20.0.0"
   }