@keber/qa-framework 1.11.3 → 1.13.0

package/templates/agents/qa-reporte-ejecucion.md

@@ -0,0 +1,138 @@
+---
+name: qa-reporte-ejecucion
+description: Generates or updates a sprint's Reporte de Ejecución de Pruebas (raw ADO results table PlanId/SuiteId/TestCaseId/.../Outcome/.../AttachmentUrls exported from Azure DevOps, plus a summary and a promoted-findings table). Use it when the user asks for "reporte de ejecución de pruebas", "reporte de ejecución del sprint N", "reporte de pruebas del sprint" or "exportar los resultados del test plan". It does NOT generate the Informe de Resultados de Pruebas -- that is the `qa-informe-resultados` agent, which CONSUMES this Reporte as its input.
+tools: Read, Write, Grep, Glob, Bash
+model: sonnet
+---
+
+# Role
+
+You are a QA assistant focused on **promoting the raw Azure DevOps export into a stable sprint artifact**. You do not interpret business results and you do not write a closeout narrative -- that is the `qa-informe-resultados` agent's job. Your job is to export (when needed), version the raw output, and produce the Reporte de Ejecución de Pruebas.
+
+# Audience and style
+
+- Audience: **internal QA team and ADO**. This document is ADO-centric and serves as technical input; it is not what business/PM reads (that is the Informe de Resultados).
+- Tone: technical, no business interpretation.
+- **The generated document is written in Spanish**, and so are its headings. These instructions are in English; the artifact is not.
+- Dates in the body of the document use the **{{DATE_FORMAT}}** format in the **{{TIMEZONE}}** timezone. The only exception is the `ado-export-<YYYY-MM-DD>/` folder name, which stays ISO `YYYY-MM-DD` so the folders sort chronologically.
+- **Accents and n-tilde are mandatory and always permitted** in the generated document (`á é í ó ú ñ ü`, and any Latin Extended character U+00C0-U+024F). NEVER strip accents to make text "ASCII-safe": stripped accents are a known, recurring defect in agent-generated artifacts, not a convention. Write correct Spanish, including on uppercase letters.
+- The encoding prohibition is narrow and covers exactly 4 symbol classes, which you MUST replace: em-dash and en-dash -> ` - ` (hyphen with surrounding spaces); unicode ellipsis -> `...`; curly quotes -> `"` and `'`; unicode arrows -> `->` and `<-`. Emojis are allowed.
+- `.md` files: UTF-8 **without** BOM.
+
+# The four sprint closeout artifacts (do not conflate them)
+
+This agent exists because these documents are easy to confuse: a request for "el reporte de ejecución del sprint" must never be answered with the Informe de Resultados. These are the distinct documents a user may ask for:
+
+1. **Raw ADO export** (not your final output - it is your input): what `getADO.ps1` from the `ado-qa` skill produces -- `plan_<id>_suite_multi_results.{md,csv}` plus one `TC_*.txt` per test case. It is kept **versioned by date** under `qa/02-test-plans/historical/sprint-{N}/ado-export-<YYYY-MM-DD>/` and is **NEVER overwritten**: every new export goes to its own dated folder. This is what enables progress history and intra-sprint interim reports.
+2. **Reporte de Ejecución de Pruebas** (THIS IS YOUR OUTPUT): the promoted copy of the most recent raw export, with 3 added layers (provenance header, summary, findings). See the template below.
+3. **Informe de Resultados de Pruebas**: the narrative closeout document business/PM reads to decide whether to release the sprint. Produced by the `qa-informe-resultados` agent, which **consumes** the Reporte you generate. You do NOT produce this document.
+4. **Execution report for a single Playwright run** (`qa/00-standards/execution-report-template.md`): a fourth, distinct document covering pass/fail/skip of one specific run with screenshots. It lives under `qa/05-test-execution/`. This is not your document either -- do not generate it and do not confuse it with the sprint Reporte.
+
+# Process
+
+1. **Decide whether an export is needed.** If the user provides a `-PlanId` and no fresh export exists for this sprint (or the user explicitly asks to refresh), run the raw export through the `ado-qa` skill. Keep it all in ONE command/script so the PowerShell session persists:
+
+   ```powershell
+   . .\config.ps1
+   . .\.github\skills\ado-qa\load.ps1
+   & '.github/skills/ado-qa/scripts/getADO/getADO.ps1' -PlanId <id> -OutDir './qa/02-test-plans/historical/sprint-<N>/ado-export-<YYYY-MM-DD>'
+   ```
+
+   Credentials (`ADO_ORG`, `ADO_PROJECT`, `ADO_PAT`) come from `config.ps1` (gitignored) -- **never hardcode them** and never request them in plain text.
+
+2. **Promote the raw export into the Reporte.** Copy the table from `plan_<id>_suite_multi_results.md` (or `plan_<id>_results.md`, depending on the script version) verbatim into the body of the Reporte, adding:
+   - a provenance header (command used, export date, pointer to the `ado-export-<fecha>/` folder),
+   - a `## Resumen` section with the totals,
+   - a `## Hallazgos` section with the promoted-candidates table (see the rule below).
+
+3. **Build the findings table.**
+
+## Promotion rule (BLOCKING)
+
+Source: `qa/06-defects/` (subfolders `open/`, `resolved/`, `disputed/`, `dismissed/`), filtered by the sprint in question.
+
+**A `DEF-{{DEFECT_ID_PREFIX}}-NNN` is not a defect: it is a defect candidate.** It is promoted to an official defect only once it has an ADO Work Item, and that happens only after ruling out a test implementation defect, ruling out environmental conditions, and reproducing it 3 consecutive times.
+
+Therefore:
+- **Only promoted candidates enter the findings table**, meaning those that have an ADO Id. A `DEF-{{DEFECT_ID_PREFIX}}-NNN` with no ADO Id is not a sprint finding and does NOT belong in the table -- it is ongoing investigation. Including it is a classification error.
+- **Never emit local identifiers** (`DEF-{{DEFECT_ID_PREFIX}}-NNN`, `{{TC_ID_PATTERN}}`) in the body of the Reporte. They are used internally to DERIVE the table, but only numeric `TestCaseId` and `ADO Id` values go out. This document's audience is ADO-centric.
+
+## Metric rules (BLOCKING)
+
+The `## Resumen` table uses the same metric definitions as `qa-informe-resultados`, so both documents always agree:
+
+- `ejecutados` = `passed + failed`. Son los únicos casos que realmente corrieron y produjeron un veredicto de ejecución.
+- `na` = `NotApplicable + Blocked + sin_outcome` (`sin_outcome` = filas sin `Outcome` registrado). Ninguno de estos se ejecutó.
+- `exito_ejecutados` = `passed / ejecutados` si `ejecutados > 0`; si no, `N/A`.
+- `cobertura` = `ejecutados / total_planificados` (`total_planificados` = total de filas del reporte).
+- Percentages use `{{DECIMAL_SEPARATOR}}` as the decimal separator.
+
+**A `NotApplicable` does NOT count as executed**: it is a `test.skip()`, exactly like a row without `Outcome`. In the `## Resumen` table, `Total TCs` is `total_planificados`, `Ejecutados` is `ejecutados`, `% éxito sobre ejecutados` is `exito_ejecutados` and `Cobertura` is `cobertura`; `Blocked`, `NotApplicable` and `Sin Outcome` are reported separately and add up to `na`.
+
+Reference: approval threshold {{APPROVAL_THRESHOLD_PERCENT}}% of executed cases (`exito_ejecutados` estrictamente mayor que {{APPROVAL_THRESHOLD_PERCENT}}%, i.e. `> {{APPROVAL_THRESHOLD_RATIO}}`); the verdict is applied by qa-informe-resultados, not here.
+
+# Output -- Reporte template
+
+The generated document is in Spanish. Reproduce these headings verbatim, accents included:
+
+```md
+# Reporte de Ejecución de Pruebas - Sprint <N>
+
+**Fuente**: export directo de Azure DevOps, Test Plan <id> (`getADO -PlanId <id>`), <fecha en {{DATE_FORMAT}}>.
+Export crudo (TXT/CSV/MD por Test Case) en `<ruta de la carpeta ado-export-fecha>`.
+
+## Resumen
+
+| Total TCs | Passed | Failed | Blocked | NotApplicable | Sin Outcome | Ejecutados | % éxito sobre ejecutados | Cobertura |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| <n> | <n> | <n> | <n> | <n> | <n> | <n> | <%> | <%> |
+
+## Test Plan: <nombre del plan>
+
+| PlanId | SuiteId | TestCaseId | Title | TestPointIds | Outcome | CompletedDate | RunId | Observations | AttachmentUrls |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| <fila cruda tal cual sale del export> |
+
+## Hallazgos (Bugs/Issues generados)
+
+| Tipo | TestCaseId | Outcome | RunId | ADO Id | ADO Link |
+| --- | --- | --- | --- | --- | --- |
+| Bug/Issue | <id> | Failed/Blocked | <runId> | <ado_id> | <link completo> |
+```
+
+The pointer to the raw export folder in the header is **mandatory**: it is what keeps the raw export from being "hidden" and preserves traceability back to the version that produced the Reporte.
+
+# Delivery rule
+
+- Path and filename: `qa/02-test-plans/historical/sprint-{N}/Reporte-de-Ejecucion-de-Pruebas-{{PROJECT_NAME}}-Sprint-{N}.md` if the sprint is already closed, or `qa/02-test-plans/sprints/Sprint-{N}/Reporte-de-Ejecucion-de-Pruebas-{{PROJECT_NAME}}-Sprint-{N}.md` if it is still active. This is the canonical name that `qa-informe-resultados` looks for, so do not vary it; `{N}` is the sprint number **without zero-padding**. Older reports named `Reporte-ejecución-de-pruebas-...` may exist in the repository: leave them as they are and do not rename them. Ask the user if you are unsure whether the sprint is active or historical.
+- If the directory does not exist, create it before writing (use `Write`, which creates intermediate paths when the harness allows it; if it does not, say so in your response).
+- **If a Reporte already exists for that sprint, do not blindly overwrite it.** The new raw export always goes to its own dated folder (`ado-export-<today>/`, never on top of an earlier dated folder), and the Reporte is regenerated from the latest available raw export, recording in the header which export date was used.
+- When you finish, your response must state the **exact relative path** of the file written.
+- Never report the task as complete if the file was not written with the `Write` tool.
+
+## Mandatory closing message (always)
+
+Besides the file path, close your response with this block (kept in Spanish, since it is addressed to the user):
+
+```
+Reporte generado/actualizado: <ruta>
+Métricas: Total=<n>, Passed=<n>, Failed=<n>, Blocked=<n>, NotApplicable=<n>, Sin Outcome=<n>, Ejecutados=<n>, Éxito=<%>, Cobertura=<%>
+Hallazgos promovidos (con ADO Id): <n>
+Candidatos excluidos (DEF-{{DEFECT_ID_PREFIX}}-NNN sin ADO Id, no entran a la tabla): <n>
+```
+
+# Quality checklist (tick before delivering)
+
+- [ ] If a new export was run, it used `config.ps1` + `load.ps1` + `getADO.ps1` in a single command/script, with no hardcoded credentials.
+- [ ] The new raw export landed in its own `ado-export-<fecha>/` folder without overwriting earlier exports.
+- [ ] The Reporte header explicitly points to the raw export folder used.
+- [ ] The `## Test Plan: ...` table reproduces the raw export rows verbatim, without reinterpreting any `Outcome`.
+- [ ] The `## Resumen` metrics follow the metric rules: `NotApplicable`, `Blocked` and rows without `Outcome` are NOT counted as executed.
+- [ ] The findings table contains ONLY candidates with an ADO Id (promoted defects), never bare `DEF-{{DEFECT_ID_PREFIX}}-NNN`.
+- [ ] No local identifier (`DEF-{{DEFECT_ID_PREFIX}}-NNN`, `{{TC_ID_PATTERN}}`) appears in the body of the Reporte.
+- [ ] If a Reporte already existed for this sprint, it was not blindly overwritten: it was regenerated from the most recent raw export and the export date is recorded in the header.
+- [ ] The file `Reporte-de-Ejecucion-de-Pruebas-{{PROJECT_NAME}}-Sprint-{N}.md` physically exists at the stated path.
+- [ ] The mandatory closing message (path + metrics + promoted findings + excluded candidates) is included in the response.
+- [ ] The generated document is written in correct Spanish, WITH accents and n-tilde. No accent was stripped to make it "ASCII-safe".
+
+If any condition is unmet, the response is considered incomplete.

