@keber/qa-framework 1.10.0 → 1.12.0

package/templates/automation-scaffold/global-setup.ts

@@ -11,14 +11,14 @@
  *   - Reference the matching storageState in playwright.config.ts projects[].
  *
  * Environment variables required:
- *   QA_BASE_URL           — Base URL of the application under test
- *   QA_USER_EMAIL         — Default QA user email (or username/RUT)
- *   QA_USER_PASSWORD      — Default QA user password
- *   QA_LOGIN_PATH         — Relative path to the login page (default: /login)
- *   QA_LOGIN_EMAIL_SELECTOR    — CSS selector for the username/email input
- *   QA_LOGIN_PASSWORD_SELECTOR — CSS selector for the password input
- *   QA_LOGIN_SUBMIT_SELECTOR   — CSS selector for the submit button
- *   QA_LOGIN_SUCCESS_SELECTOR  — CSS selector that confirms successful login
+ *   QA_BASE_URL           - Base URL of the application under test
+ *   QA_USER_EMAIL         - Default QA user email (or username/RUT)
+ *   QA_USER_PASSWORD      - Default QA user password
+ *   QA_LOGIN_PATH         - Relative path to the login page (default: /login)
+ *   QA_LOGIN_EMAIL_SELECTOR    - CSS selector for the username/email input
+ *   QA_LOGIN_PASSWORD_SELECTOR - CSS selector for the password input
+ *   QA_LOGIN_SUBMIT_SELECTOR   - CSS selector for the submit button
+ *   QA_LOGIN_SUCCESS_SELECTOR  - CSS selector that confirms successful login
  *
  * See .env.example for all supported variables.
  */
@@ -30,6 +30,102 @@ import * as fs from 'fs';
 
 dotenv.config();
 
