@keber/qa-framework 1.0.4

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

@@ -0,0 +1,85 @@
+/**
+ * fixtures/test-helpers.ts
+ *
+ * Utility functions used across all spec files.
+ * Import only what you need; keep specs self-contained.
+ */
+
+// -----------------------------------------------------------------------
+// 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
+// without relying on random values that are impossible to correlate.
+//
+// Example:
+//   const idx = execIdx();    // e.g., 42591
+//   const name = `QA-Supplier-${idx}`;
+// -----------------------------------------------------------------------
+export function execIdx(): number {
+  return Math.floor(Date.now() / 60_000) % 100_000;
+}
+
+/** Date string formatted as YYYY-MM-DD in local time. */
+export function todayISO(): string {
+  const d = new Date();
+  return d.toISOString().slice(0, 10);
+}
+
+/** Date string formatted as DD/MM/YYYY (common in Spanish-language UIs). */
+export function todayDMY(): string {
+  const d = new Date();
+  const dd = String(d.getDate()).padStart(2, '0');
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  return `${dd}/${mm}/${d.getFullYear()}`;
+}
+
+/** Future date offset by `days` from today, formatted as YYYY-MM-DD. */
+export function futureDateISO(days: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() + days);
+  return d.toISOString().slice(0, 10);
+}
+
+// -----------------------------------------------------------------------
+// 3-layer email assertion helper
+// -----------------------------------------------------------------------
+// Use this when asserting an email field value to avoid brittle exact-match
+// assertions that break when display format changes.
+//
+// Example:
+//   await assertEmailContains(
+//     await page.locator('#email-cell').textContent() ?? '',
+//     process.env.QA_USER_EMAIL!
+//   );
+// -----------------------------------------------------------------------
+export function assertEmailContains(
+  actual: string,
+  expected: string
+): void {
+  const localPart = expected.split('@')[0];
+  const domain    = expected.split('@')[1];
+  if (!actual.includes(localPart)) {
+    throw new Error(`Email assertion failed: expected local part "${localPart}" in "${actual}"`);
+  }
+  if (!actual.includes(domain)) {
+    throw new Error(`Email assertion failed: expected domain "${domain}" in "${actual}"`);
+  }
+  if (!actual.includes('@')) {
+    throw new Error(`Email assertion failed: no "@" symbol found in "${actual}"`);
+  }
+}
+
+// -----------------------------------------------------------------------
+// Unique test string builder
+// -----------------------------------------------------------------------
+// Combines a readable prefix with EXEC_IDX for easy triage in QA data.
+// -----------------------------------------------------------------------
+export function uniqueName(prefix: string): string {
+  return `${prefix}-${execIdx()}`;
+}
+
+/** Unique email address for test isolation (uses execIdx). */
+export function uniqueEmail(domain = 'qa-test.example.com'): string {
+  return `qa-user-${execIdx()}@${domain}`;
+}

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

@@ -0,0 +1,106 @@
+/**
+ * global-setup.ts
+ *
+ * Runs ONCE before all test files.
+ * Logs in as the default QA user and saves storageState so each test
+ * doesn't need to repeat the login flow.
+ *
+ * For multi-role projects:
+ *   - Add additional loginAs() calls below, one per role.
+ *   - Save each to `.auth/user-{role}.json`.
+ *   - 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
+ *
+ * See .env.example for all supported variables.
+ */
+
+import { chromium, FullConfig } from '@playwright/test';
+import * as dotenv from 'dotenv';
+import * as path from 'path';
+import * as fs from 'fs';
+
+dotenv.config();
+
+/** Perform login and persist storageState to disk. */
+async function loginAs(params: {
+  email:             string;
+  password:          string;
+  baseURL:           string;
+  loginPath?:        string;
+  emailSelector?:    string;
+  passwordSelector?: string;
+  submitSelector?:   string;
+  successSelector?:  string;
+  stateFile:         string;
+}): Promise<void> {
+  const {
+    email,
+    password,
+    baseURL,
+    loginPath        = process.env.QA_LOGIN_PATH        ?? '/login',
+    emailSelector    = process.env.QA_LOGIN_EMAIL_SELECTOR    ?? 'input[type="email"]',
+    passwordSelector = process.env.QA_LOGIN_PASSWORD_SELECTOR ?? 'input[type="password"]',
+    submitSelector   = process.env.QA_LOGIN_SUBMIT_SELECTOR   ?? 'button[type="submit"]',
+    successSelector  = process.env.QA_LOGIN_SUCCESS_SELECTOR  ?? '.dashboard, .main-content, [data-testid="app-shell"]',
+    stateFile,
+  } = params;
+
+  const browser = await chromium.launch();
+  const context = await browser.newContext();
+  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 });
+
+    // Ensure .auth/ directory exists
+    const dir = path.dirname(stateFile);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    await context.storageState({ path: stateFile });
+    console.log(`[global-setup] storageState saved: ${stateFile}`);
+  } finally {
+    await browser.close();
+  }
+}
+
+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!;
+
+  // --- 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',
+  // });
+  //
+  // await loginAs({
+  //   email:     process.env.QA_READONLY_EMAIL!,
+  //   password:  process.env.QA_READONLY_PASSWORD!,
+  //   baseURL,
+  //   stateFile: '.auth/user-readonly.json',
+  // });
+}

