@keber/qa-framework 1.0.4

package/docs/folder-structure-guide.md

@@ -0,0 +1,291 @@
+# docs/folder-structure-guide.md
+
+## `qa/` Directory Structure — Full Reference Guide
+
+This document explains the purpose, contents, and conventions for every folder in the `qa/` directory.
+
+---
+
+## Overview
+
+```
+qa/
+├── README.md                    ← Living master index (project-maintained)
+├── QA-STRUCTURE-GUIDE.md        ← Copy of this guide (installed by framework)
+├── qa-framework.config.json     ← Project configuration
+│
+├── 00-guides/                   ← Process guides and agent instructions
+├── 00-standards/                ← Naming conventions and artifact templates
+├── 01-specifications/           ← Functional specifications per module
+├── 02-test-plans/               ← Test plans (scope + priority decisions)
+├── 03-test-cases/               ← Standalone test case documents
+├── 04-test-data/                ← Test data definitions and factories
+├── 05-test-execution/           ← Execution reports and results
+├── 06-defects/                  ← Defect tracking (optional)
+├── 07-automation/               ← Automation code (Playwright, etc.)
+└── 08-azure-integration/        ← Azure DevOps integration (optional)
+```
+
+---
+
+## 00-guides/
+
+**Purpose**: Process guides and operating instructions for both humans and agents.
+
+**Installed by framework** (not project-maintained):
+
+| File | Contents |
+|---|---|
+| `README.md` | Index with reading order by persona |
+| `AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md` | How to analyze a module (4-phase process) |
+| `AGENT-INSTRUCTIONS-SPEC-GENERATION.md` | How to produce the 6-file spec set |
+| `AGENT-INSTRUCTIONS-TEST-CASES.md` | How to write test case tables |
+| `AGENT-INSTRUCTIONS-AUTOMATION.md` | How to write Playwright E2E tests |
+| `AGENT-INSTRUCTIONS-ADO-INTEGRATION.md` | How to sync results with Azure DevOps |
+| `AGENT-INSTRUCTIONS-MAINTENANCE.md` | How to update QA artifacts after code changes |
+
+**Project-maintained** (added over time):
+- `DEBUG-ARTIFACTS-POLICY.md` — where to save screenshots and debug output
+- `NOTAS-TECNICAS-PLAYWRIGHT.md` — project-specific Playwright gotchas
+- `RETROSPECTIVA-*.md` — session debug chronicles (optional, high value)
+
+---
+
+## 00-standards/
+
+**Purpose**: Non-negotiable naming conventions and artifact format standards.
+
+**Installed by framework**:
+
+| File | Contents |
+|---|---|
+| `naming-conventions.md` | All ID patterns (TC-*, RN-*, FL-*, DEF-*, folder names) |
+| `test-case-template.md` | Full TC document template |
+| `bug-report-template.md` | Full defect document template |
+| `test-data-guidelines.md` | How to structure test data, credential policy |
+| `execution-report-template.md` | How to write an execution report |
+
+---
+
+## 01-specifications/
+
+**Purpose**: Functional specifications — the primary source of truth for what the application does and what must be tested.
+
+**Structure**:
+```
+01-specifications/
+├── README.md                    ← Index of all modules
+├── shared/                      ← Shared artifacts (sitemap, shared templates)
+│   ├── ui-menu-map.md           ← Auto-generated from playwright session
+│   └── Instrucciones-analisis.md ← Checklist template for module analysis
+│
+└── module-{module-name}/
+    ├── README.md                ← Module index (submodule table + E2E flow)
+    └── submodule-{name}/
+        ├── 00-inventory.md      ← UI elements, routes, APIs, fields
+        ├── 01-business-rules.md ← RN-* rules the system enforces
+        ├── 02-workflows.md      ← FL-* user flow diagrams (Mermaid/ASCII)
+        ├── 03-roles-permissions.md ← Role matrix
+        ├── 04-test-data.md      ← Data shapes and prerequisites
+        └── 05-test-scenarios.md ← TC-* test cases with priority and steps
+```
+
+**Naming rules**:
+- Module directory: `module-{kebab-name}` (e.g., `module-operacion`)
+- Submodule directory: `submodule-{kebab-name}` (e.g., `submodule-aprobacion`)
+- Module code: 2-6 uppercase letters (e.g., `OPER`, `PERS`, `ARCF`)
+- TC ID: `TC-{MODULE}-{SUBMODULE}-{3-digit}` (e.g., `TC-OPER-CAT-001`)
+
+**TC target per submodule**: 50–85 test cases is considered a well-analyzed submodule.
+
+---
+
+## 02-test-plans/
+
+**Purpose**: Documents that define the scope, priorities, and approach for testing a module or sprint.
+
+```
+02-test-plans/
+├── README.md
+├── automated/
+│   └── {module}-automated-test-plan.md
+└── manual/
+    ├── {module}-manual-test-plan.md
+    └── exploratory/
+        └── {module}-exploratory-session.md
+```
+
+A test plan specifies:
+- Which TCs from `01-specifications/` are in scope
+- Priority assignment (P0/P1/P2/P3)
+- Which TCs will be automated vs manual
+- Estimated automation feasibility (fully/partially/not automatable)
+- ADO Test Suite mapping (if ADO is enabled)
+
+---
+
+## 03-test-cases/
+
+**Purpose**: Standalone, detailed test case documents when more depth is needed than `05-test-scenarios.md` provides.
+
+Most projects will have sparse content here — the 05-test-scenarios.md files inside specs contain the TC tables. This folder is for cases that are too complex to fit in a table row.
+
+```
+03-test-cases/
+├── README.md
+├── automated/
+│   └── TC-{ID}-{title}.md
+└── manual/
+    └── TC-{ID}-{title}.md
+```
+
+---
+
+## 04-test-data/
+
+**Purpose**: All test data definitions, no credentials.
+
+```
+04-test-data/
+├── README.md
+├── users.md         ← Test user definitions (roles, env var references, NOT passwords)
+├── fixtures/        ← Static data files (JSON/Markdown)
+├── factories/       ← Dynamic data generation patterns (Markdown or TS files)
+└── seeders/         ← DB/API seed scripts for complex test setup
+```
+
+**Critical rules**:
+- Never put real passwords in this folder
+- User tables list roles + env var names, not actual credentials
+- Use `process.env.QA_USER_EMAIL` style references throughout
+- For test data that requires unique values per run, document the `EXEC_IDX` pattern
+
+---
+
+## 05-test-execution/
+
+**Purpose**: Evidence of test runs — reports, results, and screenshots.
+
+```
+05-test-execution/
+├── README.md
+├── automated/
+│   ├── {YYYY-MM-DD_HH-MM-SS_desc}.md    ← Execution report (human-readable summary)
+│   └── test-results/                    ← Playwright output (gitignored if large)
+│       └── .last-run.json
+└── manual/
+    ├── exploratory/
+    │   └── {YYYY-MM-DD_desc}.md
+    └── regression/
+```
+
+**Execution report format** (see `00-standards/execution-report-template.md`):
+- Summary table: total/pass/skip/fail + duration
+- Per-test table with individual times
+- Defect links for any skipped tests
+- Env var commands sanitized with `<PLACEHOLDER>`
+
+---
+
+## 06-defects/
+
+**Purpose**: Defect tracking. Optional when Azure DevOps is used.
+
+```
+06-defects/
+├── README.md
+├── active/
+│   └── DEF-{NNN}-{slug}.md
+└── resolved/
+    └── DEF-{NNN}-{slug}.md
+```
+
+**Decision guide**:
+- ADO enabled → use ADO Work Items. `06-defects/` contains lightweight references only
+- ADO disabled → use this folder as primary defect tracker
+- Either way: `test.skip()` references a defect ID so the skip is traceable
+
+See `docs/generalization-decisions.md §7` for the full evaluation of this folder.
+
+---
+
+## 07-automation/
+
+**Purpose**: All automation code, configuration, and related tooling.
+
+```
+07-automation/
+├── README.md                       ← How to run, where reports go, worker config
+├── e2e/                            ← Playwright E2E tests
+│   ├── package.json
+│   ├── playwright.config.ts
+│   ├── global-setup.ts             ← Pre-suite login + storageState save
+│   ├── .env                        ← Local credentials (NEVER commit)
+│   ├── .env.example                ← Template (always commit)
+│   ├── .auth/                      ← storageState files (gitignored)
+│   ├── fixtures/
+│   │   ├── auth.ts                 ← loginAs(page, role) helper
+│   │   └── test-helpers.ts         ← EXEC_IDX, date helpers, etc.
+│   ├── page-objects/               ← Page Object Model classes
+│   ├── tests/
+│   │   ├── {module}/               ← Tests by module
+│   │   ├── helpers/debug/          ← Diagnostic scripts (not part of suite)
+│   │   └── seeds/                  ← Data seeding specs (excluded from runs)
+│   ├── diagnosis/                  ← Screenshots and debug output (gitignored)
+│   └── scripts/                    ← One-off utility scripts
+└── integration/                    ← API-level tests (if applicable)
+```
+
+**Important rules**:
+- Always run Playwright from the **repo root**, not from inside `qa/07-automation/e2e/`
+- Seeds are excluded from normal test runs via `testIgnore` in `playwright.config.ts`
+- Debug artifacts go into `diagnosis/` — never into the repo root
+- `.auth/` is always gitignored
+
+---
+
+## 08-azure-integration/
+
+**Purpose**: Azure DevOps integration configuration and scripts. Only present when ADO is enabled.
+
+```
+08-azure-integration/
+├── README.md
+├── AGENT-ADO-INTEGRATION.md        ← Agent instructions for ADO operations
+├── PLAYWRIGHT-AZURE-REPORTER-PLAN.md ← Reporter setup and migration log
+├── module-registry.json            ← Module → spec path → ADO plan/suite IDs
+├── ado-ids-mapping-{project}.json  ← Complete TC → ADO WI ID registry
+├── pipelines/
+│   └── azure-pipeline-qa.yml       ← CI/CD pipeline definition
+└── scripts/
+    ├── inject-ado-ids.ps1          ← Injects [ID] prefix into spec files
+    ├── create-testplan-from-mapping.ps1 ← Creates ADO plan from mapping JSON
+    └── sync-ado-titles.ps1         ← Syncs spec titles with ADO TC titles
+```
+
+---
+
+## `qa/README.md` — The Living Index
+
+The `qa/README.md` is the **only project-maintained file at the root of `qa/`**. It should be updated whenever:
+- A new module is analyzed
+- A new test execution is completed
+- A blocker is identified or resolved
+- A major milestone is reached
+
+Minimum contents:
+- Module status table (name, TCs documented, TCs automated, ADO plan link)
+- Quick-start commands for common tasks
+- Active blockers section
+- Last execution results summary
+
+---
+
+## Session Summary Files
+
+Optionally, place `SESSION-SUMMARY-YYYY-MM-DD.md` at the `qa/` root after each major working session. These files:
+- Document what was produced in the session
+- Record any blockers encountered
+- Provide the starting point for the next session
+
+This is especially valuable for agents — a session summary provides continuity across multiple chat sessions.

