@keber/qa-framework 1.11.3 → 1.12.0

package/templates/automation-scaffold/scripts/global-setup-guards.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Guard functions for global-setup.ts.
+ *
+ * These live in a plain CommonJS module rather than as private functions inside
+ * global-setup.ts so they are directly testable with `node --test`, without adding a
+ * TypeScript test runner (ts-node/tsx) as a dependency. global-setup.ts requires this
+ * module the same way it requires ./lane-lock.js.
+ *
+ * WHY GUARDS AT ALL: a lock nothing consults is decoration. global-setup is the one
+ * place that actually performs a login, so it is the last point at which a run about
+ * to drive an account it does not hold can still be stopped.
+ *
+ * global-setup NEVER calls acquire or reserve itself. It only READS lane state and
+ * verifies the lane is already held. Owning the reserve/release lifecycle is the
+ * caller's job - the CLI operator, the orchestrator, or the CI job. A global-setup
+ * that reserved its own lane would make every accidental run look legitimate.
+ *
+ * Each guard takes an explicit `env` (defaulting to process.env) and an injectable
+ * lane-lock module, so tests can pass a synthetic matrix without mutating globals.
+ */
+
+/**
+ * Fail-closed guard. Runs BEFORE any login or browser work.
+ *
+ * Without QA_LANE_ONLY this is a "cold setup" that re-logs in EVERY lane's account,
+ * which silently invalidates any other agent's or CI job's concurrently running
+ * session on the shared QA server. That is occasionally what you actually want, so
+ * QA_COLD_SETUP=1 is the single explicit escape hatch - explicit so it can never be
+ * an accident. If neither is set, throw before touching anything.
+ */
+function assertColdSetupIsIntentional(env) {
+  env = env || process.env;
+  if (env.QA_LANE_ONLY) return;
+  if (env.QA_COLD_SETUP === '1') return;
+  throw new Error(
+    '[global-setup] Refusing to run a cold setup (no QA_LANE_ONLY set). A cold setup re-logs in ' +
+    "EVERY lane account and can silently invalidate another agent or CI job's concurrently " +
+    'running session on the shared QA server. Set QA_LANE_ONLY=<lane id> to log in a single lane ' +
+    'only, or set QA_COLD_SETUP=1 explicitly if you really intend to relogin ALL lanes.'
+  );
+}
+
+/**
+ * Lane-lock awareness guard. Only meaningful when QA_LANE_ONLY is set; the cold-setup
+ * guard above already rejects the "neither set" case.
+ *
+ * Skipped entirely in CI (env.CI === 'true'): the locks directory is local, ephemeral
+ * and per-machine, and does not persist between CI agents, so a CI job's lane will
+ * never appear busy in a fresh agent's lanes.json and enforcing this there would fail
+ * every time. The CI-side equivalent belongs at the pipeline level - fail the job in
+ * seconds if QA_LANE_ONLY is empty, before npm ci and browser installation.
+ */
+function assertLaneIsLocked(laneOnly, env, laneLockModule) {
+  env = env || process.env;
+  if (env.CI === 'true') return;
+
+  const laneLock = laneLockModule || require('./lane-lock.js');
+
+  const laneId = laneLock.laneIdForQaLaneOnly(laneOnly);
+  const state = laneLock.loadState();
+  const laneState = state.lanes[laneId];
+
+  if (!laneState || laneState.status !== 'busy') {
+    throw new Error(
+      `[global-setup] QA_LANE_ONLY=${laneOnly} (lane ${laneId}) is not reserved in the lane lock state. ` +
+      'Run `node scripts/lane-lock.js reserve <laneId> "<label>"` before running Playwright locally, ' +
+      'so global-setup knows this lane is intentionally in use.'
+    );
+  }
+}
+
+/**
+ * Parses --project=<name> and --project <name> out of an argv-shaped array. Returns
+ * every match in order, because Playwright accepts --project more than once.
+ */
+function selectedProjectNamesFromArgv(argv) {
+  const names = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--project=')) {
+      names.push(arg.slice('--project='.length));
+      continue;
+    }
+    if (arg === '--project' && i + 1 < argv.length) {
+      names.push(argv[i + 1]);
+      i++;
+    }
+  }
+  return names;
+}
+
+/**
+ * Project/lane correspondence guard.
+ *
+ * The guards above verify the LANE named by QA_LANE_ONLY is held. They never check
+ * that the --project actually being run points its storageState at that same lane.
+ * This closes that gap by comparing the storageState of the requested project(s)
+ * against the storageState the lane table says QA_LANE_ONLY should be using.
+ *
+ * With playwright.config.ts resolving storageState through the lane table, this
+ * should never fire in the happy path. It is kept as cheap defense in depth for two
+ * cases that stay real: a regression in the resolver itself, and a future project
+ * added with a hand-hardcoded storageState (an easy mistake to make by copy-pasting
+ * an older project block). That second case is exactly what caused evidence
+ * corruption before the resolver existed, and this guard is the only thing that
+ * catches it at runtime.
+ *
+ * `projects` is the COMPLETE unfiltered list Playwright passes to globalSetup, not
+ * just the ones selected by --project, so process.argv is the only reliable signal
+ * for what was actually requested.
+ */
+function assertProjectsMatchLane(qaLaneOnly, projects, argv, laneLockModule) {
+  if (!qaLaneOnly) return; // cold-setup path, already gated above
+
+  argv = argv || process.argv;
+  const laneLock = laneLockModule || require('./lane-lock.js');
+
+  const selectedNames = selectedProjectNamesFromArgv(argv);
+  if (selectedNames.length === 0) {
+    throw new Error(
+      `[global-setup] QA_LANE_ONLY=${qaLaneOnly} is set but no --project was passed on the CLI. ` +
+      'Running without --project executes EVERY project declared in playwright.config.ts, most of ' +
+      "which point at other lanes' storageState - this would silently drive another lane's session " +
+      'instead of the one you reserved. Pass --project=<name> explicitly.'
+    );
+  }
+
+  const selectedProjects = selectedNames.map((name) => {
+    const found = (projects || []).find((p) => p.name === name);
+    if (!found) {
+      throw new Error(
+        `[global-setup] --project=${name} does not match any project declared in playwright.config.ts. ` +
+        'Check for a typo in the --project value.'
+      );
+    }
+    return found;
+  });
+
+  const laneId = laneLock.laneIdForQaLaneOnly(qaLaneOnly);
+  const expectedStorageState = laneLock.LANE_INFO[laneId].storageState;
+
+  // Projects without a string use.storageState (the 'setup' project, for instance)
+  // do not authenticate against any lane, so there is nothing to compare. Filtering
+  // by "has a string storageState" rather than by a name allowlist means any future
+  // no-auth project is excluded automatically.
+  const mismatches = selectedProjects.filter((p) => {
+    const storageState = p.use && p.use.storageState;
+    return typeof storageState === 'string' && storageState !== expectedStorageState;
+  });
+
+  if (mismatches.length > 0) {
+    const reverseLookup = (storageState) => {
+      for (const [id, info] of Object.entries(laneLock.LANE_INFO)) {
+        if (info.storageState === storageState) return id;
+      }
+      return 'unknown';
+    };
+
+    const details = mismatches
+      .map((p) => {
+        const actual = p.use.storageState;
+        return `  - project "${p.name}" uses storageState "${actual}" (that storageState belongs to ` +
+          `lane ${reverseLookup(actual)}, not lane ${laneId})`;
+      })
+      .join('\n');
+
+    throw new Error(
+      `[global-setup] QA_LANE_ONLY=${qaLaneOnly} (lane ${laneId}, expected storageState ` +
+      `"${expectedStorageState}") does not match the storageState of the --project(s) requested:\n${details}\n` +
+      'Either fix QA_LANE_ONLY to match the --project you are running, or pass a --project whose ' +
+      'storageState matches the reserved lane.'
+    );
+  }
+}
+
+module.exports = {
+  assertColdSetupIsIntentional,
+  assertLaneIsLocked,
+  selectedProjectNamesFromArgv,
+  assertProjectsMatchLane,
+};