package/templates/automation-scaffold/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{PROJECT_NAME}}-qa-e2e",
+  "version": "1.0.0",
+  "private": true,
+  "description": "E2E Playwright test suite for {{PROJECT_NAME}}",
+  "scripts": {
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "test:debug": "playwright test --debug",
+    "test:ui": "playwright test --ui",
+    "test:p0": "playwright test --grep @P0",
+    "test:p1": "playwright test --grep \"@P0|@P1\"",
+    "test:module": "playwright test --grep {{MODULE_PATTERN}}",
+    "report": "playwright show-report",
+    "validate": "npx keber/qa-framework validate"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.40.0",
+    "dotenv": "^16.0.0"
+  },
+  "optionalDependencies": {
+    "@alex_neo/playwright-azure-reporter": "^2.0.0"
+  }
+}

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

@@ -0,0 +1,85 @@
+import { defineConfig, devices } from '@playwright/test';
+import * as dotenv from 'dotenv';
+dotenv.config();
+
+// -------------------------------------------------------------------
+// Validate required environment variables at config load time
+// -------------------------------------------------------------------
+const required = ['QA_BASE_URL', 'QA_USER_EMAIL', 'QA_USER_PASSWORD'];
+for (const key of required) {
+  if (!process.env[key]) {
+    throw new Error(`[qa-framework] Missing required env var: ${key}. Check your .env file.`);
+  }
+}
+
+// Optional: Azure DevOps reporter configuration
+// Uncomment and fill in when ADO integration is enabled.
+// import { AzureReporter } from '@alex_neo/playwright-azure-reporter';
+// const adoConfig = {
+//   token:           process.env.AZURE_TOKEN!,
+//   planId:          Number(process.env.ADO_PLAN_ID),
+//   projectName:     process.env.ADO_PROJECT_NAME!,
+//   orgUrl:          process.env.ADO_ORG_URL!,
+//   testRunTitle:    `[Automated] Sprint {{NNN}} — ${new Date().toISOString().slice(0, 10)}`,
+//   publishResultsOnFailure: true,
+//   isDisabled:      process.env.ADO_SYNC_DISABLED === 'true',
+// };
+
+export default defineConfig({
+  // ------ Test discovery ------
+  testDir:  '.',
+  // Use any subdir pattern your project standardizes on, e.g.:
+  // testMatch: ['**/*.spec.ts'],
+
+  // ------ Parallelism ------
+  // Keep fullyParallel:false when tests share storageState / session data.
+  fullyParallel: false,
+  workers:       1,
+
+  // ------ Retry strategy ------
+  retries: process.env.CI ? 1 : 0,
+
+  // ------ Reporter ------
+  reporter: [
+    ['html',  { open: 'never' }],
+    ['list'],
+    // Uncomment for ADO:
+    // ['@alex_neo/playwright-azure-reporter', adoConfig],
+  ],
+
+  // ------ Global settings ------
+  use: {
+    baseURL:            process.env.QA_BASE_URL,
+    headless:           true,
+    screenshot:         'only-on-failure',
+    video:              'retain-on-failure',
+    trace:              'retain-on-failure',
+    actionTimeout:      15_000,
+    navigationTimeout:  30_000,
+  },
+
+  // ------ Auth setup ------
+  // global-setup.ts logs in once and saves storageState per role.
+  globalSetup: './global-setup.ts',
+
+  // ------ Projects ------
+  projects: [
+    {
+      name: 'setup',
+      use:  { ...devices['Desktop Chrome'] },
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'chromium',
+      use:  {
+        ...devices['Desktop Chrome'],
+        storageState: '.auth/user-default.json',
+      },
+      dependencies: ['setup'],
+    },
+  ],
+
+  // ------ Output directories ------
+  outputDir:         'test-results/',
+  snapshotPathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',
+});

