@matware/e2e-runner 1.0.0

package/bin/cli.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+
+/**
+ * @matware/e2e-runner CLI
+ *
+ * Commands:
+ *   e2e-runner run --all                  Run all test suites
+ *   e2e-runner run --suite <name>         Run a specific suite
+ *   e2e-runner run --tests <file.json>    Run tests from a JSON file
+ *   e2e-runner run --inline '<json>'      Run inline JSON tests
+ *   e2e-runner list                       List available suites
+ *   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 pool
+ *   e2e-runner init                       Scaffold e2e/ in the current project
+ *   e2e-runner --help                     Show help
+ *   e2e-runner --version                  Show version
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { loadConfig } from '../src/config.js';
+import { startPool, stopPool, restartPool, getPoolStatus, waitForPool } from '../src/pool.js';
+import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from '../src/runner.js';
+import { generateReport, saveReport, printReport } from '../src/reporter.js';
+import { log, colors as C } from '../src/logger.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkgPath = path.join(__dirname, '..', 'package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+
+const args = process.argv.slice(2);
+
+function getFlag(name) {
+  const idx = args.indexOf(name);
+  if (idx === -1) return null;
+  return args[idx + 1] || true;
+}
+
+function hasFlag(name) {
+  return args.includes(name);
+}
+
+function parseCLIConfig() {
+  const cliArgs = {};
+  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('--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'));
+  if (getFlag('--max-sessions')) cliArgs.maxSessions = parseInt(getFlag('--max-sessions'));
+  if (getFlag('--timeout')) cliArgs.defaultTimeout = parseInt(getFlag('--timeout'));
+  if (getFlag('--retries')) cliArgs.retries = parseInt(getFlag('--retries'));
+  if (getFlag('--retry-delay')) cliArgs.retryDelay = parseInt(getFlag('--retry-delay'));
+  if (getFlag('--test-timeout')) cliArgs.testTimeout = parseInt(getFlag('--test-timeout'));
+  if (getFlag('--output')) cliArgs.outputFormat = getFlag('--output');
+  if (getFlag('--env')) cliArgs.env = getFlag('--env');
+  return cliArgs;
+}
+
+function showHelp() {
+  console.log(`
+${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}
+E2E test runner using Chrome Pool (browserless/chrome)
+
+${C.bold}Usage:${C.reset}
+  e2e-runner run --all                  Run all test suites
+  e2e-runner run --suite <name>         Run a specific suite
+  e2e-runner run --tests <file.json>    Run tests from a JSON file
+  e2e-runner run --inline '<json>'      Run inline JSON tests
+
+  e2e-runner list                       List available suites
+
+  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 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)
+  --screenshots-dir <dir>  Screenshots directory (default: e2e/screenshots)
+  --concurrency <n>        Parallel test workers (default: 3)
+  --pool-port <port>       Chrome Pool port (default: 3333)
+  --max-sessions <n>       Max pool sessions (default: 5)
+  --timeout <ms>           Action timeout (default: 10000)
+  --retries <n>            Retry failed tests N times (default: 0)
+  --retry-delay <ms>       Delay between retries (default: 1000)
+  --test-timeout <ms>      Per-test timeout (default: 60000)
+  --output <format>        Report format: json, junit, both (default: json)
+  --env <name>             Environment profile from config (default: default)
+
+${C.bold}Config:${C.reset}
+  Looks for e2e.config.js or e2e.config.json in the current directory.
+  Environment variables: BASE_URL, CHROME_POOL_URL, CONCURRENCY, etc.
+`);
+}
+
+async function cmdRun() {
+  const cliArgs = parseCLIConfig();
+  const config = await loadConfig(cliArgs);
+  let tests = [];
+  let hooks = {};
+
+  console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
+  console.log(`${C.dim}Pool: ${config.poolUrl} | Base: ${config.baseUrl} | Concurrency: ${config.concurrency}${C.reset}\n`);
+
+  if (hasFlag('--all')) {
+    const loaded = loadAllSuites(config.testsDir);
+    tests = loaded.tests;
+    hooks = loaded.hooks;
+  } else if (getFlag('--suite')) {
+    const name = getFlag('--suite');
+    const loaded = loadTestSuite(name, config.testsDir);
+    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));
+    tests = loaded.tests;
+    hooks = loaded.hooks;
+    log('📋', `${C.cyan}${file}${C.reset} (${tests.length} tests)`);
+  } else if (getFlag('--inline')) {
+    const data = JSON.parse(getFlag('--inline'));
+    if (Array.isArray(data)) {
+      tests = data;
+    } else {
+      tests = data.tests || [];
+      hooks = data.hooks || {};
+    }
+  } else {
+    console.error(`${C.red}No tests specified. Use --help to see available options.${C.reset}`);
+    process.exit(1);
+  }
+
+  if (tests.length === 0) {
+    console.error(`${C.red}No tests to run.${C.reset}`);
+    process.exit(1);
+  }
+
+  // Verify pool connectivity
+  log('🔌', 'Checking Chrome Pool...');
+  const pressure = await waitForPool(config.poolUrl);
+  log('✅', `Pool ready (${pressure.running}/${pressure.maxConcurrent} sessions, queued: ${pressure.queued})`);
+
+  // Execute tests
+  console.log('');
+  const results = await runTestsParallel(tests, config, hooks);
+  const report = generateReport(results);
+  saveReport(report, config.screenshotsDir, config);
+  printReport(report, config.screenshotsDir);
+
+  process.exit(report.summary.failed > 0 ? 1 : 0);
+}
+
+async function cmdList() {
+  const cliArgs = parseCLIConfig();
+  const config = await loadConfig(cliArgs);
+  const suites = listSuites(config.testsDir);
+
+  console.log(`\n${C.bold}Available suites:${C.reset}\n`);
+  for (const suite of suites) {
+    console.log(`  ${C.cyan}${suite.name}${C.reset} (${suite.testCount} tests)`);
+    for (const test of suite.tests) {
+      console.log(`    ${C.dim}- ${test}${C.reset}`);
+    }
+  }
+  console.log('');
+}
+
+async function cmdPool() {
+  const subCmd = args[1];
+  const cliArgs = parseCLIConfig();
+  const config = await loadConfig(cliArgs);
+
+  switch (subCmd) {
+    case 'start':
+      startPool(config);
+      break;
+
+    case 'stop':
+      stopPool(config);
+      break;
+
+    case 'restart':
+      restartPool(config);
+      break;
+
+    case 'status': {
+      const status = await getPoolStatus(config.poolUrl);
+      console.log(`\n${C.bold}Chrome Pool Status:${C.reset}\n`);
+      if (status.error) {
+        console.log(`  ${C.red}Offline${C.reset}: ${status.error}`);
+      } else {
+        console.log(`  Status:     ${status.available ? `${C.green}Available${C.reset}` : `${C.red}Busy${C.reset}`}`);
+        console.log(`  Running:    ${status.running}/${status.maxConcurrent}`);
+        console.log(`  Queued:     ${status.queued}`);
+        console.log(`  Sessions:   ${status.sessions.length}`);
+      }
+      console.log('');
+      break;
+    }
+
+    default:
+      console.error(`${C.red}Unknown subcommand: ${subCmd}. Available: start, stop, restart, status${C.reset}`);
+      process.exit(1);
+  }
+}
+
+function cmdInit() {
+  const cwd = process.cwd();
+  const templatesDir = path.join(__dirname, '..', 'templates');
+
+  // Create directory structure
+  const dirs = [
+    path.join(cwd, 'e2e', 'tests'),
+    path.join(cwd, 'e2e', 'screenshots'),
+  ];
+
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+      log('📁', `Created ${path.relative(cwd, dir)}/`);
+    }
+  }
+
+  // Copy config template
+  const configDest = path.join(cwd, 'e2e.config.js');
+  if (!fs.existsSync(configDest)) {
+    fs.copyFileSync(path.join(templatesDir, 'e2e.config.js'), configDest);
+    log('📄', 'Created e2e.config.js');
+  } else {
+    log('⏭️', 'e2e.config.js already exists, skipping');
+  }
+
+  // Copy sample test
+  const testDest = path.join(cwd, 'e2e', 'tests', 'sample.json');
+  if (!fs.existsSync(testDest)) {
+    fs.copyFileSync(path.join(templatesDir, 'sample-test.json'), testDest);
+    log('📄', 'Created e2e/tests/sample.json');
+  } else {
+    log('⏭️', 'e2e/tests/sample.json already exists, skipping');
+  }
+
+  // Create .gitkeep
+  const gitkeep = path.join(cwd, 'e2e', 'screenshots', '.gitkeep');
+  if (!fs.existsSync(gitkeep)) {
+    fs.writeFileSync(gitkeep, '');
+  }
+
+  // Update .gitignore
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const ignoreLines = ['e2e/screenshots/*.png', 'e2e/screenshots/report.json', '.e2e-pool/'];
+  if (fs.existsSync(gitignorePath)) {
+    let content = fs.readFileSync(gitignorePath, 'utf-8');
+    let added = false;
+    for (const line of ignoreLines) {
+      if (!content.includes(line)) {
+        content += `\n${line}`;
+        added = true;
+      }
+    }
+    if (added) {
+      fs.writeFileSync(gitignorePath, content + '\n');
+      log('📄', 'Updated .gitignore');
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, ignoreLines.join('\n') + '\n');
+    log('📄', 'Created .gitignore');
+  }
+
+  console.log(`
+${C.bold}${C.green}E2E structure created!${C.reset}
+
+${C.bold}Next steps:${C.reset}
+  1. Edit ${C.cyan}e2e.config.js${C.reset} with your app URL
+  2. Edit ${C.cyan}e2e/tests/sample.json${C.reset} with your tests
+  3. Start the pool: ${C.cyan}e2e-runner pool start${C.reset}
+  4. Run your tests: ${C.cyan}e2e-runner run --all${C.reset}
+`);
+}
+
+// ==================== Main ====================
+
+async function main() {
+  if (args.length === 0 || hasFlag('--help') || hasFlag('-h')) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (hasFlag('--version') || hasFlag('-v')) {
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  const command = args[0];
+
+  switch (command) {
+    case 'run':
+      await cmdRun();
+      break;
+
+    case 'list':
+      await cmdList();
+      break;
+
+    case 'pool':
+      await cmdPool();
+      break;
+
+    case 'init':
+      cmdInit();
+      break;
+
+    default:
+      console.error(`${C.red}Unknown command: ${command}. Use --help to see available options.${C.reset}`);
+      process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error(`${C.red}Fatal error: ${error.message}${C.reset}`);
+  process.exit(1);
+});

package/bin/mcp-server.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server entry point for @matware/e2e-runner
+ *
+ * Install in Claude Code (once, available everywhere):
+ *   claude mcp add --transport stdio --scope user e2e-runner -- npx -p @matware/e2e-runner e2e-runner-mcp
+ */
+
+import { startMcpServer } from '../src/mcp-server.js';
+
+startMcpServer().catch((error) => {
+  process.stderr.write(`MCP server error: ${error.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@matware/e2e-runner",
+  "version": "1.0.0",
+  "description": "E2E test runner using Chrome Pool (browserless/chrome) with parallel execution",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "e2e-runner": "bin/cli.js",
+    "e2e-runner-mcp": "bin/mcp-server.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "keywords": [
+    "e2e",
+    "testing",
+    "chrome",
+    "puppeteer",
+    "browserless",
+    "parallel",
+    "mcp",
+    "claude-code"
+  ],
+  "author": "Matware",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fastslack/mtw-e2e-runner.git"
+  },
+  "homepage": "https://github.com/fastslack/mtw-e2e-runner#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "puppeteer-core": "^24.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/actions.js

@@ -0,0 +1,159 @@
+/**
+ * E2E Action Executor
+ *
+ * Each action maps to a browser page interaction via Puppeteer.
+ * The 'evaluate' type runs JS in the browser context — this is
+ * intentional and equivalent to Puppeteer's page.evaluate().
+ * The JS comes from team-authored JSON test files.
+ */
+
+import { log } from './logger.js';
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function executeAction(page, action, config) {
+  const { type, selector, value, text, timeout = config.defaultTimeout || 10000 } = action;
+  const baseUrl = config.baseUrl;
+  const screenshotsDir = config.screenshotsDir;
+
+  switch (type) {
+    case 'goto': {
+      const url = value.startsWith('http') ? value : `${baseUrl}${value}`;
+      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
+      break;
+    }
+
+    case 'click':
+      if (selector) {
+        await page.waitForSelector(selector, { timeout });
+        await page.click(selector);
+      } else if (text) {
+        await page.waitForFunction(
+          (t) => [...document.querySelectorAll('button, a, [role="button"], [role="tab"], [role="menuitem"], div[class*="cursor"], span')]
+            .find(el => el.textContent.includes(t)),
+          { timeout },
+          text
+        );
+        await page.$$eval('button, a, [role="button"], [role="tab"], [role="menuitem"], div[class*="cursor"], span', (els, t) => {
+          const el = els.find(e => e.textContent.includes(t));
+          if (el) el.click();
+        }, text);
+      }
+      break;
+
+    case 'type':
+    case 'fill':
+      await page.waitForSelector(selector, { timeout });
+      await page.click(selector, { clickCount: 3 });
+      await page.keyboard.press('Backspace');
+      await page.type(selector, value, { delay: 20 });
+      break;
+
+    case 'wait':
+      if (selector) {
+        await page.waitForSelector(selector, { timeout });
+      } else if (text) {
+        await page.waitForFunction(
+          (t) => document.body.innerText.includes(t),
+          { timeout },
+          text
+        );
+      } else if (value) {
+        await sleep(parseInt(value));
+      }
+      break;
+
+    case 'screenshot': {
+      let filename = value || `screenshot-${Date.now()}.png`;
+      if (!/\.(png|jpg|jpeg|webp)$/i.test(filename)) {
+        filename += '.png';
+      }
+      const filepath = `${screenshotsDir}/${filename}`;
+      await page.screenshot({ path: filepath, fullPage: action.fullPage || false });
+      return { screenshot: filepath };
+    }
+
+    case 'assert_text': {
+      const bodyText = await page.evaluate(() => document.body.innerText);
+      if (!bodyText.includes(text)) {
+        throw new Error(`assert_text failed: "${text}" not found`);
+      }
+      break;
+    }
+
+    case 'assert_url': {
+      const currentUrl = page.url();
+      if (!currentUrl.includes(value)) {
+        throw new Error(`assert_url failed: expected "${value}", got "${currentUrl}"`);
+      }
+      break;
+    }
+
+    case 'assert_visible': {
+      const el = await page.$(selector);
+      if (!el) {
+        throw new Error(`assert_visible failed: "${selector}" not found`);
+      }
+      const visible = await page.$eval(selector, (e) => {
+        const style = window.getComputedStyle(e);
+        return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+      });
+      if (!visible) {
+        throw new Error(`assert_visible failed: "${selector}" is not visible`);
+      }
+      break;
+    }
+
+    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}`);
+      }
+      break;
+    }
+
+    case 'select':
+      await page.waitForSelector(selector, { timeout });
+      await page.select(selector, value);
+      break;
+
+    case 'clear':
+      await page.waitForSelector(selector, { timeout });
+      await page.click(selector, { clickCount: 3 });
+      await page.keyboard.press('Backspace');
+      break;
+
+    case 'press':
+      await page.keyboard.press(value);
+      break;
+
+    case 'scroll':
+      if (selector) {
+        await page.$eval(selector, (el) => {
+          el.scrollIntoView({ behavior: 'smooth' });
+        });
+      } else {
+        await page.evaluate((y) => window.scrollBy(0, parseInt(y) || 300), value || '300');
+      }
+      await sleep(500);
+      break;
+
+    case 'hover':
+      await page.waitForSelector(selector, { timeout });
+      await page.hover(selector);
+      break;
+
+    case 'evaluate':
+      // Intentional: runs JS in browser page context (from test JSON files)
+      await page.evaluate(value);
+      break;
+
+    default:
+      log('⚠️', `Unknown action: ${type}`);
+  }
+
+  return null;
+}