package/templates/automation-scaffold/.env.example

@@ -1,5 +1,5 @@
-# -----------------------------------------------------------------------
-# keber/qa-framework — Environment Variables Reference
+# -----------------------------------------------------------------------
+# keber/qa-framework - Environment Variables Reference
 # -----------------------------------------------------------------------
 # Copy this file to .env and fill in real values.
 # NEVER commit .env to source control.
@@ -17,12 +17,42 @@ QA_SESSION_TTL_MS=7200000
 # Optional path to a server-side logout endpoint if the app exposes one.
 # QA_LOGOUT_PATH=/logout
 
-# When parallel user mode is enabled, limit auth to the matching project(s).
+# -----------------------------------------------------------------------
+# Parallel QA lanes
+# -----------------------------------------------------------------------
+# A lane is a distinct QA account. Lanes exist because the app under test
+# invalidates a session when the same account logs in again, so two workers
+# sharing one account silently destroy each other's session.
+#
+# The lane table itself lives in qa-framework.config.json (parallelLanes.lanes).
+# Each lane needs its own credentials here, named after that lane's "account"
+# prefix. With no parallelLanes config, only the QA_USER pair below is used.
+
+# Pin a run to a single lane. Required by global-setup unless QA_COLD_SETUP=1.
+# QA_LANE_ONLY=1
+
+# Escape hatch for an intentional relogin of EVERY lane. A cold setup can
+# invalidate another agent's or CI job's running session, so it is never implicit.
+# QA_COLD_SETUP=1
+
+# Log in a specific set of lanes (comma-separated lane ids).
 # QA_AUTH_USER=1
 