package/templates/defect-report.md

@@ -0,0 +1,101 @@
+# Bug Report — DEF-{{NNN}}: {{Short Title}}
+
+| Field | Value |
+|-------|-------|
+| Bug ID | DEF-{{NNN}} |
+| Title | {{Short title (max 80 chars)}} |
+| Severity | Critical / High / Medium / Low |
+| Priority | P0 / P1 / P2 / P3 |
+| Status | Open / In Progress / Resolved / Closed |
+| Assigned to | {{Developer or "Unassigned"}} |
+| Module | {{Module name}} |
+| Submodule | {{Submodule name}} |
+| Environment | QA ({{QA_BASE_URL}}) |
+| Browser | Chromium {{version}} |
+| Date reported | YYYY-MM-DD |
+| ADO WI | #{ADO_WORK_ITEM_ID} (if ADO enabled) |
+| Related TCs | TC-{{M}}-{{S}}-{{NNN}} |
+
+---
+
+## Description
+
+{{1-2 sentences describing what the bug is and where it occurs}}
+
+---
+
+## Steps to Reproduce
+
+| Step | Action |
+|------|--------|
+| 1 | Navigate to `{{QA_BASE_URL}}/{{path}}` as `{{role}}` |
+| 2 | {{action}} |
+| 3 | {{action}} |
+| 4 | Observe `{{element}}` |
+
+---
+
+## Expected Result
+
+{{What should happen according to business rules RN-{{M}}-{{NNN}}}}
+
+---
+
+## Actual Result
+
+{{What actually happens}}
+
+---
+
+## Evidence
+
+- Screenshot: `qa/07-automation/e2e/diagnosis/{{NNN}}-{{bug-slug}}.png`
+- Test output: (link to execution report if captured automatically)
+
+---
+
+## Root Cause Analysis
+
+{{If known: explain why this happens. If unknown: "Under investigation"}}
+
+---
+
+## Fix Suggestion
+
+{{If known: describe the fix. Example: "Set IND_CORREO default to true in C# model constructor"}}
+
+---
+
+## Impact on Automation
+
+| TC ID | Current test state | Impact |
+|-------|-------------------|--------|
+| TC-{{M}}-{{S}}-{{NNN}} | `test.skip()` added | Test will remain skipped until fix is deployed |
+| TC-{{M}}-{{S}}-{{NNN}} | Assertion adjusted | `toBeFalsy()` documents buggy default |
+
+**Test skip command added**:
+```typescript
+test.skip(true,
+  'DEF-{{NNN}}: {{description}}. Reactivate when ADO #{{WI_ID}} is resolved.'
+);
+```
+
+---
+
+## Reactivation Instructions
+
+When this bug is fixed:
+1. Remove `test.skip()` from TC-{{M}}-{{S}}-{{NNN}} in `{{spec-file}}`
+2. Restore original assertion (e.g., `toBeTruthy()`)
+3. Run the test at least 2 times with different EXEC_IDX values to confirm stability
+4. Move this file to `06-defects/resolved/`
+
+---
+
+## Changelog
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0 | YYYY-MM-DD | Bug reported |
+| 1.1 | YYYY-MM-DD | Root cause identified |
+| 1.2 | YYYY-MM-DD | Fix deployed, verified |

package/templates/execution-report.md

