@matware/e2e-runner 1.3.0 → 1.5.0

package/src/app-pool.js

@@ -0,0 +1,339 @@
+/**
+ * App Pool — isolated application environments for test isolation.
+ *
+ * Provides each test with its own application instance via fast VM/container
+ * forking. Supports multiple drivers:
+ *
+ *   - "docker"    — Docker-based: runs a fresh container per test (slower, ~2-5s)
+ *   - "zeroboot"  — Firecracker microVM fork via Zeroboot SDK (~0.8ms)
+ *
+ * Lifecycle:
+ *   1. Template creation (one-time): boot app, wait for ready, snapshot state
+ *   2. Fork (per-test): clone template into isolated instance with unique port
+ *   3. Test runs against fork's baseUrl
+ *   4. Fork destroyed after test completes
+ *
+ * The app pool is independent of the Chrome pool — both are selected in
+ * parallel by pool-manager.js for maximum throughput.
+ */
+
+import { log, colors as C } from './logger.js';
+
+// ── Port allocator ────────────────────────────────────────────────────────────
+
+/** Tracks allocated ports to avoid collisions across concurrent forks. */
+const allocatedPorts = new Set();
+
+function allocatePort(basePort, maxForks) {
+  for (let offset = 0; offset < maxForks; offset++) {
+    const port = basePort + offset;
+    if (!allocatedPorts.has(port)) {
+      allocatedPorts.add(port);
+      return port;
+    }
+  }
+  throw new Error(`App pool: no free ports in range ${basePort}-${basePort + maxForks - 1}`);
+}
+
+function releasePort(port) {
+  allocatedPorts.delete(port);
+}
+
+// ── Fork registry ─────────────────────────────────────────────────────────────
+
+/**
+ * Active fork tracking.
+ * Maps forkId → { port, driver, testName, startTime, metadata }
+ */
+const activeForks = new Map();
+let forkCounter = 0;
+
+function generateForkId() {
+  return `fork-${Date.now().toString(36)}-${(++forkCounter).toString(36)}`;
+}
+
+// ── Health check ──────────────────────────────────────────────────────────────
+
+/**
+ * Polls a URL until it returns 2xx or timeout is reached.
+ * Used to verify a forked app instance is ready to receive traffic.
+ */
+async function waitForReady(url, timeoutMs = 10000, intervalMs = 200) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+      if (res.ok) return true;
+    } catch { /* not ready yet */ }
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  throw new Error(`App pool: fork not ready after ${timeoutMs}ms (checked ${url})`);
+}
+
+// ── Driver: Docker ────────────────────────────────────────────────────────────
+
+/**
+ * Docker driver — runs a fresh container per fork.
+ * Slower (~2-5s) but works everywhere Docker is available.
+ *
+ * Expects appPool config:
+ *   image:       Docker image to run (required)
+ *   envVars:     { KEY: 'value' } environment variables for the container
+ *   readyCheck:  path to poll for readiness (e.g. '/health')
+ *   readyTimeout: ms to wait for ready (default 15000)
+ */
+async function dockerFork(config, port) {
+  const { execFile } = await import('child_process');
+  const { promisify } = await import('util');
+  const execFileAsync = promisify(execFile);
+
+  const appConfig = config.appPool;
+  const containerName = `e2e-app-${port}`;
+
+  const args = [
+    'run', '-d',
+    '--name', containerName,
+    '-p', `${port}:${appConfig.containerPort || 3000}`,
+  ];
+
+  // Add host.docker.internal access
+  args.push('--add-host', 'host.docker.internal:host-gateway');
+
+  // Environment variables
+  if (appConfig.envVars) {
+    for (const [key, value] of Object.entries(appConfig.envVars)) {
+      args.push('-e', `${key}=${value}`);
+    }
+  }
+
+  args.push(appConfig.image);
+
+  // Optional command override
+  if (appConfig.cmd) {
+    args.push(...(Array.isArray(appConfig.cmd) ? appConfig.cmd : appConfig.cmd.split(' ')));
+  }
+
+  await execFileAsync('docker', args);
+
+  return {
+    containerId: containerName,
+    cleanup: async () => {
+      try {
+        await execFileAsync('docker', ['rm', '-f', containerName]);
+      } catch { /* best effort */ }
+    },
+  };
+}
+
+async function dockerDestroy(metadata) {
+  if (metadata?.cleanup) {
+    await metadata.cleanup();
+  }
+}
+
+// ── Driver: Zeroboot ──────────────────────────────────────────────────────────
+
+/**
+ * Zeroboot driver — sub-millisecond VM forks via Firecracker snapshots.
+ *
+ * NOTE: Zeroboot currently has NO networking within VMs (serial I/O only).
+ * This driver is a forward-looking implementation for when networking is added.
+ * The interface is ready — only the SDK calls need updating.
+ *
+ * Expects appPool config:
+ *   zeroboot.apiUrl:     Zeroboot API endpoint (default: http://localhost:8484)
+ *   zeroboot.templateId: pre-created template ID (required)
+ *   readyCheck:          path to poll for readiness
+ *   readyTimeout:        ms to wait for ready (default 5000)
+ */
+
+/** Placeholder for Zeroboot SDK — replace with actual import when available. */
+function getZerobootClient(apiUrl) {
+  // When Zeroboot publishes their Node SDK:
+  //   import { ZerobootClient } from '@anthropic-ai/zeroboot';
+  //   return new ZerobootClient({ apiUrl });
+  return {
+    async fork(templateId, _options) {
+      // SDK call: creates a KVM fork from snapshot in ~0.8ms
+      // Returns: { forkId, port, host }
+      throw new Error(
+        'Zeroboot SDK not installed. Install with: npm install @anthropic-ai/zeroboot\n' +
+        'Zeroboot currently requires networking support (not yet available).\n' +
+        'See: https://github.com/zerobootdev/zeroboot'
+      );
+    },
+    async destroy(_forkId) {
+      // SDK call: destroys the forked VM
+    },
+    async status() {
+      // SDK call: returns template and fork status
+      return { templates: [], activeForks: 0, memoryUsed: 0 };
+    },
+  };
+}
+
+async function zerobootFork(config, port) {
+  const appConfig = config.appPool;
+  const apiUrl = appConfig.zeroboot?.apiUrl || 'http://localhost:8484';
+  const templateId = appConfig.zeroboot?.templateId;
+
+  if (!templateId) {
+    throw new Error('App pool (zeroboot): zeroboot.templateId is required in appPool config');
+  }
+
+  const client = getZerobootClient(apiUrl);
+  const fork = await client.fork(templateId, { port });
+
+  return {
+    zerobootForkId: fork.forkId,
+    client,
+    cleanup: async () => {
+      try {
+        await client.destroy(fork.forkId);
+      } catch { /* best effort */ }
+    },
+  };
+}
+
+async function zerobootDestroy(metadata) {
+  if (metadata?.cleanup) {
+    await metadata.cleanup();
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Forks a new isolated app instance.
+ *
+ * @param {object} config - Full e2e-runner config with appPool section
+ * @param {string} [testName] - Test name for logging/tracking
+ * @returns {{ forkId: string, baseUrl: string, port: number }}
+ */
+export async function forkAppInstance(config, testName = '') {
+  const appConfig = config.appPool;
+  if (!appConfig?.enabled) {
+    throw new Error('App pool is not enabled in config');
+  }
+
+  const driver = appConfig.driver || 'docker';
+  const basePort = appConfig.forkBasePort || 4000;
+  const maxForks = appConfig.maxForks || 10;
+  const port = allocatePort(basePort, maxForks);
+  const forkId = generateForkId();
+
+  log('🔱', `${C.cyan}Forking app${C.reset} ${C.dim}(${driver}, port ${port}${testName ? `, ${testName}` : ''})${C.reset}`);
+
+  const startMs = Date.now();
+  let metadata;
+
+  try {
+    if (driver === 'zeroboot') {
+      metadata = await zerobootFork(config, port);
+    } else if (driver === 'docker') {
+      metadata = await dockerFork(config, port);
+    } else {
+      throw new Error(`App pool: unknown driver "${driver}". Use "docker" or "zeroboot".`);
+    }
+
+    // Determine the baseUrl for the forked instance
+    const host = appConfig.forkHost || 'localhost';
+    const protocol = appConfig.forkProtocol || 'http';
+    const baseUrl = `${protocol}://${host}:${port}`;
+
+    // For Docker-based apps accessed from Chrome inside Docker:
+    const dockerBaseUrl = `http://host.docker.internal:${port}`;
+
+    // Wait for the app to be ready
+    if (appConfig.readyCheck) {
+      const checkUrl = `${baseUrl}${appConfig.readyCheck}`;
+      const readyTimeout = appConfig.readyTimeout || (driver === 'zeroboot' ? 5000 : 15000);
+      await waitForReady(checkUrl, readyTimeout);
+    }
+
+    const forkTimeMs = Date.now() - startMs;
+    log('🔱', `${C.green}App fork ready${C.reset} ${C.dim}(${forkTimeMs}ms, ${baseUrl})${C.reset}`);
+
+    const forkInfo = {
+      forkId,
+      port,
+      baseUrl,
+      dockerBaseUrl,
+      driver,
+      testName,
+      startTime: new Date().toISOString(),
+      forkTimeMs,
+      metadata,
+    };
+
+    activeForks.set(forkId, forkInfo);
+    return forkInfo;
+  } catch (error) {
+    releasePort(port);
+    throw error;
+  }
+}
+
+/**
+ * Destroys a forked app instance and releases its port.
+ *
+ * @param {string} forkId - Fork ID returned by forkAppInstance
+ */
+export async function destroyFork(forkId) {
+  const fork = activeForks.get(forkId);
+  if (!fork) return;
+
+  log('🔱', `${C.dim}Destroying app fork${C.reset} ${C.dim}(port ${fork.port}${fork.testName ? `, ${fork.testName}` : ''})${C.reset}`);
+
+  try {
+    if (fork.driver === 'zeroboot') {
+      await zerobootDestroy(fork.metadata);
+    } else if (fork.driver === 'docker') {
+      await dockerDestroy(fork.metadata);
+    }
+  } finally {
+    releasePort(fork.port);
+    activeForks.delete(forkId);
+  }
+}
+
+/**
+ * Returns the status of the app pool: active forks, port usage, per-fork details.
+ */
+export function getAppPoolStatus() {
+  const forks = [];
+  for (const [id, fork] of activeForks) {
+    forks.push({
+      forkId: id,
+      port: fork.port,
+      driver: fork.driver,
+      baseUrl: fork.baseUrl,
+      testName: fork.testName,
+      startTime: fork.startTime,
+      forkTimeMs: fork.forkTimeMs,
+    });
+  }
+
+  return {
+    activeForks: activeForks.size,
+    allocatedPorts: [...allocatedPorts].sort((a, b) => a - b),
+    forks,
+  };
+}
+
+/**
+ * Destroys all active forks. Called during cleanup/shutdown.
+ */
+export async function destroyAllForks() {
+  const ids = [...activeForks.keys()];
+  if (ids.length === 0) return;
+  log('🔱', `${C.dim}Destroying ${ids.length} app fork(s)...${C.reset}`);
+  await Promise.allSettled(ids.map(id => destroyFork(id)));
+}
+
+/**
+ * Checks if app pool is configured and enabled.
+ */
+export function isAppPoolEnabled(config) {
+  return config?.appPool?.enabled === true;
+}

package/src/config.js

@@ -40,6 +40,7 @@ const DEFAULTS = {
   connectRetries: 3,
   connectRetryDelay: 2000,
   poolPort: 3333,
+  poolDriver: 'auto',
   maxSessions: 10,
   retries: 0,
   retryDelay: 1000,
@@ -54,6 +55,17 @@ const DEFAULTS = {
   failOnNetworkError: false,
   actionRetries: 0,
   actionRetryDelay: 500,
+  screencast: false,
+  screencastQuality: 60,
+  screencastMaxWidth: 800,
+  screencastMaxHeight: 600,
+  screencastEveryNthFrame: 1,
+  // Auto-capture a thumbnail after each action so the storyline view is fully visual.
+  // Adds ~50-100ms per action; set false in CI if you only need final/error screenshots.
+  autoCaptureSteps: true,
+  autoCaptureWidth: 480,
+  autoCaptureHeight: 300,
+  autoCaptureQuality: 60,
   anthropicApiKey: null,
   anthropicModel: 'claude-sonnet-4-5-20250929',
   authToken: null,
@@ -68,7 +80,28 @@ const DEFAULTS = {
   neo4jBoltPort: 7687,
   neo4jHttpPort: 7474,
   verificationStrictness: 'moderate',
+  verificationThreshold: 0.02,
+  goldenDir: null,
   networkIgnoreDomains: [],
+  // App pool: isolated app environments per test
+  appPool: {
+    enabled: false,
+    driver: 'docker',              // 'docker' | 'zeroboot'
+    image: null,                   // Docker image to run (docker driver)
+    containerPort: 3000,           // Port the app listens on inside the container
+    cmd: null,                     // Optional command override
+    envVars: null,                 // { KEY: 'value' } for the container
+    forkBasePort: 4000,            // Host port range start for forked instances
+    forkHost: 'localhost',         // Host for health checks from runner
+    forkProtocol: 'http',
+    maxForks: 10,                  // Max concurrent forks
+    readyCheck: null,              // Path to poll for readiness (e.g. '/health')
+    readyTimeout: 15000,           // ms to wait for fork to be ready
+    zeroboot: {                    // Zeroboot-specific config
+      apiUrl: 'http://localhost:8484',
+      templateId: null,            // Pre-created template ID
+    },
+  },
   authLoginEndpoint: null,
   authCredentials: null,
   authTokenPath: 'token',
@@ -142,6 +175,12 @@ function loadEnvVars() {
   if (process.env.FAIL_ON_NETWORK_ERROR) env.failOnNetworkError = process.env.FAIL_ON_NETWORK_ERROR === 'true' || process.env.FAIL_ON_NETWORK_ERROR === '1';
   if (process.env.ACTION_RETRIES) env.actionRetries = parseInt(process.env.ACTION_RETRIES);
   if (process.env.ACTION_RETRY_DELAY) env.actionRetryDelay = parseInt(process.env.ACTION_RETRY_DELAY);
+  if (process.env.POOL_DRIVER) env.poolDriver = process.env.POOL_DRIVER;
+  if (process.env.SCREENCAST) env.screencast = process.env.SCREENCAST === 'true' || process.env.SCREENCAST === '1';
+  if (process.env.SCREENCAST_QUALITY) env.screencastQuality = parseInt(process.env.SCREENCAST_QUALITY);
+  if (process.env.SCREENCAST_MAX_WIDTH) env.screencastMaxWidth = parseInt(process.env.SCREENCAST_MAX_WIDTH);
+  if (process.env.SCREENCAST_MAX_HEIGHT) env.screencastMaxHeight = parseInt(process.env.SCREENCAST_MAX_HEIGHT);
+  if (process.env.SCREENCAST_EVERY_NTH_FRAME) env.screencastEveryNthFrame = parseInt(process.env.SCREENCAST_EVERY_NTH_FRAME);
   if (process.env.ANTHROPIC_API_KEY) env.anthropicApiKey = process.env.ANTHROPIC_API_KEY;
   if (process.env.ANTHROPIC_MODEL) env.anthropicModel = process.env.ANTHROPIC_MODEL;
   if (process.env.AUTH_TOKEN) env.authToken = process.env.AUTH_TOKEN;
@@ -158,6 +197,25 @@ function loadEnvVars() {
   if (process.env.NETWORK_IGNORE_DOMAINS) env.networkIgnoreDomains = process.env.NETWORK_IGNORE_DOMAINS.split(',').map(d => d.trim()).filter(Boolean);
   if (process.env.AUTH_LOGIN_ENDPOINT) env.authLoginEndpoint = process.env.AUTH_LOGIN_ENDPOINT;
   if (process.env.AUTH_TOKEN_PATH) env.authTokenPath = process.env.AUTH_TOKEN_PATH;
+  // credentials.env convention: E2E_USERNAME + E2E_PASSWORD → authCredentials
+  // Sends both email and username fields so the API accepts whichever it expects.
+  // E2E_AUTH_FIELD overrides to send a single field if desired.
+  if (process.env.E2E_USERNAME && process.env.E2E_PASSWORD) {
+    if (process.env.E2E_AUTH_FIELD) {
+      env.authCredentials = {
+        [process.env.E2E_AUTH_FIELD]: process.env.E2E_USERNAME,
+        password: process.env.E2E_PASSWORD,
+      };
+    } else {
+      env.authCredentials = {
+        email: process.env.E2E_USERNAME,
+        username: process.env.E2E_USERNAME,
+        password: process.env.E2E_PASSWORD,
+      };
+    }
+  }
+  if (process.env.E2E_LOGIN_ENDPOINT) env.authLoginEndpoint = process.env.E2E_LOGIN_ENDPOINT;
+  if (process.env.E2E_TOKEN_PATH) env.authTokenPath = process.env.E2E_TOKEN_PATH;
   if (process.env.GQL_ENDPOINT) env.gqlEndpoint = process.env.GQL_ENDPOINT;
   if (process.env.GQL_AUTH_HEADER) env.gqlAuthHeader = process.env.GQL_AUTH_HEADER;
   if (process.env.GQL_AUTH_KEY) env.gqlAuthKey = process.env.GQL_AUTH_KEY;
@@ -174,7 +232,53 @@ function loadEnvVars() {
       env.verificationStrictness = val;
     }
   }
-  
+  if (process.env.VERIFICATION_THRESHOLD) env.verificationThreshold = parseFloat(process.env.VERIFICATION_THRESHOLD);
+  if (process.env.GOLDEN_DIR) env.goldenDir = process.env.GOLDEN_DIR;
+
+  // App pool configuration from env vars
+  if (process.env.APP_POOL_ENABLED) {
+    env.appPool = env.appPool || {};
+    env.appPool.enabled = process.env.APP_POOL_ENABLED === 'true' || process.env.APP_POOL_ENABLED === '1';
+  }
+  if (process.env.APP_POOL_DRIVER) {
+    env.appPool = env.appPool || {};
+    env.appPool.driver = process.env.APP_POOL_DRIVER;
+  }
+  if (process.env.APP_POOL_IMAGE) {
+    env.appPool = env.appPool || {};
+    env.appPool.image = process.env.APP_POOL_IMAGE;
+  }
+  if (process.env.APP_POOL_CONTAINER_PORT) {
+    env.appPool = env.appPool || {};
+    env.appPool.containerPort = parseInt(process.env.APP_POOL_CONTAINER_PORT);
+  }
+  if (process.env.APP_POOL_BASE_PORT) {
+    env.appPool = env.appPool || {};
+    env.appPool.forkBasePort = parseInt(process.env.APP_POOL_BASE_PORT);
+  }
+  if (process.env.APP_POOL_MAX_FORKS) {
+    env.appPool = env.appPool || {};
+    env.appPool.maxForks = parseInt(process.env.APP_POOL_MAX_FORKS);
+  }
+  if (process.env.APP_POOL_READY_CHECK) {
+    env.appPool = env.appPool || {};
+    env.appPool.readyCheck = process.env.APP_POOL_READY_CHECK;
+  }
+  if (process.env.APP_POOL_READY_TIMEOUT) {
+    env.appPool = env.appPool || {};
+    env.appPool.readyTimeout = parseInt(process.env.APP_POOL_READY_TIMEOUT);
+  }
+  if (process.env.ZEROBOOT_API_URL) {
+    env.appPool = env.appPool || {};
+    env.appPool.zeroboot = env.appPool.zeroboot || {};
+    env.appPool.zeroboot.apiUrl = process.env.ZEROBOOT_API_URL;
+  }
+  if (process.env.ZEROBOOT_TEMPLATE_ID) {
+    env.appPool = env.appPool || {};
+    env.appPool.zeroboot = env.appPool.zeroboot || {};
+    env.appPool.zeroboot.templateId = process.env.ZEROBOOT_TEMPLATE_ID;
+  }
+
   // Sync configuration from env vars
   if (process.env.E2E_SYNC_MODE) {
     const mode = process.env.E2E_SYNC_MODE.toLowerCase();
@@ -231,11 +335,10 @@ async function loadConfigFile(cwd) {
   return {};
 }
 
-/** Load .env file from cwd into process.env (no deps, KEY=VALUE format). */
-function loadDotEnv(cwd) {
-  const envPath = path.join(cwd, '.env');
-  if (!fs.existsSync(envPath)) return;
-  const lines = fs.readFileSync(envPath, 'utf-8').split('\n');
+/** Load a KEY=VALUE file into process.env (no deps). */
+function loadEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  const lines = fs.readFileSync(filePath, 'utf-8').split('\n');
   for (const line of lines) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith('#')) continue;
@@ -254,6 +357,14 @@ function loadDotEnv(cwd) {
   }
 }
 
+/** Load .env and credentials.env from cwd into process.env. */
+function loadDotEnv(cwd) {
+  loadEnvFile(path.join(cwd, '.env'));
+  // credentials.env — search e2e/ subdir first, then cwd root
+  loadEnvFile(path.join(cwd, 'e2e', 'credentials.env'));
+  loadEnvFile(path.join(cwd, 'credentials.env'));
+}
+
 export async function loadConfig(cliArgs = {}, cwd = null) {
   cwd = cwd || process.cwd();
   loadDotEnv(cwd);
@@ -267,7 +378,7 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
     ...cliArgs,
   };
   
-  // Deep merge sync config (nested objects need special handling)
+  // Deep merge nested config objects
   if (fileConfig.sync || envConfig.sync || cliArgs.sync) {
     config.sync = deepMerge(
       DEFAULTS.sync,
@@ -276,6 +387,14 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
       cliArgs.sync || {}
     );
   }
+  if (fileConfig.appPool || envConfig.appPool || cliArgs.appPool) {
+    config.appPool = deepMerge(
+      DEFAULTS.appPool,
+      fileConfig.appPool || {},
+      envConfig.appPool || {},
+      cliArgs.appPool || {}
+    );
+  }
 
   // Apply environment profile overrides
   if (config.env && config.env !== 'default' && config.environments?.[config.env]) {
@@ -300,6 +419,11 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
     fs.mkdirSync(config.screenshotsDir, { recursive: true });
   }
 
+  // Auto-infer authLoginEndpoint from baseUrl if credentials are available but no endpoint
+  if (config.authCredentials && !config.authLoginEndpoint && config.baseUrl) {
+    config.authLoginEndpoint = config.baseUrl.replace(/\/+$/, '') + '/api/auth/login';
+  }
+
   // Stash cwd for project identity (used by db.js)
   config._cwd = cwd;
   if (!config.projectName) {