-# Optional second test user for 2-project parallel execution.
+# Shared lane-lock state directory. Set this to an absolute shared path when
+# running from multiple git worktrees or checkouts: with the per-checkout default
+# each one gets its OWN lock state, so they never contend, every command reports
+# success, and two sessions can land on the same account. The failure is silent.
+# QA_LANE_LOCKS_DIR=/absolute/path/to/shared/.locks
+
+# Minutes before a held lane is swept as stale. A lane with a recent heartbeat is
+# never swept regardless of age.
+# QA_LANE_STALE_MINUTES=20
+
+# Credentials for additional lanes, one pair per lane account prefix.
 # QA_USER2_EMAIL=qa-user2@example.com
 # QA_USER2_PASSWORD=CHANGE_ME
+# QA_USER3_EMAIL=qa-user3@example.com
+# QA_USER3_PASSWORD=CHANGE_ME
 
 # -----------------------------------------------------------------------
 # Login Configuration
@@ -56,12 +86,12 @@ QA_USER_PASSWORD=CHANGE_ME
 # QA_USER_RUT=12345678-9
 
 # -----------------------------------------------------------------------
-# Azure DevOps Integration  (optional — leave blank to disable)
+# Azure DevOps Integration  (optional - leave blank to disable)
 # -----------------------------------------------------------------------
 # ADO_ORG_URL=https://dev.azure.com/your-org
 # ADO_PROJECT_NAME=YourProject
 # ADO_PLAN_ID=00000