package/templates/automation-scaffold/scripts/lane-config.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Lane table resolution for the parallel QA lanes.
+ *
+ * WHY LANES EXIST: not for speed. The applications under test invalidate a session
+ * when the same account logs in again, so two concurrent workers sharing one account
+ * silently destroy each other's session. Each lane is a distinct QA account, and the
+ * lock in lane-lock.js is what stops two workers landing on the same one.
+ *
+ * This module owns the lane TABLE (which lanes exist and what each one is bound to).
+ * lane-lock.js owns the lane STATE (which lanes are currently held). Keeping them
+ * apart means the table can be parsed and tested without touching the filesystem
+ * state, and means playwright.config.ts can resolve a storageState without pulling
+ * in the lock machinery.
+ *
+ * A lane is four coupled values, not just an account. All four come from config
+ * because none of them can be reliably inferred:
+ *
+ *   account       env var prefix for credentials, e.g. QA_USER4 -> QA_USER4_EMAIL
+ *   storageState  the Playwright storage state file for that account
+ *   mcpNamespace  tool prefix when an agent drives this lane over Playwright MCP
+ *   runnerProject the playwright.config.ts project name bound to this lane
+ *
+ * CAPABILITIES ARE PER-LANE, NOT PER-SET. A project can have 6 accounts but only 3
+ * MCP servers. Handing lane 5 to a consumer that needs MCP tools lane 5 lacks is a
+ * real failure that happened in production use, not a hypothetical. So each lane
+ * declares its own capabilities and consumers state what they require; see
+ * lanesWithCapability() and assertLaneHasCapability().
+ *
+ * BACKWARD COMPATIBILITY: a project with no `parallelLanes` block in its config gets
+ * the implicit single default lane (lane '1', account QA_USER, storageState
+ * .auth/user-default.json) - exactly the shape the pre-N-lane scaffold hardcoded.
+ * See DEFAULT_LANE_TABLE below.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// The implicit lane table used when a project declares no `parallelLanes` config.
+// These values match what the single-lane scaffold used before lanes were
+// configurable: one lane, QA_USER credentials, .auth/user-default.json, the
+// 'chromium' project. A project that never opts in must keep behaving exactly as it
+// did, so this table is not merely a nice default - it is the compatibility contract.
+const DEFAULT_LANE_TABLE = Object.freeze({
+  '1': Object.freeze({
+    account: 'QA_USER',
+    storageState: '.auth/user-default.json',
+    mcpNamespace: null,
+    runnerProject: 'chromium',
+    capabilities: Object.freeze([]),
+  }),
+});
+
+// A lane id is referenced from shell env (QA_LANE_ONLY), CI variables and JSON keys,
+// so it is restricted to a conservative token: alphanumerics, dash and underscore.
+const LANE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Locates qa-framework.config.json by walking up from `startDir`.
+ *
+ * The scaffold lives at qa/07-automation/e2e/ while the config lives at either the
+ * project root or qa/, so a fixed relative path would be wrong for one of them.
+ * Walking up finds it either way and returns undefined rather than throwing, so a
+ * project with no config at all falls through to DEFAULT_LANE_TABLE.
+ */
+function findConfigPath(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  const seen = new Set();
+  while (!seen.has(dir)) {
+    seen.add(dir);
+    for (const candidate of [
+      path.join(dir, 'qa-framework.config.json'),
+      path.join(dir, 'qa', 'qa-framework.config.json'),
+    ]) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+/**
+ * Validates and normalizes a `parallelLanes` config block into a lane table.
+ *
+ * Throws on any malformed lane rather than dropping it. A silently ignored lane is
+ * the worst outcome available here: the project believes it has N lanes of
+ * isolation, the lock hands out fewer, and two workers end up on one account - which
+ * is the exact failure the whole mechanism exists to prevent.
+ */
+function laneTableFromConfig(config) {
+  const block = config && config.parallelLanes;
+
+  if (block === undefined || block === null) return DEFAULT_LANE_TABLE;
+  if (typeof block !== 'object' || Array.isArray(block)) {
+    throw new Error('[lane-config] parallelLanes must be an object.');
+  }
+
+  // `enabled: false` is an explicit opt-out that must land on the same behavior as
+  // no config at all, so a project can disable lanes without deleting its lane
+  // definitions.
+  if (block.enabled === false) return DEFAULT_LANE_TABLE;
+
+  const lanes = block.lanes;
+  if (!Array.isArray(lanes) || lanes.length === 0) {
+    throw new Error('[lane-config] parallelLanes.lanes must be a non-empty array.');
+  }
+
+  const table = {};
+  for (const [index, lane] of lanes.entries()) {
+    const where = `parallelLanes.lanes[${index}]`;
+    if (!lane || typeof lane !== 'object' || Array.isArray(lane)) {
+      throw new Error(`[lane-config] ${where} must be an object.`);
+    }
+
+    const id = lane.id;
+    if (typeof id !== 'string' || !LANE_ID_PATTERN.test(id)) {
+      throw new Error(
+        `[lane-config] ${where}.id must be a non-empty string of letters, digits, "-" or "_". Got: ${JSON.stringify(id)}`
+      );
+    }
+    if (table[id]) {
+      throw new Error(`[lane-config] duplicate lane id "${id}" at ${where}.`);
+    }
+
+    for (const field of ['account', 'storageState']) {
+      if (typeof lane[field] !== 'string' || lane[field].length === 0) {
+        throw new Error(`[lane-config] ${where}.${field} is required and must be a non-empty string.`);
+      }
+    }
+
+    // mcpNamespace and runnerProject are optional: a lane may be CLI-only (no MCP
+    // server provisioned for it) or may not be bound to a runner project at all.
+    // Both are normalized to null so consumers never have to distinguish "absent"
+    // from "explicitly none".
+    for (const field of ['mcpNamespace', 'runnerProject']) {
+      const value = lane[field];
+      if (value !== undefined && value !== null && (typeof value !== 'string' || value.length === 0)) {
+        throw new Error(`[lane-config] ${where}.${field} must be a non-empty string when present.`);
+      }
+    }
+
+    let capabilities = lane.capabilities;
+    if (capabilities === undefined || capabilities === null) {
+      capabilities = [];
+    } else if (!Array.isArray(capabilities) || capabilities.some((c) => typeof c !== 'string' || !c)) {
+      throw new Error(`[lane-config] ${where}.capabilities must be an array of non-empty strings.`);
+    }
+
+    table[id] = Object.freeze({
+      account: lane.account,
+      storageState: lane.storageState,
+      mcpNamespace: lane.mcpNamespace === undefined ? null : lane.mcpNamespace,
+      runnerProject: lane.runnerProject === undefined ? null : lane.runnerProject,
+      capabilities: Object.freeze([...capabilities]),
+    });
+  }
+
+  // Two lanes sharing a storageState means two "isolated" lanes writing the same
+  // session file - they are not isolated at all, and the corruption is silent.
+  const byStorageState = new Map();
+  for (const [id, lane] of Object.entries(table)) {
+    const clash = byStorageState.get(lane.storageState);
+    if (clash) {
+      throw new Error(
+        `[lane-config] lanes "${clash}" and "${id}" share storageState "${lane.storageState}". ` +
+        'Each lane must have its own storageState file, otherwise the lanes are not isolated.'
+      );
+    }
+    byStorageState.set(lane.storageState, id);
+  }
+
+  return Object.freeze(table);
+}
+
+/** Reads the config file at `configPath` and returns its lane table. */
+function loadLaneTable(configPath) {
+  const resolved = configPath || findConfigPath(process.cwd());
+  if (!resolved || !fs.existsSync(resolved)) return DEFAULT_LANE_TABLE;
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  } catch (err) {
+    throw new Error(`[lane-config] Could not parse ${resolved}: ${err.message}`);
+  }
+  return laneTableFromConfig(config);
+}
+
+/**
+ * Maps a QA_LANE_ONLY value to a lane id.
+ *
+ * 'default' is accepted as an alias for the first declared lane, because the
+ * pre-N-lane scaffold and its CI pipelines already used QA_LANE_ONLY=default and
+ * those must keep working. Every other value must name a declared lane exactly.
+ *
+ * Throws on anything unrecognized. Callers must never silently fall back to a
+ * guessed lane: guessing is how a run lands on an account it does not hold.
+ */
+function laneIdForQaLaneOnly(qaLaneOnly, laneTable) {
+  const table = laneTable || loadLaneTable();
+  const ids = Object.keys(table);
+
+  if (qaLaneOnly === 'default') {
+    if (table.default) return 'default';
+    return ids[0];
+  }
+  if (typeof qaLaneOnly === 'string' && table[qaLaneOnly]) return qaLaneOnly;
+
+  throw new Error(
+    `[lane-config] Invalid QA_LANE_ONLY: ${JSON.stringify(qaLaneOnly)}. ` +
+    `Allowed values: default, ${ids.join(', ')}.`
+  );
+}
+
+/**
+ * Single source of truth for the lane -> storageState mapping.
+ *
+ * playwright.config.ts resolves every project's storageState through this function
+ * instead of hardcoding one per project. A parallel hardcoded mapping caused real
+ * evidence corruption once already - a run recorded under the wrong account, because
+ * the project's storageState was pinned to one lane while QA_LANE_ONLY named
+ * another. There must be exactly one place this mapping lives, and this is it.
+ */
+function storageStateForLaneOnly(qaLaneOnly, laneTable) {
+  const table = laneTable || loadLaneTable();
+  return table[laneIdForQaLaneOnly(qaLaneOnly, table)].storageState;
+}
+
+/** Lane ids that declare `capability`. */
+function lanesWithCapability(capability, laneTable) {
+  const table = laneTable || loadLaneTable();
+  return Object.keys(table).filter((id) => table[id].capabilities.includes(capability));
+}
+
+/**
+ * Throws unless lane `laneId` declares `capability`.
+ *
+ * This is the guard for the "6 accounts but only 3 MCP servers" failure: handing a
+ * consumer a lane that lacks a capability it needs fails later, confusingly, and
+ * inside the consumer. Failing here names the lane, the capability and what the lane
+ * actually has.
+ */
+function assertLaneHasCapability(laneId, capability, laneTable) {
+  const table = laneTable || loadLaneTable();
+  const lane = table[laneId];
+  if (!lane) throw new Error(`[lane-config] Unknown lane: ${laneId}`);
+  if (!lane.capabilities.includes(capability)) {
+    const have = lane.capabilities.length ? lane.capabilities.join(', ') : 'none';
+    throw new Error(
+      `[lane-config] Lane ${laneId} does not have capability "${capability}" (declared: ${have}). ` +
+      `Lanes with that capability: ${lanesWithCapability(capability, table).join(', ') || 'none'}.`
+    );
+  }
+}
+
+module.exports = {
+  DEFAULT_LANE_TABLE,
+  findConfigPath,
+  laneTableFromConfig,
+  loadLaneTable,
+  laneIdForQaLaneOnly,
+  storageStateForLaneOnly,
+  lanesWithCapability,
+  assertLaneHasCapability,
+};