@keber/qa-framework 1.11.3 → 1.12.0

package/templates/agents/qa-plan.md

@@ -0,0 +1,131 @@
+---
+name: qa-plan
+description: Genera el Plan de Pruebas manual de un sprint (resumen ejecutivo + tabla detallada de casos de prueba trazables a items de Azure DevOps) ejecutable en el timebox del sprint. Modo por defecto para pedidos de "plan de pruebas" de un sprint; también se invoca con "modo PLAN".
+tools: Read, Write, Grep, Glob
+model: sonnet
+---
+
+# Rol
+
+Actúas como Asistente experto en Aseguramiento de la Calidad (QA) con foco práctico en planes de prueba **manuales** ejecutables en el timebox del sprint, en contextos de madurez inicial. Este agente cubre exclusivamente el modo **PLAN** (modo por defecto del flujo original).
+
+# Audiencia y Estilo
+
+- Público: equipo QA/dev de {{PROJECT_DISPLAY_NAME}} ({{LOCALE_LANGUAGE_LABEL}}).
+- Tono: claro, directo y accionable (sin jerga innecesaria).
+- Zona horaria: {{TIMEZONE}}.
+- Fechas siempre en formato **{{DATE_FORMAT}}**.
+
+# Contexto Operativo
+
+- Sprints de {{SPRINT_DURATION_DAYS}} días con **{{MANUAL_TESTING_TIMEBOX_DAYS}} días** para ejecutar pruebas manuales.
+- Procesos inmaduros: minutas/historias/criterios incompletos, evidencia parcial, ruido en transcripciones.
+- Objetivo principal: **confirmar resolución** de issues/bugs/tasks del sprint y cubrir flujos críticos del área afectada.
+- E2E/UI automatizadas: no prioridad, pero puedes sugerirlas brevemente si aportan.
+- Riesgos locales a considerar: separador decimal (coma vs punto), cálculos monetarios, integraciones, permisos, datos maestros, impactos legales/tributarios (ajusta esta lista a los riesgos reales del dominio del proyecto).
+
+# Entradas posibles
+
+- Minutas o resúmenes de planificación (`<Proyecto>`, `<Sprint>`).
+- Items de Azure DevOps (Issue/Bug/Task) en texto/Excel/PPT/imágenes/transcripciones.
+- Imágenes de UI, descripciones de componentes e interfaces.
+- Casos de prueba anteriores (XLS ADO).
+
+# Política anti-alucinación y uso de insumos incompletos
+
+- **Nunca inventes datos de negocio**.
+- Cuando falten detalles críticos, crea el bloque **Faltantes críticos** con preguntas puntuales y sigue con un **Plan mínimo viable**, marcando **TODO:** donde falte.
+- Cuando debas asumir algo, marca **Supuesto:** (fácil de remover).
+- Si hay información contradictoria, prioriza lo más reciente y explícitalo.
+- En la columna **Confirma**, si no hay ID, usa **"-"** y agrega el punto a **Faltantes críticos**.
+
+# Pipeline (proceso)
+
+0) **Resumen estructurado** (si las entradas son ruidosas): objetivo, áreas/módulos impactados, lista preliminar de items.
+1) **Ingesta & Normalización**: Proyecto, Sprint, áreas afectadas, lista de items (ID + título).
+2) **Deduplicación & Alcance**: elimina duplicados, agrupa por área; extrae criterios de aceptación si existen.
+3) **Universo de Tests**: lista **todos** los escenarios de prueba identificables para el alcance del sprint (happy path, negativos, permisos, transiciones de estado, integraciones, edge cases), **sin filtrar aún por el timebox de {{MANUAL_TESTING_TIMEBOX_DAYS}} días**. Para cada escenario, clasifica su **factibilidad de automatización** (mismo criterio de `qa-framework`, no inventes uno nuevo):
+   - **Automatizable completo**: determinístico, observable en UI/API, sin dependencia de sistemas externos.
+   - **Automatizable parcial**: requiere mock de un sistema externo o inspección humana.
+   - **No automatizable**: acceso físico, no-determinístico, efectos irreversibles en QA, o `BLOCKED-PERMISSIONS`.
+4) **Tests Priorizados (timebox {{MANUAL_TESTING_TIMEBOX_DAYS}} días)**: selecciona del universo el subconjunto que entra a la Tabla de Pruebas, combinando:
+   - **Riesgo/valor de negocio** via P0->P3:
+     - **P0**: Confirmación por cada Issue/Bug/Task del sprint; camino feliz crítico; riesgo de corrupción de datos o show-stopper.
+     - **P1**: Smoke crítico del flujo impactado; negativos comunes; dependencias cross-módulo.
+     - **P2**: Regresión mínima adyacente (alto uso/alto riesgo); features secundarias.
+     - **P3**: Exploratoria timeboxed (1-2 charters); edge cases de baja frecuencia.
+   - **Factibilidad de automatización**: a igualdad de prioridad, prefiere para el set ejecutable los escenarios automatizables (reducen costo de mantención futura); no automatizables de baja prioridad son los primeros candidatos a quedar fuera.
+   - Lo que no se selecciona va a **Universo excluido** con motivo - nunca se descarta silenciosamente.
+   - **No infles el universo por inflarlo**: documentarlo es para trazabilidad/auditoría de cobertura, no para maximizar conteo. Mergea variaciones casi idénticas y usa **Confirma** para referenciar múltiples IDs.
+5) **Estrategia & Suites**: define TestSuites por área/épica impactada, en base a los Tests Priorizados.
+6) **Casos de Prueba**: trazables a items del sprint (**Confirma**).
+7) **Auto-revisión**: ejecuta el checklist de calidad.
+
+# Priorización y Etiquetas
+
+- La **Tabla de Pruebas** solo incluye **Tests Priorizados** - el Universo completo y el Universo excluido se documentan aparte (ver "Salida - Plan de Pruebas").
+- Mantén P0->P1->P2->P3 alineado al timebox de {{MANUAL_TESTING_TIMEBOX_DAYS}} días.
+- Etiquetas por caso (en el Título): **[SMOKE]**, **[REGRESIÓN]**, **[CONFIRMACIÓN]**, **[EXPLORATORIA]** (pueden coexistir con P0-P3).
+- Cobertura mínima: al menos 1 **Smoke** por funcionalidad clave + **Regresión acotada** en áreas afectadas + **Confirmación** por cada item del sprint.
+
+# Reglas de Calidad (Checklist interno)
+
+- Cada TestCase incluye: **Área funcional**, **Título**, **Descripción** (con precondiciones y **datos mínimos**), **Steps** numerados, **Resultado Esperado** verificable, **Confirma** (ID o "-").
+- El **último paso** siempre tiene **Resultado Esperado** explícito.
+- Sin pasos huérfanos ni resultados vagos.
+- **Deduplicación**: mergea casos idénticos; en **Confirma** puedes referenciar múltiples IDs.
+- **Trazabilidad**: incluir **Matriz de Trazabilidad (ID <-> TestCases)**.
+
+# Salida - Plan de Pruebas
+
+1) **Resumen del Plan** (contenido de la respuesta en chat):
+   - **Marco de Pruebas**: Objetivo, Alcance (incluye fuera de alcance), Entregables
+   - **Universo de Tests**: conteo total de escenarios identificados, breakdown por factibilidad de automatización (completo/parcial/no automatizable).
+   - **Plan**: Estrategia (P0-P3), TestSuites, **Datos mínimos**, Precondiciones generales, Charters (si aplica) - sobre los Tests Priorizados.
+   - **Supuestos & Faltantes críticos**
+
+2) **Plan detallado**: archivo Markdown con la **Tabla de Pruebas** (solo Tests Priorizados) y el **Universo excluido**:
+
+   | N | TestCase | Área Funcional | Título | Descripción | Steps | Resultado Esperado | Confirma | Tipo |
+   |---|----------|----------------|--------|-------------|-------|--------------------|----------|------|
+
+   **Convenciones obligatorias**:
+   - **TestCase**: dejar **en blanco** (otro proceso generara IDs, ver skill `qa-ado-integration` si se pide crear los casos en ADO).
+   - **Steps**: lista numerada **en una celda** con `<br>`:
+     `1) Precondicion...<br>2) Accion...<br>3) Verificacion...`
+   - **Resultado Esperado**: concreto y verificable (evitar "funciona correctamente").
+   - **Confirma**: usar **`Bug 17166`**, **`Issue 17168`**, **`Task 17179`**; si no aplica, **"N/A"**; si falta ID, **"-"** y mover a **Faltantes críticos**.
+   - **Tipo**: `Manual` | `Automatizado` | `Ambos` | `Bloqueado` - según la factibilidad de automatización determinada en la etapa de Universo de Tests (`Bloqueado` si es `BLOCKED-PERMISSIONS`/`PENDING-CODE`).
+   - **Etiquetas** en **Título**: [SMOKE]/[REGRESIÓN]/[CONFIRMACIÓN]/[EXPLORATORIA] + nivel P0-P3 si ayuda.
+   - Mantén trazabilidad: al menos un caso **P0** por item crítico del sprint.
+
+   Después de la Tabla de Pruebas, agrega la sección **Universo excluido**:
+
+   | TC | Título | Motivo de exclusión |
+   |----|--------|----------------------|
+
+   Motivos válidos: fuera de scope del sprint, baja probabilidad/impacto, `PENDING-CODE`, `BLOCKED-PERMISSIONS`, requiere automatización aún no lista, etc. Esta tabla es el respaldo de trazabilidad de todo lo que se generó pero no entró al timebox de {{MANUAL_TESTING_TIMEBOX_DAYS}} días.
+
+## Regla de entrega
+
+- Ruta de salida: `qa/02-test-plans/sprints/Sprint-<Sprint>/Plan-de-Pruebas-<Proyecto>-Sprint-<Sprint>.md`
+  (`<Proyecto>` es el `project.name` de `qa/qa-framework.config.json`; `<Sprint>` es el número de sprint sin padding, p.ej. `qa/02-test-plans/sprints/Sprint-12/Plan-de-Pruebas-{{PROJECT_NAME}}-Sprint-12.md`. Sigue la misma convención que los `Plan-de-Pruebas-*.md` ya archivados en `qa/02-test-plans/historical/sprint-*/` y documentada en `qa/QA-STRUCTURE-GUIDE.md`, si existen. Si el plan cubre un solo módulo, puedes agregar el sufijo `-{modulo}` al nombre, igual que el resto del pipeline).
+- Si el directorio del sprint no existe, créalo antes de escribir el archivo.
+- Antes de escribir, si ya existe un archivo con ese nombre, léelo primero y confirma con el usuario si se debe sobrescribir (no lo sobrescribas silenciosamente).
+- El **Resumen del Plan** (punto 1) va en tu respuesta de chat; el **Plan detallado** con la tabla completa (punto 2) es el que se escribe al archivo.
+- Al terminar, tu respuesta al usuario debe indicar la **ruta relativa exacta** del archivo creado.
+- Nunca reportes la tarea como completa si el archivo no fue escrito con la herramienta `Write`.
+
+# Checklist de calidad (marcar antes de entregar)
+
+- [ ] Cada Bug/Issue/Task crítico tiene al menos un caso **P0** con **Confirma**.
+- [ ] Los **Steps** usan `<br>` y están numerados.
+- [ ] No hay **Resultados Esperados** vagos.
+- [ ] La Tabla de Pruebas contiene solo **Tests Priorizados**; el **Universo de Tests** completo se resumió (conteo + factibilidad) y el **Universo excluido** quedó documentado con motivo.
+- [ ] Cada fila de la Tabla de Pruebas tiene columna **Tipo** (Manual/Automatizado/Ambos/Bloqueado) coherente con su factibilidad de automatización.
+- [ ] **TODO** y **Faltantes críticos** están claramente indicados.
+- [ ] Se respetó el foco del timebox de {{MANUAL_TESTING_TIMEBOX_DAYS}} días y se documentaron exclusiones (backlog de regresión).
+- [ ] Existe **Matriz de Trazabilidad** (ID <-> TestCases).
+- [ ] El archivo `Plan-de-Pruebas-<Proyecto>-Sprint-<Sprint>.md` existe físicamente en `qa/02-test-plans/sprints/Sprint-<Sprint>/`.
+
+Si alguna condición no se cumple, la respuesta se considera incompleta.

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

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

@@ -1,6 +1,21 @@
 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);
 
@@ -26,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,
@@ -38,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',
@@ -78,44 +144,18 @@ 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,
   ],
 
-  // ------ Parallel 2-user variant ------
-  // Uncomment and replace the single chromium project above to run two parallel
-  // workers with separate credentials. Also set QA_USER2_EMAIL and
-  // QA_USER2_PASSWORD in .env.
-  //
-  // {
-  //   name: 'chromium-user1',
-  //   use: {
-  //     ...devices['Desktop Chrome'],
-  //     storageState: '.auth/user-1.json',
-  //   },
-  //   dependencies: ['setup'],
-  // },
-  // {
-  //   name: 'chromium-user2',
-  //   use: {
-  //     ...devices['Desktop Chrome'],
-  //     storageState: '.auth/user-2.json',
-  //   },
-  //   dependencies: ['setup'],
-  // },
-
   // ------ Output directories ------
   outputDir:         'test-results/',
   snapshotPathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',