@@ -0,0 +1,116 @@
+# Execution Report — {{MODULE_NAME}}
+
+**Report ID**: EXEC-{{MODULE}}-{{YYYYMMDD}}-{{NNN}}
+**Sprint / Release**: Sprint {{NNN}}
+**Execution type**: Automated / Manual / Mixed
+**Executor**: (agent name or analyst name)
+**Environment**: QA — `{{QA_BASE_URL}}`
+**Date**: YYYY-MM-DD HH:MM UTC
+**Playwright version**: {{version}} (if automated)
+**ADO Test Plan**: #{ADO_PLAN_ID} (if ADO enabled)
+
+---
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total TCs | {{N}} |
+| Passed | {{N}} |
+| Failed | {{N}} |
+| Skipped | {{N}} |
+| Pass rate | {{N}}% |
+| Execution time | {{Nm Ns}} |
+
+### Overall Result: ✅ PASS / ❌ FAIL / ⚠️ PARTIAL
+
+---
+
+## Results by Submodule
+
+| Submodule | Total | Pass | Fail | Skip | Notes |
+|-----------|-------|------|------|------|-------|
+| {{submodule}} | | | | | |
+
+---
+
+## Detailed Results
+
+| TC-ID | Title | Priority | Result | Duration | Notes |
+|-------|-------|----------|--------|----------|-------|
+| TC-{{M}}-{{S}}-001 | {{title}} | P0 | ✅ Pass | {{Xs}} | |
+| TC-{{M}}-{{S}}-002 | {{title}} | P0 | ❌ Fail | {{Xs}} | DEF-{{NNN}} opened |
+| TC-{{M}}-{{S}}-003 | {{title}} | P1 | ⏭️ Skip | — | DEF-{{NNN}} blocks |
+
+---
+
+## Failures Detail
+
+### TC-{{M}}-{{S}}-{{NNN}} — {{Title}}
+
+**Error**:
+```
+{{Error message or assertion failure output}}
+```
+
+**Screenshot**: `{{path-to-screenshot-if-any}}`
+
+**Action taken**: DEF-{{NNN}} opened / escalated to Dev.
+
+---
+
+## Open Defects
+
+| DEF-ID | Title | Severity | Linked TC | Status |
+|--------|-------|----------|-----------|--------|
+| DEF-{{NNN}} | {{title}} | High | TC-{{M}}-{{S}}-{{NNN}} | Open |
+
+---
+
+## Skipped Tests
+
+| TC-ID | Reason |
+|-------|--------|
+| TC-{{M}}-{{S}}-{{NNN}} | DEF-{{NNN}} — {{short description}} |
+
+---
+
+## Environment Used
+
+```
+QA_BASE_URL={{QA_BASE_URL}}
+Browser: Chromium {{version}}
+Viewport: 1280x720
+Workers: 1 (sequential, shared auth state)
+Auth state: .auth/user-{{role}}.json (not committed)
+```
+
+> Credentials and tokens are NEVER logged in execution reports.
+
+---
+
+## Recommendations
+
+1. **DEF-{{NNN}}**: High priority — unblocks {{N}} skipped P0 tests.
+2. **Flaky risk**: TC-{{M}}-{{S}}-{{NNN}} passed on retry — investigate timing issue.
+3. **Coverage gap**: {{submodule}} `{{scenario}}` has no automated coverage — manual execution required.
+
+---
+
+## Artifacts
+
+| Artifact | Location |
+|----------|----------|
+| Playwright HTML report | `playwright-report/index.html` |
+| Test results JSON | `test-results/` |
+| Spec files | `qa/07-automation/e2e/{{module}}/` |
+| ADO sync log | (if ADO enabled — see `integrations/ado-powershell/` output) |
+
+---
+
+## Sign-off
+
+| Role | Name | Date |
+|------|------|------|
+| QA Analyst | | |
+| Tech Lead | | |

package/templates/session-summary.md

