@keber/qa-framework 1.5.2 → 1.6.2

package/scripts/upgrade.js

@@ -8,21 +8,30 @@
  *
  * What this command does (safe by design):
  *   ALWAYS updates (framework-owned):
- *     - .github/skills/             ← New skills architecture; always current
- *     - .github/copilot-instructions.md ← Pipeline sequencer; framework-owned
- *     - qa/QA-STRUCTURE-GUIDE.md    ← Folder reference; framework-owned
+ *     - .github/skills/             <- New skills architecture; always current
+ *     - .github/copilot-instructions.md <- Pipeline sequencer; framework-owned
+ *     - qa/QA-STRUCTURE-GUIDE.md    <- Folder reference; framework-owned
  *
+ *   MIGRATES (v1.5.x -> v1.6.0, non-destructive):
+ *     - qa/07-automation/playwright.config.ts  -> qa/07-automation/e2e/
+ *     - qa/07-automation/global-setup.ts       -> qa/07-automation/e2e/
+ *     - qa/07-automation/package.json          -> qa/07-automation/e2e/
+ *     - qa/07-automation/.env.example          -> qa/07-automation/e2e/
+ *     - qa/07-automation/fixtures/             -> qa/07-automation/e2e/fixtures/
+ *     - qa/07-automation/e2e/{module}/         -> qa/07-automation/e2e/tests/{module}/
+ *     - Creates integration/ and load/ placeholders *     - Patches playwright.config.ts: testDir '.' -> './tests', adds testIgnore
+ *     - Creates tests/helpers/debug/ and tests/seeds/ if absent *
  *   NEVER touches (project-owned):
- *     - qa/01-specifications/       ← Your specs
- *     - qa/02-test-plans/           ← Your test plans
- *     - qa/03-test-cases/           ← Your TCs
- *     - qa/07-automation/           ← Your Playwright code
- *     - qa/memory/                  ← Your learnings
- *     - qa/README.md                ← Your living index
- *     - qa/AGENT-NEXT-STEPS.md       ← Your sprint queue
+ *     - qa/01-specifications/       <- Your specs
+ *     - qa/02-test-plans/           <- Your test plans
+ *     - qa/03-test-cases/           <- Your TCs
+ *     - qa/07-automation/e2e/tests/ <- Your Playwright tests (only moves, never overwrites)
+ *     - qa/memory/                  <- Your learnings
+ *     - qa/README.md                <- Your living index
+ *     - qa/AGENT-NEXT-STEPS.md      <- Your sprint queue
  *
  *   REPORTS but does not delete:
- *     - qa/00-guides/               ← Old location (can be deleted manually)
+ *     - qa/00-guides/               <- Old location (can be deleted manually)
  */
 
 'use strict';