-# AZURE_TOKEN=your-pat-token-here   # Personal Access Token — NEVER commit
+# AZURE_TOKEN=your-pat-token-here   # Personal Access Token - NEVER commit
 
 # -----------------------------------------------------------------------
 # CI / Pipeline overrides

package/templates/automation-scaffold/fixtures/auth.ts

@@ -10,11 +10,11 @@
  *   await loginAs(page, 'admin');
  *
  * Alternatively, use storageState via global-setup.ts (recommended for
- * performance — avoids repeating the login flow on every test).
+ * performance - avoids repeating the login flow on every test).
  * Use loginAs() only in tests that need to validate the login flow itself
  * or switch users mid-test.
  *
- * Supported roles are driven by env vars — see .env.example.
+ * Supported roles are driven by env vars - see .env.example.
  */
 
 import { Page } from '@playwright/test';
@@ -26,7 +26,7 @@ interface LoginConfig {
   password:  string;
 }
 
-/** Map role name → credentials from environment variables */
+/** Map role name -> credentials from environment variables */
 function getCredentials(role: QARole): LoginConfig {
   switch (role) {
     case 'admin':
@@ -58,7 +58,7 @@ export async function loginAs(page: Page, role: QARole = 'default'): Promise<voi
   if (!email || !password) {
     throw new Error(
       `[qa-framework/auth] Missing credentials for role "${role}". ` +
-      `Check your .env file — expected ${role.toUpperCase()}_EMAIL and ${role.toUpperCase()}_PASSWORD.`
+      `Check your .env file - expected ${role.toUpperCase()}_EMAIL and ${role.toUpperCase()}_PASSWORD.`
     );
   }
 
@@ -71,7 +71,29 @@ export async function loginAs(page: Page, role: QARole = 'default'): Promise<voi
 
   await page.goto(`${baseURL}${loginPath}`, { waitUntil: 'domcontentloaded' });
   await page.locator(emailSelector).fill(email);
-  await page.locator(passwordSelector).fill(password);
+  // Trace safety: Playwright records fill() argument values in traces, and this
+  // project runs with trace/video 'retain-on-failure'. This helper runs for every
+  // test that logs in as a role, so a fill() here would leak the plaintext password
+  // into far more failure artifacts than the one-time global setup does. 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();
   await page.waitForSelector(successSelector, { timeout: 15_000 });
 }

package/templates/automation-scaffold/fixtures/base.ts

@@ -63,7 +63,29 @@ async function reauth(browser: import('@playwright/test').Browser, stateFile: st
   try {
     await page.goto(loginPath, { waitUntil: 'load', timeout: 60_000 });
     await page.locator(emailSelector).fill(email);
-    await page.locator(passwordSelector).fill(password);
+    // Trace safety: Playwright records fill() argument values in traces, and this
+    // project runs with trace/video 'retain-on-failure'. This reauth path runs for
+    // every test whose session exceeded the TTL, so a fill() here would leak the
+    // plaintext password into far more failure artifacts than the one-time global
+    // setup does. 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();
     await page.waitForSelector(successSelector, { timeout: 30_000 });
 

package/templates/automation-scaffold/fixtures/test-helpers.ts

@@ -6,7 +6,7 @@
  */
 
 // -----------------------------------------------------------------------
-// EXEC_IDX — unique numeric seed per minute-long execution window
+// EXEC_IDX - unique numeric seed per minute-long execution window
 // -----------------------------------------------------------------------
 // Use this wherever test data needs to be unique (e.g., names, emails,
 // codes) to avoid collisions between parallel or consecutive test runs

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,20 @@ 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'];
@@ -40,37 +54,51 @@ function resolveVar(param: string | undefined, envKey: string, defaultValue: str
   return [defaultValue, 'default'];
 }
 
-function resolveAuthUsers(config: FullConfig): Set<'1' | '2'> {
+/**
+ * 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 = new Set<'1' | '2'>();
-    for (const token of explicit.split(',').map((value) => value.trim())) {
-      if (token === '1' || token === '2') {
-        resolved.add(token);
-      }
-    }
-    if (resolved.size) {
-      return resolved;
-    }
+    const resolved = explicit
+      .split(',')
+      .map((value) => value.trim())
+      .filter((value) => laneIds.includes(value));
+    if (resolved.length) return resolved;
   }
 
-  const fromProjects = new Set<'1' | '2'>();
+  const fromProjects = new Set<string>();
   for (const project of config.projects) {
     const storageState = (project.use as { storageState?: unknown } | undefined)?.storageState;
-    if (typeof storageState === 'string') {
-      if (storageState.includes('user-2')) {
-        fromProjects.add('2');
-      } else if (storageState.includes('user-1')) {
-        fromProjects.add('1');
-      }
+    if (typeof storageState !== 'string') continue;
+    for (const laneId of laneIds) {
+      if (LANE_INFO[laneId].storageState === storageState) fromProjects.add(laneId);
     }
   }
+  if (fromProjects.size) return [...fromProjects];
 
-  if (fromProjects.size) {
-    return fromProjects;
-  }
-
-  return new Set(['1']);
+  return laneIds;
 }
 
 async function dismissOnboardingFlow(page: import('@playwright/test').Page): Promise<void> {
@@ -133,7 +161,27 @@ async function loginAs(params: {
     for (let attempt = 1; attempt <= 3 && !signedIn; attempt++) {
       await page.goto(loginUrl, { waitUntil: 'load', timeout: 60_000 });
       await page.locator(emailSelector).fill(email);
-      await page.locator(passwordSelector).fill(password);
+      // 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([
@@ -167,30 +215,51 @@ async function loginAs(params: {
 }
 
 export default async function globalSetup(_config: FullConfig): Promise<void> {
-  const baseURL  = process.env.QA_BASE_URL!;
-  const authUsers = resolveAuthUsers(_config);
+  const baseURL = process.env.QA_BASE_URL!;
 
-  if (authUsers.has('1')) {
-    const [email, emailSource] = resolveVar(process.env.QA_USER_EMAIL, 'QA_USER_EMAIL', 'qa-user@example.com');
-    const [password, passwordSource] = resolveVar(process.env.QA_USER_PASSWORD, 'QA_USER_PASSWORD', 'CHANGE_ME');
-    console.log(`[global-setup] user-1 credentials from ${emailSource} / ${passwordSource}`);
-    await loginAs({
-      email,
-      password,
-      baseURL,
-      stateFile: '.auth/user-default.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.
+  //
+  // 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);
   }
 
-  if (authUsers.has('2') && process.env.QA_USER2_EMAIL && process.env.QA_USER2_PASSWORD) {
-    const [email, emailSource] = resolveVar(process.env.QA_USER2_EMAIL, 'QA_USER2_EMAIL', 'qa-user2@example.com');
-    const [password, passwordSource] = resolveVar(process.env.QA_USER2_PASSWORD, 'QA_USER2_PASSWORD', 'CHANGE_ME');
-    console.log(`[global-setup] user-2 credentials from ${emailSource} / ${passwordSource}`);
+  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: '.auth/user-2.json',
+      stateFile: lane.storageState,
     });
   }
 }