@@ -0,0 +1,73 @@
+# Session Summary — {{SESSION_TITLE}}
+
+**Date**: YYYY-MM-DD
+**Session type**: Module Analysis / Spec Generation / Test Plan / Automation / ADO Sync / Maintenance
+**Agent instruction used**: `agent-instructions/0{{N}}-{{name}}.md`
+**Module / Submodule**: {{MODULE_NAME}} / {{SUBMODULE_NAME}} (or "N/A")
+**Duration**: ~{{N}} minutes
+
+---
+
+## Objective
+
+{{1-2 sentences describing what this session aimed to accomplish}}
+
+---
+
+## Completed
+
+| Item | Output file | Status |
+|------|-------------|--------|
+| {{artifact type}} | `{{relative/path/to/file}}` | ✅ Done |
+| {{artifact type}} | `{{relative/path/to/file}}` | ✅ Done |
+
+---
+
+## Decisions Made
+
+| Decision | Chosen option | Rationale |
+|----------|--------------|-----------|
+| {{e.g., "TC priority assignment for..."}} | P{{N}} | {{reason}} |
+| {{e.g., "Skip automation for..."}} | Not automated | {{reason (external system, PDF, etc.)}} |
+
+---
+
+## Open Items for Next Session
+
+| Item | Priority | Notes |
+|------|----------|-------|
+| {{task}} | High / Medium / Low | {{context}} |
+
+---
+
+## Defects Discovered
+
+| DEF-ID | Title | Severity | File opened? |
+|--------|-------|----------|--------------|
+| DEF-{{NNN}} | {{title}} | {{severity}} | Yes — `qa/06-defects/open/DEF-{{NNN}}.md` |
+
+---
+
+## Files Modified
+
+| Path | Action |
+|------|--------|
+| `{{path}}` | Created / Updated |
+
+---
+
+## Continuation Prompt
+
+To resume this work in a new session, use:
+
+```
+Using keber/qa-framework agent instructions (agent-instructions/0{{N}}-{{name}}.md),
+continue working on {{MODULE_NAME}} > {{SUBMODULE_NAME}}.
+
+Last completed: {{last artifact}}
+Next step: {{next specific task}}
+
+Relevant files:
+- {{file 1}}
+- {{file 2}}
+```

package/templates/specification/00-inventory.md

@@ -0,0 +1,81 @@
+# MODULE: {{MODULE_NAME}} — Submodule: {{SUBMODULE_NAME}}
+
+> **Template version**: 1.0 | Replace all `{{...}}` with actual values before committing.
+
+| Field | Value |
+|-------|-------|
+| Module code | {{MODULE_CODE}} |
+| Submodule code | {{SUBMODULE_CODE}} |
+| Primary URL | `{{QA_BASE_URL}}/{{SUBMODULE_PATH}}` |
+| Secondary URLs | `{{URL_2}}`, `{{URL_3}}` |
+| Status | Active |
+| Deployed | YYYY-MM-DD |
+| Last analyzed | YYYY-MM-DD |
+
+---
+
+## Menu Location
+
+| Level | Label | URL |
+|-------|-------|-----|
+| 1 | {{TOP_MENU}} | — |
+| 2 | {{SUBMENU}} | `{{URL}}` |
+
+---
+
+## UI Elements
+
+### Index / List View (`{{INDEX_URL}}`)
+
+| Element | Type | Notes |
+|---------|------|-------|
+| {{field-name}} | text / select / checkbox / date / button | {{notes}} |
+| Search input | text | Filters table by {{field}} |
+| Pagination | paginator | N records per page |
+| Export button | button | Generates {{format}} file |
+
+### Create / Edit Form (`{{FORM_URL}}`)
+
+| Field | Type | Required | Validation |
+|-------|------|----------|------------|
+| {{field-name}} | text | Yes/No | {{rule, e.g., max 100 chars}} |
+| {{field-name}} | select | Yes/No | Options loaded from API |
+| {{field-name}} | date | No | Future dates only |
+
+---
+
+## API Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/{{endpoint}}` | Load list with pagination |
+| POST | `/api/{{endpoint}}` | Create new record |
+| PUT | `/api/{{endpoint}}` | Update existing record |
+| DELETE | `/api/{{endpoint}}` | Delete / deactivate record |
+| GET | `/api/{{endpoint}}` | Load options for dropdown |
+
+---
+
+## Key Identifiers
+
+| Element | Selector / Identifier | Notes |
+|---------|----------------------|-------|
+| {{button}} | {{selector}} | {{usage}} |
+| {{table}} | {{selector}} | {{usage}} |
+| {{modal}} | {{selector}} | Opens on: {{trigger}} |
+
+---
+
+## Related Submodules
+
+| Submodule | Relationship | Notes |
+|-----------|-------------|-------|
+| {{submodule}} | Provides data to this module | Dropdown populated from {{API}} |
+| {{submodule}} | Depends on data from this module | — |
+
+---
+
+## Notes
+
+- {{any technical notes discovered during analysis}}
+- {{gotchas or non-obvious behaviors}}