package/src/config.js

@@ -0,0 +1,104 @@
+/**
+ * Config Loader
+ *
+ * Priority order (highest to lowest):
+ * 1. CLI flags
+ * 2. Environment variables
+ * 3. Config file (e2e.config.js / e2e.config.json)
+ * 4. Defaults
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+const DEFAULTS = {
+  baseUrl: 'http://host.docker.internal:3000',
+  poolUrl: 'ws://localhost:3333',
+  testsDir: 'e2e/tests',
+  screenshotsDir: 'e2e/screenshots',
+  concurrency: 3,
+  viewport: { width: 1280, height: 720 },
+  defaultTimeout: 10000,
+  connectRetries: 3,
+  connectRetryDelay: 2000,
+  poolPort: 3333,
+  maxSessions: 10,
+  retries: 0,
+  retryDelay: 1000,
+  testTimeout: 60000,
+  outputFormat: 'json',
+  env: 'default',
+  hooks: { beforeAll: [], afterAll: [], beforeEach: [], afterEach: [] },
+};
+
+function loadEnvVars() {
+  const env = {};
+  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.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);
+  if (process.env.POOL_PORT) env.poolPort = parseInt(process.env.POOL_PORT);
+  if (process.env.MAX_SESSIONS) env.maxSessions = parseInt(process.env.MAX_SESSIONS);
+  if (process.env.RETRIES) env.retries = parseInt(process.env.RETRIES);
+  if (process.env.RETRY_DELAY) env.retryDelay = parseInt(process.env.RETRY_DELAY);
+  if (process.env.TEST_TIMEOUT) env.testTimeout = parseInt(process.env.TEST_TIMEOUT);
+  if (process.env.OUTPUT_FORMAT) env.outputFormat = process.env.OUTPUT_FORMAT;
+  if (process.env.E2E_ENV) env.env = process.env.E2E_ENV;
+  return env;
+}
+
+async function loadConfigFile(cwd) {
+  // Try e2e.config.js
+  const jsPath = path.join(cwd, 'e2e.config.js');
+  if (fs.existsSync(jsPath)) {
+    const fileUrl = pathToFileURL(jsPath).href;
+    const mod = await import(fileUrl);
+    return mod.default || mod;
+  }
+
+  // Try e2e.config.json
+  const jsonPath = path.join(cwd, 'e2e.config.json');
+  if (fs.existsSync(jsonPath)) {
+    return JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+  }
+
+  return {};
+}
+
+export async function loadConfig(cliArgs = {}) {
+  const cwd = process.cwd();
+  const fileConfig = await loadConfigFile(cwd);
+  const envConfig = loadEnvVars();
+
+  const config = {
+    ...DEFAULTS,
+    ...fileConfig,
+    ...envConfig,
+    ...cliArgs,
+  };
+
+  // Apply environment profile overrides
+  if (config.env && config.env !== 'default' && config.environments?.[config.env]) {
+    const profile = config.environments[config.env];
+    Object.assign(config, profile);
+  }
+  delete config.environments;
+
+  // Resolve relative paths against cwd
+  if (!path.isAbsolute(config.testsDir)) {
+    config.testsDir = path.join(cwd, config.testsDir);
+  }
+  if (!path.isAbsolute(config.screenshotsDir)) {
+    config.screenshotsDir = path.join(cwd, config.screenshotsDir);
+  }
+
+  // Ensure screenshots directory exists
+  if (!fs.existsSync(config.screenshotsDir)) {
+    fs.mkdirSync(config.screenshotsDir, { recursive: true });
+  }
+
+  return config;
+}