@@ -98,6 +107,125 @@ if (fs.existsSync(oldGuidesDir)) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// 5. Migration v1.5.x -> v1.6.0: restructure qa/07-automation/
+//    Safe: only moves files when source exists and destination does NOT.
+// ---------------------------------------------------------------------------
+const automationDir  = path.join(qaRoot, '07-automation');
+const e2eDir         = path.join(automationDir, 'e2e');
+
+// 5a. Scaffold files: 07-automation/*.* -> 07-automation/e2e/*.*
+const scaffoldFiles = ['playwright.config.ts', 'global-setup.ts', 'package.json', '.env.example', 'package-lock.json'];
+for (const file of scaffoldFiles) {
+  const oldPath = path.join(automationDir, file);
+  const newPath = path.join(e2eDir, file);
+  if (fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+    if (!dryRun) {
+      fs.mkdirSync(e2eDir, { recursive: true });
+      fs.renameSync(oldPath, newPath);
+    }
+    updated.push(newPath);
+    console.log(`  [migrated] ${path.relative(cwd, oldPath)} -> e2e/${file}`);
+  }
+}
+
+// 5b. fixtures/: 07-automation/fixtures/ -> 07-automation/e2e/fixtures/
+const oldFixturesDir = path.join(automationDir, 'fixtures');
+const newFixturesDir = path.join(e2eDir, 'fixtures');
+if (fs.existsSync(oldFixturesDir) && !fs.existsSync(newFixturesDir)) {
+  if (!dryRun) {
+    fs.mkdirSync(e2eDir, { recursive: true });
+    fs.renameSync(oldFixturesDir, newFixturesDir);
+  }
+  updated.push(newFixturesDir);
+  console.log(`  [migrated] ${path.relative(cwd, oldFixturesDir)}/ -> e2e/fixtures/`);
+}
+
+// 5c. Spec stubs: e2e/{module}/*.spec.ts -> e2e/tests/{module}/
+//     Moves any directory directly under e2e/ that is not a known non-module dir.
+const testsDir = path.join(e2eDir, 'tests');
+const knownE2eDirs = new Set(['tests', 'page-objects', 'fixtures', 'diagnosis', 'scripts', 'seeds', 'helpers']);
+if (fs.existsSync(e2eDir)) {
+  for (const entry of fs.readdirSync(e2eDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || knownE2eDirs.has(entry.name)) continue;
+    const oldModDir = path.join(e2eDir, entry.name);
+    const newModDir = path.join(testsDir, entry.name);
+    if (!fs.existsSync(newModDir)) {
+      if (!dryRun) {
+        fs.mkdirSync(testsDir, { recursive: true });
+        fs.renameSync(oldModDir, newModDir);
+      }
+      updated.push(newModDir);
+      console.log(`  [migrated] e2e/${entry.name}/ -> e2e/tests/${entry.name}/`);
+    } else {
+      warnings.push(
+        `Cannot migrate e2e/${entry.name}/ — target e2e/tests/${entry.name}/ already exists. Merge manually.`
+      );
+    }
+  }
+}
+
+// 5d. Create integration/ and load/ placeholders if missing.
+const integrationReadme = path.join(automationDir, 'integration', 'README.md');
+const loadReadme        = path.join(automationDir, 'load', 'README.md');
+if (!fs.existsSync(integrationReadme)) {
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(integrationReadme), { recursive: true });
+    fs.writeFileSync(integrationReadme,
+      '# Integration Tests\n\n> Placeholder for API/integration tests (k6, JMeter, Azure Load Testing, etc.).\n> Each tool gets its own subdirectory.\n', 'utf8');
+  }
+  updated.push(integrationReadme);
+  console.log(`  [created] ${path.relative(cwd, integrationReadme)}`);
+}
+if (!fs.existsSync(loadReadme)) {
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(loadReadme), { recursive: true });
+    fs.writeFileSync(loadReadme,
+      '# Load Tests\n\n> Placeholder for load and performance tests.\n> Each tool gets its own subdirectory (e.g. k6/, jmeter/).\n', 'utf8');
+  }
+  updated.push(loadReadme);
+  console.log(`  [created] ${path.relative(cwd, loadReadme)}`);
+}
+
+// 5e. Patch playwright.config.ts in e2e/:
+const playwrightConfigPath = path.join(e2eDir, 'playwright.config.ts');
+if (fs.existsSync(playwrightConfigPath)) {
+  let cfg = fs.readFileSync(playwrightConfigPath, 'utf8');
+  let cfgChanged = false;
+
+  // Fix testDir: '.' -> './tests'
+  if (/testDir\s*:\s*['"]\.['"]/.test(cfg)) {
+    cfg = cfg.replace(/testDir\s*:\s*['"]\.['"]/g, "testDir:  './tests'");
+    cfgChanged = true;
+    console.log(`  [patched] e2e/playwright.config.ts — testDir: '.' -> './tests'`);
+  }
+
+  // Inject testIgnore after testDir line if not present
+  if (!cfg.includes('testIgnore')) {
+    cfg = cfg.replace(
+      /(testDir\s*:.*\n)/,
+      "$1  testIgnore: ['**/helpers/debug/**', '**/seeds/**'],\n"
+    );
+    cfgChanged = true;
+    console.log(`  [patched] e2e/playwright.config.ts — added testIgnore`);
+  }
+
+  if (cfgChanged) {
+    if (!dryRun) fs.writeFileSync(playwrightConfigPath, cfg, 'utf8');
+    updated.push(playwrightConfigPath);
+  }
+}
+
+// Create tests/helpers/debug and tests/seeds if missing
+for (const subdir of ['tests/helpers/debug', 'tests/seeds']) {
+  const subdirPath = path.join(e2eDir, subdir);
+  if (!fs.existsSync(subdirPath)) {
+    if (!dryRun) fs.mkdirSync(subdirPath, { recursive: true });
+    updated.push(subdirPath);
+    console.log(`  [created] ${path.relative(cwd, subdirPath)}/`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------

package/skills/qa-ado-integration/SKILL.md

@@ -63,7 +63,7 @@ After sync, each TC file must have `adoId: <NNN>` in its YAML frontmatter block.
 
 ### Step 4 — Configure Playwright ADO reporter
 
-See `references/scripts-and-config.md` for the reporter config block to add to `qa/07-automation/playwright.config.ts`.
+See `references/scripts-and-config.md` for the reporter config block to add to `qa/07-automation/e2e/playwright.config.ts`.
 
 Required fields:
 - `orgUrl`, `projectName`, `planId`, `runName`
@@ -100,4 +100,4 @@ Update `qa/08-azure-integration/module-registry.json` with:
 - ADO Test Plan populated with test cases
 - `qa/03-test-cases/automated/TC-*.md` — ADO IDs injected
 - `qa/08-azure-integration/module-registry.json` updated
-- `qa/07-automation/playwright.config.ts` updated with reporter config
+- `qa/07-automation/e2e/playwright.config.ts` updated with reporter config

package/skills/qa-automation/SKILL.md

@@ -14,7 +14,7 @@ description: >
 
 **Stage**: 5 — Automation  
 **Prerequisite**: All specs for the target submodule are complete and contain no `PENDING-CODE` sections  
-**Output**: `qa/07-automation/e2e/{module}/{submodule}.spec.ts` + supporting files  
+**Output**: `qa/07-automation/e2e/tests/{module}/{submodule}.spec.ts` + supporting files  
 **Next stage**: Stage 6 — Maintenance (`qa-maintenance`) or Stage 5b — Stabilization (`qa-test-stabilization`) if tests fail
 
 > **Pipeline rule**: Never automate a TC whose spec contains `PENDING-CODE`. Resolve spec gaps first.
@@ -24,8 +24,8 @@ description: >
 ## Inputs Required
 
 1. `qa/01-specifications/{module}/` — full spec set for target submodule
-2. `qa/07-automation/playwright.config.ts` — confirm project name maps to submodule tag
-3. `qa/07-automation/fixtures/auth.ts` — identify available auth fixtures
+2. `qa/07-automation/e2e/playwright.config.ts` — confirm project name maps to submodule tag
+3. `qa/07-automation/e2e/fixtures/auth.ts` — identify available auth fixtures
 4. TC list (from test plan or Stage 4) — defines which TCs to automate in this session
 5. `qa/qa-framework.config.json` → screenshotPath, automationRoot
 
@@ -38,7 +38,7 @@ description: >
 For every new submodule, run a dedicated inspection script before writing tests.
 **Template**: `references/dom-inspection-template.js` — copy, set the 4 constants at the top, run.
 
-1. Copy `references/dom-inspection-template.js` → `qa/07-automation/_inspect-{submodule}.js`
+1. Copy `references/dom-inspection-template.js` → `qa/07-automation/e2e/_inspect-{submodule}.js`
 2. Set the 4 constants at the top of the script:
    - `MODULE_ROUTE` — the submodule's URL path (e.g. `'/Users'`, `'/Products/list'`)
    - `APP_SHELL_SEL` — a selector that confirms the SPA has loaded (nav, sidebar, app shell)
@@ -150,7 +150,7 @@ See `references/patterns.md` for full TypeScript implementations.
 
 ## Outputs
 
-- `qa/07-automation/e2e/{module}/{submodule}.spec.ts`
+- `qa/07-automation/e2e/tests/{module}/{submodule}.spec.ts`
 - `qa/07-automation/e2e/page-objects/{SubmoduleName}Page.ts`  (when POM criteria met)
-- `qa/07-automation/playwright.config.ts` (updated or confirmed)
+- `qa/07-automation/e2e/playwright.config.ts` (updated or confirmed)
 - `qa/README.md` automation status updated

package/skills/qa-maintenance/SKILL.md

@@ -24,7 +24,7 @@ description: >
 
 1. Description of the change — which submodule, what changed, and why
 2. `qa/01-specifications/{module}/` — specs affected by the change
-3. `qa/07-automation/e2e/{module}/` — automation affected by the change
+3. `qa/07-automation/e2e/tests/{module}/` — automation affected by the change
 4. Optionally: ADO work item or defect report describing the change
 
 ---
@@ -105,6 +105,6 @@ change-summary: {one-line description of what changed}
 
 - Updated `qa/01-specifications/{module}/*.md` files
 - Updated `qa/03-test-cases/automated/TC-*.md` files
-- Updated `qa/07-automation/e2e/{module}/*.spec.ts`
+- Updated `qa/07-automation/e2e/tests/{module}/*.spec.ts`
 - Updated `qa/README.md`
 - Updated `AGENT-NEXT-STEPS.md` (or sprint moved to history if complete)

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

@@ -38,7 +38,9 @@ for (const key of required) {
 
 export default defineConfig({
   // ------ Test discovery ------
-  testDir:  '.',
+  testDir:  './tests',
+  // Exclude non-suite directories from test runs
+  testIgnore: ['**/helpers/debug/**', '**/seeds/**'],
   // Use any subdir pattern your project standardizes on, e.g.:
   // testMatch: ['**/*.spec.ts'],
 

package/agent-instructions/00-module-analysis.md

@@ -1,266 +0,0 @@
-# Agent Instructions: Module Analysis
-
-> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-module-analysis/SKILL.md`.
-> Kept as reference during the transition period. Do not update this file.
-
-**File**: `agent-instructions/00-module-analysis.md`  
-**Purpose**: Instructions for an AI agent to perform complete functional analysis of an application module and produce the 6-file specification set.
-
----
-
-## When to use these instructions
-
-Use this instruction set when:
-- Analyzing a new module for the first time
-- A module has been updated and its spec needs to be refreshed
-- Building the initial `01-specifications/` tree for a project
-
----
-
-## Prerequisites (Agent must verify before starting)
-
-1. Confirm that `qa-framework.config.json` exists and contains `project.qaBaseUrl`
-2. Confirm that `qa/00-standards/naming-conventions.md` is available
-3. Confirm that the Playwright CLI (playwright-mcp or equivalent) is available for browser interaction
-4. Ask the user for:
-   - The module name and URL (or route prefix) to analyze
-   - The submodules to analyze (if known; otherwise discover from the UI)
-   - QA user credentials (handle via env vars — never store in markdown)
-
-**⚠️ SECURITY**: Never write real credentials to any file. If credentials appear in any output, replace immediately with `<PLACEHOLDER>`.
-
----
-
-## Phase 1 — Preparation
-
-### 1.1 Review existing specs
-
-Check if a `qa/01-specifications/module-{name}/` directory already exists.
-
-- If it does: read all existing files to understand what is already documented. Only re-analyze what has changed.
-- If it does not: create the directory structure.
-
-### 1.2 Generate module code
-
-If no module code exists yet, allocate a unique 2–6 uppercase letter code for the module.  
-Check `qa/00-standards/naming-conventions.md` for existing codes to avoid conflicts.
-
-Example: module "Operación" → code `OPER`; submodule "Catálogos" → code `CAT`
-
-### 1.3 Plan the session
-
-Identify all submodules in scope. A submodule typically corresponds to:
-- A distinct menu item or section in the application
-- A distinct CRUD entity (users, products, orders, etc.)
-- A distinct workflow (approval, registration, reporting)
-
-Document the planned submodules in `qa/01-specifications/module-{name}/README.md` before analysis begins.
-
----
-
-## Phase 2 — Exploration
-
-For each submodule, perform the following exploration using browser automation (Playwright CLI):
-
-### 2.1 Navigation and route mapping
-
-```
-Navigate to {{QA_BASE_URL}} and log in with the appropriate role
-Navigate to the submodule URL
-Record:
-  - Full URL of each page/view
-  - Page title
-  - Navigation breadcrumb
-```
-
-### 2.2 UI inventory
-
-For each screen in the submodule:
-
-```
-Record all:
-  - Input fields (name, type, required/optional, validation rules visible in UI)
-  - Dropdowns (static or dynamic/AJAX, options if static)
-  - Buttons (action, what they trigger)
-  - Tables/grids (columns, default sorting, pagination)
-  - Modals (trigger condition, fields, confirmation behavior)
-  - Status indicators / badges / alerts
-  - File upload / download controls
-```
-
-### 2.3 API endpoint discovery
-
-```
-Observe network requests during key interactions (create, read, update, delete)
-Record:
-  - Endpoint path (e.g., /api/GetUsers, api/CreateUser)
-  - HTTP method
-  - Request payload shape (field names)
-  - Response shape (key fields)
-```
-
-### 2.4 Role-based access testing
-
-```
-For each configured test user role:
-  Log in as that role
-  Navigate to the submodule
-  Record: can access? (YES / NO / PERMISSION_ERROR)
-  Record: which actions are available vs hidden
-```
-
-### 2.5 Workflow discovery
-
-```
-Execute the primary happy path with appropriate test data
-Record each step
-Identify branch points (e.g., approve vs reject)
-Record state transitions
-```
-
-### 2.6 Business rule discovery
-
-```
-Attempt invalid inputs for each validation
-Record: validation message text, field that shows the error
-Attempt boundary conditions (empty, max length, duplicate, etc.)
-Record: system behavior
-```
-
----
-
-## Phase 3 — Documentation (6-file output)
-
-Produce the following files for each submodule. Use the templates in `qa/00-standards/` and `templates/specification/`.
-
-### File 00: `00-inventory.md`
-
-Contents:
-- Module header (name, code, URL, deployment date if known)
-- Submodule header (name, code, routes)
-- UI element inventory table
-  - Element name | Type | Required | Notes
-- API endpoint table
-  - Method | Path | Purpose
-- Key identifiers and selectors observed in the UI
-
-### File 01: `01-business-rules.md`
-
-Contents:
-- Each rule as `RN-{MODULE}-{NNN}`: Description
-- Rule type: Validation / Access Control / State Machine / Calculation / Integration
-- Trigger: what user action triggers this rule
-- Error message: exact text shown when rule is violated (if applicable)
-
-Aim for 5–15 business rules per submodule.
-
-### File 02: `02-workflows.md`
-
-Contents:
-- Each major workflow as `FL-{MODULE}-{NNN}`: Title
-- Use ASCII flowchart or Mermaid block diagram
-- Cover: happy path + main alternative paths + error paths
-
-### File 03: `03-roles-permissions.md`
-
-Contents:
-- Role × Feature matrix table
-  - Row: test user role
-  - Column: feature/action (view, create, edit, delete, approve, export, etc.)
-  - Cell: ✅ / ❌ / ⚠️ (limited)
-- Notes on role inheritance or conditional access
-
-### File 04: `04-test-data.md`
-
-Contents:
-- Prerequisites: what data must exist before tests run
-- Data shapes: for each key test scenario, what data is needed
-  - DO NOT include real user credentials
-  - Use env var references for any credential: `process.env.QA_USER_EMAIL`
-- Data dependencies between submodules (if any)
-
-### File 05: `05-test-scenarios.md`
-
-Contents:
-- Summary table at top: total TCs, by priority, by type
-- For each TC:
-  - ID: `TC-{MODULE}-{SUBMODULE}-{NNN}`
-  - Title: brief action description
-  - Priority: P0 / P1 / P2 / P3
-  - Type: Functional / Regression / Security / Negative / Integration
-  - Origin: `UI-OBSERVED` / `PENDING-CODE` / `BLOCKED-PERMISSIONS`
-  - Preconditions
-  - Steps (numbered)
-  - Expected result
-  - Automation feasibility: Yes / Partial / No
-
-Target: **50–85 TCs per submodule** is a well-analyzed submodule.
-
-#### TC coverage must include:
-- ✅ Access control (each role: can access / cannot access)
-- ✅ Happy path (primary workflow end-to-end)
-- ✅ Negative scenarios (required field empty, invalid format, duplicate, etc.)
-- ✅ State transitions (create → edit → delete; pending → approved → rejected)
-- ✅ Cross-module dependencies (if any)
-- ✅ Export/download (if feature exists)
-- ✅ Pagination/search (if feature exists)
-
-TC origin rules:
-- Only write `UI-OBSERVED` if you directly observed the behavior in the QA environment
-- If a feature is documented but not visible in the QA environment: `PENDING-CODE`
-- If you couldn't test it due to permission restrictions: `BLOCKED-PERMISSIONS`
-
----
-
-## Phase 4 — Review and Session Summary
-
-### 4.1 Completeness checklist
-
-After completing all submodule files, verify:
-
-- [ ] All menu items in the module have a corresponding submodule folder
-- [ ] All TCs marked `UI-OBSERVED` were actually observed in this session
-- [ ] `01-business-rules.md` covers all visible validation behaviors
-- [ ] `03-roles-permissions.md` reflects the access observed for each role
-- [ ] No credentials appear in any file
-- [ ] All TC IDs are unique across the module
-- [ ] Module README lists all submodules with their codes and TC counts
-
-### 4.2 Write session summary
-
-Create `qa/SESSION-SUMMARY-{YYYY-MM-DD}.md` with:
-
-```markdown
-# Session Summary — {YYYY-MM-DD}
-
-## Module analyzed
-{module-name} ({module-code})
-
-## Submodules documented
-| Submodule | Code | TC count | Notes |
-|-----------|------|----------|-------|
-| {name}    | {code} | {N}    | {any notable blocking issues} |
-
-## Files created
-- {list of all files created with their paths}
-
-## Blockers
-- {any features that couldn't be analyzed and why}
-
-## Observations for next session
-- {what to tackle next}
-```
-
----
-
-## Quality Standards
-
-A well-executed module analysis session:
-
-1. Takes between 2-6 hours depending on module complexity
-2. Produces 6 files per submodule (not more, not less)
-3. Has no hardcoded credentials in any file
-4. Has TC IDs that follow the `TC-{MODULE}-{SUBMODULE}-{NNN}` pattern
-5. Has business rules that are verifiable in automated tests
-6. Has at least 1 P0 TC per submodule (the primary happy path)
-7. Does not invent TCs for behavior that wasn't observed in the QA environment