@keber/qa-framework 1.0.4

package/integrations/playwright/README.md

@@ -0,0 +1,68 @@
+# Integration — Playwright
+
+This directory documents how `@playwright/test` is configured within the
+`keber/qa-framework` opinionated setup.
+
+## Installation
+
+```bash
+npm install --save-dev @playwright/test
+npx playwright install chromium
+```
+
+## Recommended version
+
+Peer dependency: `@playwright/test >= 1.40.0`
+
+## Configuration
+
+Copy `templates/automation-scaffold/playwright.config.ts` into your project's
+`qa/07-automation/` directory and replace all `{{PLACEHOLDER}}` values.
+
+## Key conventions
+
+| Convention | Value |
+|------------|-------|
+| `fullyParallel` | `false` (tests share auth storageState) |
+| `workers` | `1` (sequential by default; increase only when tests are fully isolated) |
+| `retries` | `0` locally, `1` in CI |
+| Auth persistence | `.auth/user-{role}.json` (via `global-setup.ts`) |
+| Selectors | CSS preferred; use `data-testid` when available |
+| Timeouts | `actionTimeout: 15_000`, `navigationTimeout: 30_000` |
+
+## Auth state management
+
+The `global-setup.ts` template saves `storageState` to `.auth/` once before
+all tests. Tests reuse this state, so the login flow runs exactly once per
+suite execution.
+
+`.auth/` must be in `.gitignore`.
+
+## Debugging checklist
+
+1. `PWDEBUG=1 npx playwright test` — step through in inspector
+2. `--headed` — watch the browser
+3. `--trace on` — record full trace; open with `npx playwright show-trace`
+4. Increase `actionTimeout` if the app has slow server-side rendering
+5. Add `await page.waitForLoadState('networkidle')` before assertions on
+   dynamically loaded content
+
+## Spec file minimal template
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+const EXEC_IDX = Math.floor(Date.now() / 60_000) % 100_000;
+
+test.describe('[TC-M-S-NNN] Module > Submodule @P0', () => {
+  test('[TC-M-S-001] Should ...', async ({ page }) => {
+    // Arrange
+    await page.goto('/your-module-path');
+    // Act
+    await page.locator('#some-input').fill(`QA-Test-${EXEC_IDX}`);
+    await page.locator('#submit').click();
+    // Assert
+    await expect(page.locator('.success-notification')).toBeVisible();
+  });
+});
+```

package/integrations/playwright-azure-reporter/README.md

@@ -0,0 +1,88 @@
+# Integration — playwright-azure-reporter
+
+Connects Playwright test results to Azure DevOps Test Plans automatically.
+
+## Package
+
+```bash
+npm install --save-dev @alex_neo/playwright-azure-reporter
+```
+
+## Required environment variables
+
+```
+ADO_ORG_URL=https://dev.azure.com/your-org
+ADO_PROJECT_NAME=YourProject
+ADO_PLAN_ID=<plan-id>
+AZURE_TOKEN=<personal-access-token>
+```
+
+> These variables MUST be injected via CI secrets (Azure Pipeline Library Variable Group).
+> NEVER store tokens in `.env` files committed to source control.
+
+## playwright.config.ts snippet
+
+```typescript
+import type { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  reporter: [
+    ['list'],
+    ['html', { open: 'never' }],
+    ['@alex_neo/playwright-azure-reporter', {
+      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] ${new Date().toISOString().slice(0, 10)}`,
+      publishResultsOnFailure: true,
+      isDisabled:      process.env.ADO_SYNC_DISABLED === 'true',
+    }],
+  ],
+};
+
+export default config;
+```
+
+## Test case title format (required for ADO sync)
+
+The reporter matches test titles to ADO Work Items by the numeric prefix.
+After running `inject-ado-ids.ps1`, each test title will be prepended with
+the ADO WI ID wrapped in square brackets:
+
+```
+[22957] [TC-MOD-SUB-001] Create supplier @P0
+```
+
+The reporter extracts `22957` and publishes results to WI #22957 in ADO.
+
+## Module registry
+
+The file `qa/08-azure-integration/module-registry.json` maps each spec
+file/describe block to its ADO Test Suite. Example:
+
+```json
+{
+  "modules": [
+    {
+      "name": "Suppliers",
+      "specPattern": "suppliers/**/*.spec.ts",
+      "adoSuiteId": 22794
+    }
+  ]
+}
+```
+
+## Disabling ADO sync locally
+
+Set `ADO_SYNC_DISABLED=true` in your `.env` to skip reporting while running
+tests locally.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `401 Unauthorized` | Expired PAT | Regenerate PAT in ADO → User Settings |
+| `Test case not found` | WI ID mismatch | Re-run `inject-ado-ids.ps1` |
+| Results not published | `isDisabled: true` | Remove or set to `false` |
+| Duplicate test runs | Reporter called twice | Check for duplicate reporter arrays |

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@keber/qa-framework",
+  "version": "1.0.4",
+  "description": "Reusable spec-driven QA framework for IDE-agent-assisted automated testing. Installable as an npm package. Provides structure, templates, agent instructions, and optional integrations for Playwright and Azure DevOps.",
+  "keywords": [
+    "qa",
+    "testing",
+    "playwright",
+    "spec-driven",
+    "azure-devops",
+    "agent",
+    "copilot",
+    "framework"
+  ],
+  "license": "MIT",
+  "main": "scripts/index.js",
+  "bin": {
+    "qa-framework": "scripts/cli.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/init.js --skip-if-exists",
+    "init": "node scripts/cli.js init",
+    "generate": "node scripts/cli.js generate",
+    "validate": "node scripts/cli.js validate"
+  },
+  "files": [
+    "agent-instructions/",
+    "templates/",
+    "docs/",
+    "examples/",
+    "integrations/",
+    "scripts/",
+    "README.md",
+    "CHANGELOG.md",
+    "qa-framework.config.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {},
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0",
+    "@keber/ado-qa": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "@keber/ado-qa": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keber/qa-framework.git"
+  }
+}

package/qa-framework.config.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "./qa-framework.config.schema.json",
+  "frameworkVersion": "1.0.0",
+
+  "project": {
+    "name": "{{PROJECT_NAME}}",
+    "displayName": "{{PROJECT_DISPLAY_NAME}}",
+    "description": "{{PROJECT_DESCRIPTION}}",
+    "qaBaseUrl": "{{QA_BASE_URL}}",
+    "techStack": "{{TECH_STACK}}",
+    "loginPath": "{{LOGIN_PATH}}"
+  },
+
+  "modules": [
+    {
+      "code": "{{MODULE_CODE}}",
+      "name": "{{MODULE_NAME}}",
+      "description": "{{MODULE_DESCRIPTION}}",
+      "specPath": "qa/01-specifications/module-{{module-name}}",
+      "automationPath": "qa/07-automation/e2e/tests/{{module-name}}"
+    }
+  ],
+
+  "conventions": {
+    "language": "es",
+    "locale": "es-CL",
+    "testCaseIdPattern": "TC-{MODULE}-{SUBMODULE}-{NUM}",
+    "businessRuleIdPattern": "RN-{MODULE}-{NUM}",
+    "workflowIdPattern": "FL-{MODULE}-{NUM}",
+    "defectIdPattern": "DEF-{NUM}",
+    "testNamingPattern": "[{ID}] {title} @{priority}",
+    "timestampFormat": "YYYY-MM-DD_HH-MM-SS",
+    "tcPriorityLevels": ["P0", "P1", "P2", "P3"]
+  },
+
+  "testUsers": [
+    {
+      "role": "{{ROLE_NAME}}",
+      "envVarEmail": "QA_USER_{{ROLE_UPPER}}_EMAIL",
+      "envVarPassword": "QA_USER_{{ROLE_UPPER}}_PASSWORD",
+      "description": "{{ROLE_DESCRIPTION}}"
+    }
+  ],
+
+  "integrations": {
+    "playwright": {
+      "enabled": false,
+      "automationRoot": "qa/07-automation/e2e",
+      "workers": {
+        "local": 2,
+        "ci": 1
+      },
+      "timeout": 30000,
+      "navigationTimeout": 60000,
+      "actionTimeout": 10000,
+      "retries": {
+        "local": 0,
+        "ci": 2
+      },
+      "browsers": ["chromium"]
+    },
+
+    "azureDevOps": {
+      "enabled": false,
+      "organization": "{{ADO_ORG}}",
+      "project": "{{ADO_PROJECT}}",
+      "testPlanId": null,
+      "suiteId": null,
+      "variableGroup": "{{ADO_VARIABLE_GROUP}}",
+      "pipelineFile": "qa/08-azure-integration/pipelines/azure-pipeline-qa.yml",
+      "moduleRegistry": "qa/08-azure-integration/module-registry.json",
+      "reporterPackage": "@alex_neo/playwright-azure-reporter"
+    }
+  },
+
+  "agentSettings": {
+    "instructionsPath": "qa/00-guides",
+    "credentialPolicy": "env-vars-only",
+    "credentialPlaceholder": "<PLACEHOLDER>",
+    "screenshotPath": "qa/07-automation/e2e/diagnosis",
+    "sessionSummaryLocation": "qa/",
+    "tc_per_submodule_target": {
+      "min": 50,
+      "max": 85
+    }
+  }
+}

package/scripts/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * scripts/cli.js — keber/qa-framework CLI entry point
+ *
+ * Usage:
+ *   npx keber/qa-framework <command> [options]
+ *   qa-framework <command> [options]
+ *
+ * Commands:
+ *   init      Scaffold a qa/ folder structure from qa-framework.config.json
+ *   generate  Generate an artifact (spec template, test plan, etc.)
+ *   validate  Validate qa/ folder structure and conventions
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const [, , command, ...args] = process.argv;
+
+const commands = {
+  init:     'init.js',
+  generate: 'generate.js',
+  validate: 'validate.js',
+};
+
+if (!command || command === '--help' || command === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (!commands[command]) {
+  console.error(`[qa-framework] Unknown command: "${command}"`);
+  printHelp();
+  process.exit(1);
+}
+
+const scriptPath = path.join(__dirname, commands[command]);
+const result = spawnSync(
+  process.execPath,
+  [scriptPath, ...args],
+  { stdio: 'inherit', cwd: process.cwd() }
+);
+
+process.exit(result.status ?? 0);
+
+function printHelp() {
+  console.log(`
+keber/qa-framework
+
+Usage:
+  qa-framework <command> [options]
+
+Commands:
+  init [--config <path>]      Scaffold qa/ structure from config file
+  generate <artifact>         Generate from template
+                                artifact: spec | test-plan | test-case |
+                                          execution-report | defect-report |
+                                          session-summary
+  validate [--strict]         Validate qa/ structure and naming conventions
+
+Options:
+  --help, -h                  Show help
+  --version, -v               Show version
+
+Examples:
+  qa-framework init
+  qa-framework init --config ./my-project.config.json
+  qa-framework generate spec --module suppliers --submodule create
+  qa-framework validate
+  qa-framework validate --strict
+`);
+}

package/scripts/generate.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * scripts/generate.js — Generate a qa artifact from a template
+ *
+ * Usage:
+ *   qa-framework generate <artifact> [options]
+ *
+ * Artifacts:
+ *   spec              6-file submodule spec set
+ *   test-plan         Test plan document
+ *   test-case         Individual test case document
+ *   execution-report  Execution report document
+ *   defect-report     Defect / bug report
+ *   session-summary   Session summary
+ *
+ * Options:
+ *   --module <name>     Module name (used for file naming and headers)
+ *   --submodule <name>  Submodule name (for spec artifact)
+ *   --output <dir>      Output directory (default: current working directory)
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const args     = process.argv.slice(2);
+const artifact = args[0];
+
+const getArg = (flag) => {
+  const i = args.indexOf(flag);
+  return i !== -1 ? args[i + 1] : null;
+};
+
+const moduleName    = getArg('--module')    ?? 'MyModule';
+const submoduleName = getArg('--submodule') ?? 'MySubmodule';
+const outputDir     = getArg('--output')    ? path.resolve(process.cwd(), getArg('--output')) : process.cwd();
+
+const templateDir = path.resolve(__dirname, '..', 'templates');
+
+const ARTIFACTS = {
+  spec:             null,    // special — copies all 6 files
+  'test-plan':      path.join(templateDir, 'test-plan.md'),
+  'test-case':      path.join(templateDir, 'test-case.md'),
+  'execution-report': path.join(templateDir, 'execution-report.md'),
+  'defect-report':  path.join(templateDir, 'defect-report.md'),
+  'session-summary': path.join(templateDir, 'session-summary.md'),
+};
+
+if (!artifact || !ARTIFACTS.hasOwnProperty(artifact)) {
+  console.error(`[qa-framework/generate] Unknown artifact: "${artifact}"`);
+  console.error(`Available artifacts: ${Object.keys(ARTIFACTS).join(', ')}`);
+  process.exit(1);
+}
+
+const moduleKey  = moduleName.toLowerCase().replace(/\s+/g, '-');
+const subKey     = submoduleName.toLowerCase().replace(/\s+/g, '-');
+
+if (artifact === 'spec') {
+  // Generate all 6 spec files into outputDir/moduleKey/subKey/
+  const specDir = path.join(outputDir, moduleKey, subKey);
+  fs.mkdirSync(specDir, { recursive: true });
+
+  const specTemplateDir = path.join(templateDir, 'specification');
+  const files = fs.readdirSync(specTemplateDir).filter(f => f.endsWith('.md'));
+
+  for (const file of files) {
+    const dest = path.join(specDir, file);
+    let content = fs.readFileSync(path.join(specTemplateDir, file), 'utf8');
+    content = applyReplacements(content, moduleKey, subKey, moduleName, submoduleName);
+    fs.writeFileSync(dest, content, 'utf8');
+    console.log(`[generate] Created: ${path.relative(process.cwd(), dest)}`);
+  }
+} else {
+  // Single file artifact
+  const src  = ARTIFACTS[artifact];
+  const slug = artifact === 'defect-report' ? 'DEF-NNN' : `${moduleKey}-${artifact}`;
+  const dest = path.join(outputDir, `${slug}.md`);
+
+  let content = fs.readFileSync(src, 'utf8');
+  content = applyReplacements(content, moduleKey, subKey, moduleName, submoduleName);
+  fs.writeFileSync(dest, content, 'utf8');
+  console.log(`[generate] Created: ${path.relative(process.cwd(), dest)}`);
+}
+
+function applyReplacements(content, moduleKey, subKey, moduleName, submoduleName) {
+  return content
+    .replace(/\{\{MODULE_NAME\}\}/g, moduleName)
+    .replace(/\{\{SUBMODULE_NAME\}\}/g, submoduleName)
+    .replace(/\{\{MODULE\}\}/g, moduleKey.toUpperCase())
+    .replace(/\{\{SUB\}\}/g, subKey.toUpperCase());
+}