@keber/qa-framework 1.10.0 → 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.
@@ -10,6 +10,50 @@
 # -----------------------------------------------------------------------
 QA_BASE_URL=https://your-app.qa.example.com
 
+# -----------------------------------------------------------------------
+# Session and login resilience
+# -----------------------------------------------------------------------
+QA_SESSION_TTL_MS=7200000
+# Optional path to a server-side logout endpoint if the app exposes one.
+# QA_LOGOUT_PATH=/logout
+
+# -----------------------------------------------------------------------
+# 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
+
+# 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
 # These selectors allow the framework to work with any login form.
@@ -42,15 +86,20 @@ 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
 # -----------------------------------------------------------------------
 # CI=true           # Set automatically by most CI systems
 # ADO_SYNC_DISABLED=false   # Set to true to skip ADO reporter in local runs
+
+# -----------------------------------------------------------------------
+# Playwright Service  (optional - only needed for cloud or self-hosted grid)
+# -----------------------------------------------------------------------
+# PLAYWRIGHT_SERVICE_URL=wss://eastus.api.playwright.microsoft.com/accounts/<your-id>/browsers

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

@@ -0,0 +1,130 @@
+/**
+ * fixtures/base.ts
+ *
+ * Playwright test wrapper with TTL-aware session refresh.
+ * Import this file instead of `@playwright/test` when the app uses a
+ * server-side session that may expire during long runs.
+ */
+
+import { test as base, devices } from '@playwright/test';
+import { SESSION_TTL_MS } from '../playwright.config';
+import * as dotenv from 'dotenv';
+import * as fs from 'fs';
+import * as path from 'path';
+
+dotenv.config();
+
+const authTimestamps = new Map<string, number>();
+
+function stateFileForProject(storageState: unknown): string {
+  if (typeof storageState === 'string' && storageState) {
+    return path.resolve(__dirname, '..', storageState);
+  }
+  return path.resolve(__dirname, '../.auth/user-default.json');
+}
+
+function credentialsForState(stateFile: string): { email: string; password: string } {
+  if (stateFile.includes('user-2')) {
+    return {
+      email: process.env.QA_USER2_EMAIL ?? '',
+      password: process.env.QA_USER2_PASSWORD ?? '',
+    };
+  }
+
+  return {
+    email: process.env.QA_USER_EMAIL ?? '',
+    password: process.env.QA_USER_PASSWORD ?? '',
+  };
+}
+
+function lastAuthTime(stateFile: string): number {
+  if (!authTimestamps.has(stateFile)) {
+    try {
+      authTimestamps.set(stateFile, fs.statSync(stateFile).mtimeMs);
+    } catch {
+      authTimestamps.set(stateFile, 0);
+    }
+  }
+  return authTimestamps.get(stateFile) ?? 0;
+}
+
+async function reauth(browser: import('@playwright/test').Browser, stateFile: string): Promise<void> {
+  const { email, password } = credentialsForState(stateFile);
+  const baseURL = process.env.QA_BASE_URL ?? '';
+  const loginPath = process.env.QA_LOGIN_PATH ?? '/login';
+  const emailSelector = process.env.QA_LOGIN_EMAIL_SELECTOR ?? 'input[type="email"]';
+  const passwordSelector = process.env.QA_LOGIN_PASSWORD_SELECTOR ?? 'input[type="password"]';
+  const submitSelector = process.env.QA_LOGIN_SUBMIT_SELECTOR ?? 'button[type="submit"]';
+  const successSelector = process.env.QA_LOGIN_SUCCESS_SELECTOR ?? '.dashboard, .main-content, [data-testid="app-shell"]';
+
+  const context = await browser.newContext({ ...devices['Desktop Chrome'], baseURL });
+  const page = await context.newPage();
+
+  try {
+    await page.goto(loginPath, { 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'. 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 });
+
+    const dir = path.dirname(stateFile);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    await context.storageState({ path: stateFile });
+    authTimestamps.set(stateFile, Date.now());
+    console.log(`[session-refresh] storageState renewed: ${stateFile}`);
+  } finally {
+    await context.close();
+  }
+}
+
+export const test = base.extend<{ authStatePath: string }>({
+  authStatePath: async ({}, use, testInfo) => {
+    await use(stateFileForProject(testInfo.project.use.storageState));
+  },
+
+  context: async ({ browser }, use, testInfo) => {
+    const stateFile = stateFileForProject(testInfo.project.use.storageState);
+    if (Date.now() - lastAuthTime(stateFile) > SESSION_TTL_MS) {
+      await reauth(browser, stateFile).catch((error) => {
+        console.error(`[session-refresh] reauth failed: ${(error as Error).message}`);
+      });
+    }
+
+    const context = await browser.newContext({
+      ...devices['Desktop Chrome'],
+      storageState: stateFile,
+      baseURL: process.env.QA_BASE_URL,
+    });
+
+    await use(context);
+    await context.close();
+  },
+});
+
+export { expect } from '@playwright/test';
+export type { Page, Browser, BrowserContext } from '@playwright/test';

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