+// Lane table and guards. Both are CommonJS so the guard logic stays testable with
+// `node --test` without adding ts-node or tsx as a dependency.
+const laneLock = require('./scripts/lane-lock.js');
+const guards = require('./scripts/global-setup-guards.js');
+
+type LaneInfo = {
+  account: string;
+  storageState: string;
+  mcpNamespace: string | null;
+  runnerProject: string | null;
+  capabilities: string[];
+};
+const LANE_INFO: Record<string, LaneInfo> = laneLock.LANE_INFO;
+
+function resolveVar(param: string | undefined, envKey: string, defaultValue: string): [string, string] {
+  if (param !== undefined) {
+    return [param, 'param'];
+  }
+  if (process.env[envKey] !== undefined) {
+    return [process.env[envKey]!, `env:${envKey}`];
+  }
+  return [defaultValue, 'default'];
+}
+
+/**
+ * Decides which lanes to log in.
+ *
+ * Resolution order:
+ *   1. QA_LANE_ONLY  - pins the run to exactly one lane. This is the normal path and
+ *      the only one the guards permit without an explicit cold-setup opt-in.
+ *   2. QA_AUTH_USER  - comma-separated lane ids, for an intentional multi-lane setup.
+ *   3. the projects' storageState, matched against the lane table.
+ *   4. every configured lane (the cold-setup path, gated by QA_COLD_SETUP=1).
+ *
+ * Step 3 matches storageState by EXACT equality against the lane table rather than by
+ * substring. The previous scaffold used storageState.includes('user-2'), which is what
+ * breaks first beyond two lanes: 'user-2' is a substring of 'user-20', and there was no
+ * branch at all for a third lane, so lanes past the second were silently never logged in.
+ */
+function resolveAuthLanes(config: FullConfig): string[] {
+  const laneIds = Object.keys(LANE_INFO);
+
+  const laneOnly = process.env.QA_LANE_ONLY;
+  if (laneOnly) {
+    // Throws on an unknown lane rather than guessing. Guessing is how a run logs into
+    // an account it does not hold.
+    return [laneLock.laneIdForQaLaneOnly(laneOnly)];
+  }
+
+  const explicit = process.env.QA_AUTH_USER;
+  if (explicit) {
+    const resolved = explicit
+      .split(',')
+      .map((value) => value.trim())
+      .filter((value) => laneIds.includes(value));
+    if (resolved.length) return resolved;
+  }
+
+  const fromProjects = new Set<string>();
+  for (const project of config.projects) {
+    const storageState = (project.use as { storageState?: unknown } | undefined)?.storageState;
+    if (typeof storageState !== 'string') continue;
+    for (const laneId of laneIds) {
+      if (LANE_INFO[laneId].storageState === storageState) fromProjects.add(laneId);
+    }
+  }
+  if (fromProjects.size) return [...fromProjects];
+
+  return laneIds;
+}
+
+async function dismissOnboardingFlow(page: import('@playwright/test').Page): Promise<void> {
+  // Override this with your app's onboarding dismissal logic.
+  // Use QA_DISMISS_ONBOARDING_LABELS (comma-separated button labels) to enable
+  // without modifying this file. Example: QA_DISMISS_ONBOARDING_LABELS=Skip,Got it
+  const raw = process.env.QA_DISMISS_ONBOARDING_LABELS ?? '';
+  const labels = raw.split(',').map((l: string) => l.trim()).filter(Boolean);
+  if (!labels.length) return;
+
+  for (let round = 0; round < 3; round++) {
+    let dismissed = false;
+    for (const label of labels) {
+      const button = page.getByRole('button', { name: label, exact: true }).first();
+      const visible = await button.isVisible({ timeout: 1_000 }).catch(() => false);
+      if (visible) {
+        await button.click({ timeout: 2_000 }).catch(() => {});
+        await page.waitForTimeout(250);
+        dismissed = true;
+      }
+    }
+    if (!dismissed) {
+      break;
+    }
+  }
+}
+
 /** Perform login and persist storageState to disk. */
 async function loginAs(params: {
   email:             string;
@@ -59,11 +155,53 @@ async function loginAs(params: {
   const page    = await context.newPage();
 
   try {
-    await page.goto(`${baseURL}${loginPath}`, { waitUntil: 'domcontentloaded' });
-    await page.locator(emailSelector).fill(email);
-    await page.locator(passwordSelector).fill(password);
-    await page.locator(submitSelector).click();
-    await page.waitForSelector(successSelector, { timeout: 15_000 });
+    const loginUrl = `${baseURL}${loginPath.startsWith('/') ? loginPath : `/${loginPath}`}`;
+    let signedIn = false;
+
+    for (let attempt = 1; attempt <= 3 && !signedIn; attempt++) {
+      await page.goto(loginUrl, { waitUntil: 'load', timeout: 60_000 });
+      await page.locator(emailSelector).fill(email);
+      // Trace safety: Playwright records fill() argument values in traces, and this
+      // project runs with trace/video 'retain-on-failure' - a failed CI run would
+      // persist the plaintext password in the artifact. Setting the value through
+      // evaluate() keeps it out of the trace. Do not "simplify" this back to fill().
+      // The input/change events are required because assigning .value directly does
+      // not notify SPA frameworks (Blazor/Radzen bind on those events).
+      // evaluate() has no auto-wait, so the explicit waitFor replaces the one that
+      // locator().fill() performed implicitly.
+      await page.locator(passwordSelector).waitFor({ state: 'visible', timeout: 30_000 });
+      await page.evaluate(
+        ([selector, pwd]) => {
+          const input = document.querySelector(selector) as HTMLInputElement | null;
+          if (!input) {
+            throw new Error(`[qa-framework] Password input not found for selector: ${selector}`);
+          }
+          input.value = pwd;
+          input.dispatchEvent(new Event('input', { bubbles: true }));
+          input.dispatchEvent(new Event('change', { bubbles: true }));
+        },
+        [passwordSelector, password] as const
+      );
+      await page.locator(submitSelector).click();
+
+      const result = await Promise.race([
+        page.waitForSelector(successSelector, { timeout: 30_000 }).then(() => 'ok' as const),
+        page.locator('text=An unhandled error has occurred.').waitFor({ state: 'visible', timeout: 30_000 }).then(() => 'crash' as const),
+      ]).catch(() => 'timeout' as const);
+
+      if (result === 'ok') {
+        signedIn = true;
+      } else if (result === 'crash') {
+        await page.getByText('Reload').click({ timeout: 5_000 }).catch(() => {});
+        await page.waitForTimeout(2_000);
+      }
+    }
+
+    if (!signedIn) {
+      throw new Error('[qa-framework] Login did not reach the success selector after 3 attempts.');
+    }
+
+    await dismissOnboardingFlow(page);
 
     // Ensure .auth/ directory exists
     const dir = path.dirname(stateFile);
@@ -77,30 +215,51 @@ async function loginAs(params: {
 }
 
 export default async function globalSetup(_config: FullConfig): Promise<void> {
-  const baseURL  = process.env.QA_BASE_URL!;
-  const email    = process.env.QA_USER_EMAIL!;
-  const password = process.env.QA_USER_PASSWORD!;
+  const baseURL = process.env.QA_BASE_URL!;
 
-  // --- Default role login ---
-  await loginAs({
-    email,
-    password,
-    baseURL,
-    stateFile: '.auth/user-default.json',
-  });
-
-  // --- Additional roles (uncomment and adapt as needed) ---
-  // await loginAs({
-  //   email:     process.env.QA_ADMIN_EMAIL!,
-  //   password:  process.env.QA_ADMIN_PASSWORD!,
-  //   baseURL,
-  //   stateFile: '.auth/user-admin.json',
-  // });
+  // Guards run BEFORE any login. A lock nothing consults is decoration, and this is
+  // the last point at which a run about to drive an account it does not hold can
+  // still be stopped.
   //
-  // await loginAs({
-  //   email:     process.env.QA_READONLY_EMAIL!,
-  //   password:  process.env.QA_READONLY_PASSWORD!,
-  //   baseURL,
-  //   stateFile: '.auth/user-readonly.json',
-  // });
+  // global-setup NEVER acquires or reserves a lane itself. It only READS the lock
+  // state and verifies the lane is already held. Reserving is the caller's job - the
+  // operator, the orchestrator, or the CI job. A global-setup that reserved its own
+  // lane would make every accidental run look legitimate.
+  guards.assertColdSetupIsIntentional(process.env);
+
+  const laneOnly = process.env.QA_LANE_ONLY;
+  if (laneOnly) {
+    guards.assertLaneIsLocked(laneOnly, process.env, laneLock);
+    guards.assertProjectsMatchLane(laneOnly, _config.projects, process.argv, laneLock);
+  }
+
+  for (const laneId of resolveAuthLanes(_config)) {
+    const lane = LANE_INFO[laneId];
+
+    // Credentials come from the lane's declared account prefix, e.g. account
+    // 'QA_USER4' resolves QA_USER4_EMAIL / QA_USER4_PASSWORD. This is what replaces
+    // the old hardcoded QA_USER / QA_USER2 pair and is what lets a lane be added by
+    // config alone.
+    const emailKey = `${lane.account}_EMAIL`;
+    const passwordKey = `${lane.account}_PASSWORD`;
+
+    if (!process.env[emailKey] || !process.env[passwordKey]) {
+      throw new Error(
+        `[global-setup] Lane ${laneId} (account ${lane.account}) is missing ${emailKey} or ` +
+        `${passwordKey}. Every configured lane needs its own credentials, otherwise two lanes ` +
+        'end up sharing an account, which is exactly what lanes exist to prevent.'
+      );
+    }
+
+    const [email, emailSource] = resolveVar(process.env[emailKey], emailKey, 'qa-user@example.com');
+    const [password, passwordSource] = resolveVar(process.env[passwordKey], passwordKey, 'CHANGE_ME');
+    console.log(`[global-setup] lane ${laneId} (${lane.account}) credentials from ${emailSource} / ${passwordSource}`);
+
+    await loginAs({
+      email,
+      password,
+      baseURL,
+      stateFile: lane.storageState,
+    });
+  }
 }

package/templates/automation-scaffold/playwright.config.ts

@@ -1,6 +1,23 @@
 import { defineConfig, devices } from '@playwright/test';
 import * as dotenv from 'dotenv';
-dotenv.config();
+import * as fs from 'fs';
+
+// Least privilege: this config only needs a handful of non-secret values, so it reads
+// them with dotenv.parse(), which returns a plain object and never touches process.env.
+// dotenv.config() would inject the WHOLE .env - every QA account password and ADO token
+// living in it - into a process that has no use for them, where any dependency, crash
+// dump or child process inherits them. Do not "simplify" this back to config().
+const ENV_KEYS = ['QA_SESSION_TTL_MS', 'QA_BASE_URL'] as const;
+if (fs.existsSync('.env')) {
+  const parsed = dotenv.parse(fs.readFileSync('.env'));
+  for (const key of ENV_KEYS) {
+    if (process.env[key] === undefined && parsed[key] !== undefined) {
+      process.env[key] = parsed[key];
+    }
+  }
+}
+
+export const SESSION_TTL_MS = Number(process.env.QA_SESSION_TTL_MS ?? 2 * 60 * 60 * 1000);
 
 // -------------------------------------------------------------------
 // Validate required environment variables at config load time
@@ -24,7 +41,7 @@ for (const key of required) {
 //   token:                   process.env.SYSTEM_ACCESSTOKEN ?? process.env.ADO_PAT,
 //   planId:                  Number(process.env.ADO_PLAN_ID),
 //   projectName:             process.env.ADO_PROJECT!,
-//   testRunTitle:            `[Auto] Sprint {{NNN}} — ${new Date().toISOString().slice(0, 10)}`,
+//   testRunTitle:            `[Auto] Sprint {{NNN}} - ${new Date().toISOString().slice(0, 10)}`,
 //   publishTestResultsMode:  'testRun' as const,
 //   uploadAttachments:       true,
 //   attachmentsType:         ['screenshot', 'video', 'trace'] as const,
@@ -36,6 +53,57 @@ for (const key of required) {
 //  },
 // };
 
+// -------------------------------------------------------------------
+// Parallel QA lanes
+// -------------------------------------------------------------------
+// A lane is a distinct QA account. Lanes exist because 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. Speed is not the reason.
+//
+// The lane table lives in qa-framework.config.json (parallelLanes.lanes) and is read
+// here through lane-lock.js, which is the SINGLE SOURCE OF TRUTH for the
+// lane -> storageState mapping. Never hardcode a storageState on a project below. A
+// parallel hardcoded mapping caused real evidence corruption once already: a project
+// pinned to one lane's storageState while QA_LANE_ONLY named another, so a run was
+// recorded under the wrong account and nothing failed at the time.
+//
+// A project with no parallelLanes block gets one implicit default lane, producing
+// exactly the single 'chromium' project this scaffold shipped before lanes existed.
+const laneLock = require('./scripts/lane-lock.js');
+
+type LaneInfo = {
+  account: string;
+  storageState: string;
+  mcpNamespace: string | null;
+  runnerProject: string | null;
+  capabilities: string[];
+};
+const LANE_INFO: Record<string, LaneInfo> = laneLock.LANE_INFO;
+
+// QA_LANE_ONLY pins the whole run to a single lane. When it is set, every lane project
+// resolves its storageState through that lane, so a --project bound to a different lane
+// cannot quietly drive an account this run does not hold. global-setup-guards.js
+// additionally rejects a --project whose storageState does not match the reserved lane.
+const QA_LANE_ONLY = process.env.QA_LANE_ONLY;
+
+function resolveStorageState(laneId: string): string {
+  return QA_LANE_ONLY
+    ? laneLock.storageStateForLaneOnly(QA_LANE_ONLY)
+    : LANE_INFO[laneId].storageState;
+}
+
+// One Playwright project per configured lane. A lane that declares a runnerProject uses
+// that name; otherwise the project is named chromium-lane-<id>. With the single implicit
+// default lane this yields one project named 'chromium'.
+const laneProjects = Object.entries(LANE_INFO).map(([laneId, lane]) => ({
+  name: lane.runnerProject || `chromium-lane-${laneId}`,
+  use: {
+    ...devices['Desktop Chrome'],
+    storageState: resolveStorageState(laneId),
+  },
+  dependencies: ['setup'],
+}));
+
 export default defineConfig({
   // ------ Test discovery ------
   testDir:  './tests',
@@ -76,20 +144,16 @@ export default defineConfig({
   globalSetup: './global-setup.ts',
 
   // ------ Projects ------
+  // To add a lane, add an entry to parallelLanes.lanes in qa-framework.config.json.
+  // There is nothing to uncomment or copy-paste here: the lane projects are generated
+  // from that table, so the config stays the only place a lane is defined.
   projects: [
     {
       name: 'setup',
       use:  { ...devices['Desktop Chrome'] },
       testMatch: /global-setup\.ts/,
     },
-    {
-      name: 'chromium',
-      use:  {
-        ...devices['Desktop Chrome'],
-        storageState: '.auth/user-default.json',
-      },
-      dependencies: ['setup'],
-    },
+    ...laneProjects,
   ],
 
   // ------ Output directories ------

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,
+};