package/docs/generalization-decisions.md

@@ -0,0 +1,203 @@
+# docs/generalization-decisions.md
+
+**Phase 2 Artifact** — Classification and decision log for every element found during discovery.
+
+Every decision in this document follows the format:
+
+> **Decision ID** | **Item** | **Source** | **Decision** | **Rationale** | **What was discarded**
+
+---
+
+## §1 — 8-Folder QA Directory Structure
+
+- **Item**: Numbered folder hierarchy `00-guides/` through `08-azure-integration/`
+- **Source**: Both repos (identical structure)
+- **Decision**: ✅ **Framework core**
+- **Rationale**: Both repos independently converged on this same structure. It provides a clear, numbered namespace that agents can navigate predictably. The numbers prevent alphabetical re-ordering from breaking conventions.
+- **What was discarded**: Nothing. Structure adopted as-is.
+
+---
+
+## §2 — 6-File Submodule Template Set
+
+- **Item**: `00-inventory.md` → `05-test-scenarios.md`
+- **Source**: Both repos (Repo B more consistently follows the pattern)
+- **Decision**: ✅ **Framework core** (reusable template)
+- **Rationale**: This is the most consistently-replicated pattern across both repos and the most clearly generalizable unit of work. Every submodule follows this structure regardless of domain.
+- **Naming difference**: Repo A names file 1 `01-business-rules.md`; Repo B sometimes uses `01-functional-analysis.md`. **Resolution**: Standardize as `01-business-rules.md`. Functional analysis is a technique to produce business rules, not the output itself.
+- **What was discarded**: `01-functional-analysis.md` naming variant.
+
+---
+
+## §3 — Agent Instructions: Module Analysis
+
+- **Item**: `AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md` — 766 lines (A), 834 lines (B)
+- **Source**: Both repos (conceptually identical, slightly different phrasings)
+- **Decision**: ✅ **Agent instructions** (generalized, project-specific refs removed)
+- **Rationale**: Both are 4-phase instructions (Prepare → Explore → Document → Review). The core process is identical. Project-specific items removed: hardcoded URLs, project names, session names.
+- **What was discarded**:
+  - Repo A: `https://redactedURL.com`, `redacted@mail.com`, `playwright-cli MCP tool reference`
+  - Repo B: `https://redactedURL.com`, `redacted-project` session name
+  - Replaced with: `{{QA_BASE_URL}}`, `{{QA_USER_EMAIL}}` placeholders
+- **Adopted from Repo B** (merged): TC origin classification (UI-OBSERVADO / PENDIENTE-CODE / BLOQUEADO-PERMISOS), 50–85 TC target per submodule, 3-condition TC validity rule (VISIBLE + ACCESIBLE + OBSERVABLE)
+
+---
+
+## §4 — Agent Instructions: E2E Automation
+
+- **Item**: `AGENT-INSTRUCTIONS-E2E-PLAYWRIGHT-SPRINT40.md` (Repo A only)
+- **Source**: Repo A — sprint-specific, 961 lines
+- **Decision**: ✅ **Agent instructions** + **Optional integration** (heavily refactored)
+- **Rationale**: The document contains highly valuable generalizable patterns (multi-role auth, EXEC_IDX date strategy, 3-layer email validation, skip+DEF pattern, storageState) embedded within Sprint 40-specific content. The generalizable patterns were extracted; the sprint-specific content (task IDs, routes, form selectors) was discarded.
+- **What was discarded**: Azure Task IDs (20111, 21944–21949, 20528–20529), all `/RCL/`, `/Seguridad/` route references, all Sprint 40 test counts and scope, specific ADO Plan/Suite IDs.
+- **What was extracted**: The 18-section structure was collapsed into a generalized `04-automation-generation.md` agent instruction with parameterized sections.
+
+---
+
+## §5 — Standards Folder (`00-standards/`)
+
+- **Item**: Naming conventions, bug template, TC template, test-data guidelines
+- **Source**: Repo B only
+- **Decision**: ✅ **Framework core** — adopt from Repo B as the baseline
+- **Rationale**: Repo B has a full and well-designed standards set absent from Repo A. These are fully generalizable with minor parameterization (module/submodule codes).
+- **What was discarded**:
+  - Repo B has `admin.qakeber.com` hardcoded in bug-report template and test-data guidelines. Replaced with `{{QA_ADMIN_EMAIL}}`.
+  - Module codes (AUTH, PERS, USER, AGRI, OPER, REP) were kept as example values in templates but removed from any "authoritative" list.
+
+---
+
+## §6 — Playwright Integration
+
+- **Item**: `playwright.config.ts`, `global-setup.ts`, `.env.example`, `fixtures/auth.ts`, page objects, spec files
+- **Source**: Both repos
+- **Decision**: ✅ **Optional integration** (playwright adapter) + ✅ **Reusable templates** for config files
+- **Rationale**: Playwright is the automation framework of choice in both repos but must remain optional. Projects may use a different test runner (Jest, Cypress). The configuration patterns (storageState, globalSetup, testIgnore for seeds, CI vs local workers) are generalizable as templates.
+- **What was discarded**:
+  - All project-specific selectors (form fields, route paths, element IDs)
+  - All hardcoded URLs
+  - Sprint-specific npm scripts (`sprint40`, `sprint40:p0`)
+  - Application-specific form constants from `fixtures/test-data.ts`
+  - All page objects (too application-specific)
+- **What was templated**:
+  - `playwright.config.ts` — with `{{...}}` placeholders for baseURL, test path, ADO credentials
+  - `global-setup.ts` — generic login flow with configurable selectors
+  - `.env.example` — with all credential variables documented
+  - `fixtures/auth.ts` — generic multi-role fixture
+
+---
+
+## §7 — `06-defects/` Directory
+
+**This is the evaluation specifically requested in the brief.**
+
+- **Item**: The `06-defects/` folder and its defect-tracking purpose
+- **Source**: Repo A (actively used: DEF-001, DEF-002), Repo B (folder exists, no files)
+- **Analysis**:
+
+  | Criteria | Finding |
+  |---|---|
+  | Is real value demonstrated? | Yes, in Repo A: DEF-* IDs are referenced from `test.skip()`, linking automation state to bug state. This provides traceability from failing test → known defect. |
+  | Is it redundant with ADO? | Partially. ADO Work Items serve the same purpose in organizations that use ADO. However, not all projects use ADO. |
+  | Is the format standardized? | No. In Repo A: freeform Markdown. Repo B has a bug-report template in `00-standards/`. |
+  | Does it create maintenance burden? | Yes, if not kept in sync with ADO. Two sources of truth for defects is a known anti-pattern. |
+
+- **Decision**: ✅ **Keep as optional** — not required by framework core, but recommended when:
+  1. ADO is not in use (lightweight alternative)
+  2. The project needs offline/local defect tracking during sprint stabilization
+  3. The team wants to document the `test.skip() → DEF-* → reactivation path` explicitly
+
+- **Recommended evolution**: When ADO is enabled, `06-defects/` becomes a cache/mirror of ADO bugs relevant to QA automation. The defect file links to the ADO WI, rather than replacing it.
+
+- **What would be removed**: If this folder is removed from a project, the `test.skip('DEF-XXX: ...')` convention should still be kept in spec files; the DEF ID should then reference the ADO WI ID directly.
+
+---
+
+## §8 — Azure DevOps Integration
+
+- **Item**: Pipeline YAML, `playwright-azure-reporter`, PowerShell scripts, `module-registry.json`, `ado-ids-mapping.json`
+- **Source**: Repo B (fully implemented), Repo A (partial — referenced but not implemented)
+- **Decision**: ✅ **Optional integration** (ado-powershell adapter + playwright-azure-reporter adapter)
+- **Rationale**: ADO integration provides real value (E2E result sync with Test Plans, CI pipeline, WI ID injection) but creates a strong dependency on a specific vendor (Azure DevOps). The framework must work without it.
+- **What was kept**: The full set of scripts from Repo B — `inject-ado-ids.ps1`, `create-testplan-from-mapping.ps1`, `sync-ado-titles.ps1` — generalized by removing hardcoded org/project/ID values.
+- **What was parameterized**: `ADO_ORG`, `ADO_PROJECT`, `ADO_PAT`, `planId`, `suiteId`, variable group name.
+- **What was marked as stub**: The Repo B pipeline references a specific trigger branch (`keber.flores/qa-test/qa-specs`). This is replaced with a parameterized `{{CI_TRIGGER_BRANCH}}` in the template.
+
+---
+
+## §9 — Blazor-Specific Automation Guides
+
+- **Item**: `BLAZOR_WASM_AUTOMATION.md`, `RADZEN_COMPONENTS_PLAYWRIGHT.md`, `RETROSPECTIVA_CASCADA_2026-02.md`
+- **Source**: Repo B only
+- **Decision**: ✅ **Optional integration** (blazor-radzen adapter) for reusable helper functions; ❌ **Out of framework** for retrospective
+- **Rationale**: The Blazor/Radzen automation patterns (`openDropdownAndSelectFirst()`, `toBeAttached()`, `waitForFunction()` for popup detection) are highly reusable across any Radzen Blazor project. However, they are not generic enough for the framework core. The retrospective is project-specific debug log.
+- **What was extracted**: `openDropdownAndSelectFirst()` function moved to `integrations/blazor-radzen/helpers.ts` (stub — marked as `ADAPTER`).
+- **What was discarded**: Retrospective content, specific route references in cascade-dropdown backtrack.
+
+---
+
+## §10 — EXEC_IDX / RUN_SLOT Date Generation Pattern
+
+- **Item**: `Math.floor(Date.now() / 60_000) % 100_000` (EXEC_IDX), `Math.floor(Date.now()/300_000)` (RUN_SLOT)
+- **Source**: Repo A (primary), Repo B (uses raw `Date.now()` without the slot pattern)
+- **Decision**: ✅ **Framework core** (general convention, extracted to template)
+- **Rationale**: This pattern solves a real cross-project problem: parallel or repeated test runs creating data collisions. It avoids the need for test teardown and is independently applicable to any project with CRUD tests.
+- **Action**: Documented in `agent-instructions/04-automation-generation.md` as a required pattern for data-producing tests. Moved to `templates/automation-scaffold/fixtures/test-helpers.ts`.
+
+---
+
+## §11 — Naming Convention: Test Titles
+
+- **Item**: Test title format — `[Nx] Title @Pp` (Repo A) vs `[ADO_ID] Title` (Repo B)
+- **Source**: Both repos, incompatible
+- **Decision**: ✅ **Framework core** (adopt unified convention)
+- **Unified convention**: `[{LOCAL_ID}] {title} @{priority}` — e.g. `[TC-OPER-CAT-001] Access catalog list @P0`
+- **When ADO is enabled**: Local ID is replaced with ADO WI ID by `inject-ado-ids.ps1`, becoming `[22957] Access catalog list @P0`
+- **Rationale**: The local ID format preserves traceability without requiring ADO. The ADO ID injection is an idempotent upgrade step, not a prerequisite.
+
+---
+
+## §12 — Page Object Model (POM) vs Inline Automation
+
+- **Item**: POMs (Repo A) vs inline selector logic (Repo B)
+- **Source**: Repo A has 5 POMs; Repo B uses inline `page.locator()` calls in spec files
+- **Decision**: ✅ **Framework recommendation: use POMs** for production automation; inline is acceptable for exploratory scripts
+- **Rationale**: POMs provide selector encapsulation and reuse across suites. Repo A's approach led to smaller spec files and easier maintenance. Repo B's inline approach was faster to write but led to selector duplication. The framework templates use POMs, but the agent instruction notes that inline is acceptable for single-use diagnostic specs.
+
+---
+
+## §13 — `SITEMAP_TERRAVIX_QA.md` / `ui-menu-map.md` Pattern
+
+- **Item**: Auto-generated application sitemap from a real Playwright session
+- **Source**: Both repos (Repo B: SITEMAP file, Repo A: auto-generated ui-menu-map.md)
+- **Decision**: ✅ **Reusable template** — the `ui-menu-map.spec.ts` script extracted and generalized
+- **Rationale**: Generating a live sitemap from a Playwright session is a highly valuable, universally applicable pattern. It provides the ground truth for module analysis and access-control testing.
+- **What was parameterized**: `BASE_URL` env var, output path in `qa/01-specifications/shared/ui-menu-map.md`.
+
+---
+
+## §14 — Session Summary Pattern
+
+- **Item**: `SESSION-SUMMARY-YYYY-MM-DD.md` files at qa/ root (Repo B)
+- **Source**: Repo B only
+- **Decision**: ✅ **Reusable template**
+- **Rationale**: Provides a living log of what was produced in each QA working session. Useful for agent continuity (can resume from a known state) and for traceability.
+- **What was discarded**: Specific content (Personas module, 19 files created, etc.)
+
+---
+
+## §15 — `06-defects/` vs ADO Work Items Decision Tree
+
+For completeness, here is the recommended decision tree:
+
+```
+Is Azure DevOps enabled in this project?
+├── YES → Use ADO Work Items for ALL defects.
+│         Keep 06-defects/ as a lightweight reference cache only.
+│         Each DEF-*.md file = summary + link to ADO WI URL.
+│         test.skip() references ADO WI ID, not DEF-ID.
+│
+└── NO  → Use 06-defects/ as the primary defect tracker.
+          Follow the bug-report-template.md format.
+          test.skip() references DEF-ID.
+          When ADO is enabled later: migrate IDs.
+```