@keber/qa-framework 1.0.4

package/scripts/init.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * scripts/init.js — Scaffold qa/ folder structure from config
+ *
+ * Usage:
+ *   qa-framework init
+ *   qa-framework init --config ./my-project.config.json
+ *
+ * Reads qa-framework.config.json and creates the full qa/ directory tree
+ * including per-module and per-submodule folders with placeholder spec files.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// --- Parse args ---
+const args            = process.argv.slice(2);
+const configFlag      = args.indexOf('--config');
+const skipIfExists    = args.includes('--skip-if-exists');
+
+if (configFlag !== -1 && !args[configFlag + 1]) {
+  console.error('[qa-framework/init] Missing value for --config <path>');
+  process.exit(1);
+}
+
+const cwd = process.cwd();
+const explicitConfigPath = configFlag !== -1 ? path.resolve(cwd, args[configFlag + 1]) : null;
+const rootConfigPath = path.resolve(cwd, 'qa-framework.config.json');
+const qaConfigPath = path.resolve(cwd, 'qa', 'qa-framework.config.json');
+
+// --- Load or bootstrap config ---
+let config;
+let configSource;
+
+if (explicitConfigPath) {
+  if (!fs.existsSync(explicitConfigPath)) {
+    console.error(`[qa-framework/init] Config file not found: ${explicitConfigPath}`);
+    process.exit(1);
+  }
+  config = JSON.parse(fs.readFileSync(explicitConfigPath, 'utf8'));
+  configSource = explicitConfigPath;
+} else if (fs.existsSync(rootConfigPath)) {
+  config = JSON.parse(fs.readFileSync(rootConfigPath, 'utf8'));
+  configSource = rootConfigPath;
+} else if (fs.existsSync(qaConfigPath)) {
+  config = JSON.parse(fs.readFileSync(qaConfigPath, 'utf8'));
+  configSource = qaConfigPath;
+} else {
+  config = buildBootstrapConfig();
+  configSource = 'generated defaults';
+  console.log('[qa-framework/init] No config file found. Bootstrapping with default config.');
+}
+
+const qaRoot  = path.resolve(cwd, config.conventions?.qaRoot ?? 'qa');
+const localConfigPath = path.join(qaRoot, 'qa-framework.config.json');
+
+// --skip-if-exists: bail out silently when qa/ is already initialised
+if (skipIfExists && fs.existsSync(localConfigPath)) {
+  console.log('[qa-framework/init] qa/ already initialised — skipping (postinstall).');
+  process.exit(0);
+}
+
+if (!fs.existsSync(localConfigPath)) {
+  fs.mkdirSync(qaRoot, { recursive: true });
+  fs.writeFileSync(localConfigPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  console.log(`  [created] ${path.relative(cwd, localConfigPath)}`);
+} else {
+  console.log(`  [exists]  ${path.relative(cwd, localConfigPath)} — skipped`);
+}
+
+console.log(`[qa-framework/init] Scaffolding qa/ at: ${qaRoot}`);
+console.log(`[qa-framework/init] Using config source: ${configSource}`);
+
+// --- Top-level folders ---
+const topLevelFolders = [
+  '00-guides',
+  '00-standards',
+  '05-test-plans',
+  '06-defects/open',
+  '06-defects/resolved',
+  '07-automation/e2e',
+  '08-azure-integration',
+];
+
+for (const folder of topLevelFolders) {
+  const fullPath = path.join(qaRoot, folder);
+  fs.mkdirSync(fullPath, { recursive: true });
+  console.log(`  [created] ${path.relative(process.cwd(), fullPath)}/`);
+}
+
+// --- Standards placeholder ---
+const stdDir = path.join(qaRoot, '00-standards');
+writeIfMissing(path.join(stdDir, 'naming-conventions.md'), `# Naming Conventions\n\n> Fill in per your project. See keber/qa-framework docs/spec-driven-philosophy.md.\n`);
+writeIfMissing(path.join(stdDir, 'bug-report-template.md'), fs.readFileSync(
+  path.resolve(__dirname, '..', 'templates', 'defect-report.md'), 'utf8'
+));
+
+// --- Per-module folders ---
+const modules = config.modules ?? [];
+if (modules.length === 0) {
+  console.warn('[qa-framework/init] No modules defined in config. Add "modules" array to qa-framework.config.json.');
+}
+
+const SPEC_FILES = [
+  '00-inventory.md',
+  '01-business-rules.md',
+  '02-workflows.md',
+  '03-roles-permissions.md',
+  '04-test-data.md',
+  '05-test-scenarios.md',
+];
+
+const templateDir = path.resolve(__dirname, '..', 'templates', 'specification');
+
+for (const mod of modules) {
+  const moduleKey = mod.key ?? mod.name.toLowerCase().replace(/\s+/g, '-');
+  const submodules = mod.submodules ?? [];
+
+  for (const sub of submodules) {
+    const subKey = sub.key ?? sub.name.toLowerCase().replace(/\s+/g, '-');
+    const subDir = path.join(qaRoot, moduleKey, subKey);
+    fs.mkdirSync(subDir, { recursive: true });
+
+    for (const specFile of SPEC_FILES) {
+      const dest = path.join(subDir, specFile);
+      if (!fs.existsSync(dest)) {
+        const src = path.join(templateDir, specFile);
+        if (fs.existsSync(src)) {
+          let content = fs.readFileSync(src, 'utf8');
+          content = content
+            .replace(/\{\{MODULE_NAME\}\}/g, mod.name)
+            .replace(/\{\{SUBMODULE_NAME\}\}/g, sub.name)
+            .replace(/\{\{MODULE\}\}/g, moduleKey.toUpperCase())
+            .replace(/\{\{SUB\}\}/g, subKey.toUpperCase());
+          fs.writeFileSync(dest, content, 'utf8');
+        } else {
+          fs.writeFileSync(dest, `# ${specFile}\n\n> Auto-generated placeholder\n`, 'utf8');
+        }
+        console.log(`  [created] ${path.relative(process.cwd(), dest)}`);
+      } else {
+        console.log(`  [exists]  ${path.relative(process.cwd(), dest)} — skipped`);
+      }
+    }
+
+    // Create automation e2e subdir placeholder
+    const e2eDir = path.join(qaRoot, '07-automation', 'e2e', moduleKey);
+    fs.mkdirSync(e2eDir, { recursive: true });
+    const specTs = path.join(e2eDir, `${subKey}.spec.ts`);
+    if (!fs.existsSync(specTs)) {
+      fs.writeFileSync(specTs, specScaffold(mod.name, sub.name, moduleKey, subKey), 'utf8');
+      console.log(`  [created] ${path.relative(process.cwd(), specTs)}`);
+    }
+  }
+}
+
+// --- Automation scaffold ---
+const automationDir = path.join(qaRoot, '07-automation');
+const scaffoldSrc   = path.resolve(__dirname, '..', 'templates', 'automation-scaffold');
+for (const file of ['playwright.config.ts', 'global-setup.ts', '.env.example', 'package.json']) {
+  const dest = path.join(automationDir, file);
+  if (!fs.existsSync(dest)) {
+    fs.copyFileSync(path.join(scaffoldSrc, file), dest);
+    console.log(`  [created] ${path.relative(process.cwd(), dest)}`);
+  }
+}
+const fixturesDir = path.join(automationDir, 'fixtures');
+fs.mkdirSync(fixturesDir, { recursive: true });
+for (const file of ['auth.ts', 'test-helpers.ts']) {
+  const dest = path.join(fixturesDir, file);
+  if (!fs.existsSync(dest)) {
+    fs.copyFileSync(path.join(scaffoldSrc, 'fixtures', file), dest);
+    console.log(`  [created] ${path.relative(process.cwd(), dest)}`);
+  }
+}
+
+// --- ADO integration placeholder ---
+const adoDir = path.join(qaRoot, '08-azure-integration');
+writeIfMissing(path.join(adoDir, 'README.md'), `# ADO Integration\n\nSee keber/qa-framework integrations/ado-powershell/ for setup instructions.\n`);
+writeIfMissing(path.join(adoDir, 'module-registry.json'), JSON.stringify({ modules: [] }, null, 2));
+
+// --- Agent instructions → qa/00-guides/ ---
+const agentInstrSrc = path.resolve(__dirname, '..', 'agent-instructions');
+const guidesDir     = path.join(qaRoot, '00-guides');
+const agentFileMap  = {
+  '00-module-analysis.md':      'AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md',
+  '01-spec-generation.md':      'AGENT-INSTRUCTIONS-SPEC-GENERATION.md',
+  '02-test-plan-generation.md': 'AGENT-INSTRUCTIONS-TEST-PLAN.md',
+  '03-test-case-generation.md': 'AGENT-INSTRUCTIONS-TEST-CASES.md',
+  '04-automation-generation.md':'AGENT-INSTRUCTIONS-AUTOMATION.md',
+  '04b-test-stabilization.md':  'AGENT-INSTRUCTIONS-TEST-STABILIZATION.md',
+  '05-ado-integration.md':      'AGENT-INSTRUCTIONS-ADO-INTEGRATION.md',
+  '06-maintenance.md':          'AGENT-INSTRUCTIONS-MAINTENANCE.md',
+};
+for (const [src, dest] of Object.entries(agentFileMap)) {
+  const srcPath  = path.join(agentInstrSrc, src);
+  const destPath = path.join(guidesDir, dest);
+  if (fs.existsSync(srcPath)) {
+    writeIfMissing(destPath, fs.readFileSync(srcPath, 'utf8'));
+  }
+}
+
+// --- QA structure guide → qa/QA-STRUCTURE-GUIDE.md ---
+const structureGuideSrc  = path.resolve(__dirname, '..', 'docs', 'folder-structure-guide.md');
+const structureGuideDest = path.join(qaRoot, 'QA-STRUCTURE-GUIDE.md');
+if (fs.existsSync(structureGuideSrc)) {
+  writeIfMissing(structureGuideDest, fs.readFileSync(structureGuideSrc, 'utf8'));
+}
+
+// --- .github/copilot-instructions.md ---
+const githubDir         = path.join(cwd, '.github');
+const copilotInstrPath  = path.join(githubDir, 'copilot-instructions.md');
+const copilotInstrContent = `# QA Framework Instructions
+
+This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'} for spec-driven automated testing.
+
+## Agent behavior rules
+
+1. Before performing any QA task, read the relevant instruction file from \`qa/00-guides/\`
+2. Always save artifacts in the correct \`qa/\` subfolder — refer to \`qa/QA-STRUCTURE-GUIDE.md\`
+3. Never hardcode credentials — always use env vars and \`<PLACEHOLDER>\` in documentation
+4. Follow the naming conventions in \`qa/00-standards/naming-conventions.md\`
+5. Project QA config is at \`qa/qa-framework.config.json\`
+
+## Available agent instructions
+
+| Task | Instruction file |
+|---|---|
+| Analyze a module | \`qa/00-guides/AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md\` |
+| Generate specifications | \`qa/00-guides/AGENT-INSTRUCTIONS-SPEC-GENERATION.md\` |
+| Generate a test plan | \`qa/00-guides/AGENT-INSTRUCTIONS-TEST-PLAN.md\` |
+| Generate test cases | \`qa/00-guides/AGENT-INSTRUCTIONS-TEST-CASES.md\` |
+| Generate automation | \`qa/00-guides/AGENT-INSTRUCTIONS-AUTOMATION.md\` |
+| Stabilize failing tests | \`qa/00-guides/AGENT-INSTRUCTIONS-TEST-STABILIZATION.md\` |
+| Sync with Azure DevOps | \`qa/00-guides/AGENT-INSTRUCTIONS-ADO-INTEGRATION.md\` |
+| Maintenance after changes | \`qa/00-guides/AGENT-INSTRUCTIONS-MAINTENANCE.md\` |
+`;
+writeIfMissing(copilotInstrPath, copilotInstrContent);
+
+console.log('\n[qa-framework/init] Done!\n');
+console.log('Next steps:');
+console.log('  1. Copy qa/07-automation/.env.example to qa/07-automation/.env and fill in credentials');
+console.log('  2. Add qa/07-automation/.env and qa/07-automation/.auth/ to .gitignore');
+console.log('  3. Run: cd qa/07-automation && npm install && npx playwright install chromium');
+console.log('  4. Start filling in spec files with your module\'s real data');
+
+// -----------------------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------------------
+function writeIfMissing(filePath, content) {
+  if (!fs.existsSync(filePath)) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+    console.log(`  [created] ${path.relative(process.cwd(), filePath)}`);
+  }
+}
+
+function specScaffold(modName, subName, modKey, subKey) {
+  return `import { test, expect } from '@playwright/test';
+
+const EXEC_IDX = Math.floor(Date.now() / 60_000) % 100_000;
+
+test.describe('${modName} > ${subName} @P0', () => {
+
+  test('[TC-${modKey.toUpperCase()}-${subKey.toUpperCase()}-001] TODO: Add test title @P0', async ({ page }) => {
+    // TODO: Replace with real test steps from 05-test-scenarios.md
+    await page.goto('/');
+    expect(true).toBe(true);
+  });
+
+});
+`;
+}
+
+function buildBootstrapConfig() {
+  const templatePath = path.resolve(__dirname, '..', 'qa-framework.config.json');
+  const projectName = path.basename(cwd);
+
+  let base = {
+    frameworkVersion: '1.0.0',
+    project: {
+      name: projectName,
+      displayName: projectName,
+      description: '',
+      qaBaseUrl: '',
+      techStack: '',
+      loginPath: ''
+    },
+    modules: [],
+    conventions: {
+      qaRoot: 'qa',
+      language: 'es',
+      locale: 'es-CL'
+    },
+    integrations: {
+      playwright: { enabled: false },
+      azureDevOps: { enabled: false }
+    }
+  };
+
+  if (fs.existsSync(templatePath)) {
+    try {
+      base = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+    } catch {
+      // Keep fallback defaults above.
+    }
+  }
+
+  base.project = {
+    ...(base.project ?? {}),
+    name: projectName,
+    displayName: projectName
+  };
+  base.modules = [];
+  base.conventions = {
+    ...(base.conventions ?? {}),
+    qaRoot: 'qa'
+  };
+
+  return base;
+}

package/scripts/validate.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * scripts/validate.js — Validate qa/ folder structure and conventions
+ *
+ * Usage:
+ *   qa-framework validate
+ *   qa-framework validate --strict
+ *   qa-framework validate --config ./my-config.json
+ *
+ * Checks:
+ *   1. Required top-level folders exist
+ *   2. All submodule folders contain the 6 required spec files
+ *   3. No plaintext credentials in spec files (basic scan)
+ *   4. Test case naming convention (TC-NNN pattern in spec files)
+ *   5. [--strict] Automation spec files exist for every submodule
+ *   6. [--strict] EXEC_IDX pattern present in all spec files
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// --- Args ---
+const args       = process.argv.slice(2);
+const strict     = args.includes('--strict');
+const configFlag = args.indexOf('--config');
+const configPath = configFlag !== -1
+  ? path.resolve(process.cwd(), args[configFlag + 1])
+  : path.resolve(process.cwd(), 'qa-framework.config.json');
+
+// --- Load config (optional) ---
+let qaRoot = path.resolve(process.cwd(), 'qa');
+if (fs.existsSync(configPath)) {
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  qaRoot = path.resolve(process.cwd(), config.conventions?.qaRoot ?? 'qa');
+}
+
+console.log(`[qa-framework/validate] Validating: ${qaRoot}`);
+if (strict) console.log('[qa-framework/validate] Mode: STRICT');
+
+const errors   = [];
+const warnings = [];
+
+// -----------------------------------------------------------------------
+// Check 1: Required top-level folders
+// -----------------------------------------------------------------------
+const requiredFolders = [
+  '00-standards',
+  '05-test-plans',
+  '06-defects',
+  '07-automation',
+];
+
+for (const folder of requiredFolders) {
+  if (!fs.existsSync(path.join(qaRoot, folder))) {
+    errors.push(`Missing required folder: qa/${folder}/`);
+  }
+}
+
+// -----------------------------------------------------------------------
+// Check 2: Submodule spec completeness
+// -----------------------------------------------------------------------
+const SPEC_FILES = [
+  '00-inventory.md',
+  '01-business-rules.md',
+  '02-workflows.md',
+  '03-roles-permissions.md',
+  '04-test-data.md',
+  '05-test-scenarios.md',
+];
+
+const SKIP_DIRS = new Set([
+  '00-guides', '00-standards', '05-test-plans',
+  '06-defects', '07-automation', '08-azure-integration',
+]);
+
+if (fs.existsSync(qaRoot)) {
+  const topDirs = fs.readdirSync(qaRoot).filter(d => {
+    return fs.statSync(path.join(qaRoot, d)).isDirectory() && !SKIP_DIRS.has(d);
+  });
+
+  for (const moduleDir of topDirs) {
+    const modulePath = path.join(qaRoot, moduleDir);
+    const subDirs = fs.readdirSync(modulePath).filter(d =>
+      fs.statSync(path.join(modulePath, d)).isDirectory()
+    );
+
+    for (const subDir of subDirs) {
+      const subPath = path.join(modulePath, subDir);
+      for (const specFile of SPEC_FILES) {
+        if (!fs.existsSync(path.join(subPath, specFile))) {
+          errors.push(`Missing spec file: qa/${moduleDir}/${subDir}/${specFile}`);
+        }
+      }
+
+      // Strict: automation spec must exist
+      if (strict) {
+        const specTs = path.join(qaRoot, '07-automation', 'e2e', moduleDir, `${subDir}.spec.ts`);
+        if (!fs.existsSync(specTs)) {
+          warnings.push(`[STRICT] No automation spec found: qa/07-automation/e2e/${moduleDir}/${subDir}.spec.ts`);
+        }
+      }
+    }
+  }
+}
+
+// -----------------------------------------------------------------------
+// Check 3: Credential scan (basic)
+// -----------------------------------------------------------------------
+const CREDENTIAL_PATTERNS = [
+  /password\s*=\s*['"][^'"]{4,}['"]/i,
+  /token\s*=\s*['"][a-zA-Z0-9+/]{20,}['"]/i,
+  /secret\s*=\s*['"][^'"]{4,}['"]/i,
+];
+
+function scanFileForCredentials(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    for (const pattern of CREDENTIAL_PATTERNS) {
+      if (pattern.test(content)) {
+        errors.push(`Potential credential in: ${path.relative(process.cwd(), filePath)}`);
+        break;
+      }
+    }
+  } catch {}
+}
+
+const specFiles = walkFiles(path.join(qaRoot, '07-automation'), '.spec.ts');
+for (const f of specFiles) {
+  scanFileForCredentials(f);
+
+  // Check 4: TC naming pattern in spec files
+  const content = fs.readFileSync(f, 'utf8');
+  if (!content.includes('[TC-') && !content.includes('EXEC_IDX')) {
+    warnings.push(`No TC-ID naming convention found in: ${path.relative(process.cwd(), f)}`);
+  }
+
+  // Check 6 (strict): EXEC_IDX
+  if (strict && !content.includes('EXEC_IDX')) {
+    warnings.push(`[STRICT] EXEC_IDX pattern missing in: ${path.relative(process.cwd(), f)}`);
+  }
+}
+
+// -----------------------------------------------------------------------
+// Report
+// -----------------------------------------------------------------------
+console.log('');
+if (errors.length === 0 && warnings.length === 0) {
+  console.log('✅ Validation passed — no issues found.');
+  process.exit(0);
+}
+
+if (warnings.length > 0) {
+  console.log(`⚠️  ${warnings.length} warning(s):`);
+  for (const w of warnings) console.log(`   WARN  ${w}`);
+  console.log('');
+}
+
+if (errors.length > 0) {
+  console.log(`❌ ${errors.length} error(s):`);
+  for (const e of errors) console.log(`   ERROR ${e}`);
+  console.log('');
+  process.exit(1);
+} else {
+  process.exit(0);
+}
+
+// -----------------------------------------------------------------------
+// Helper
+// -----------------------------------------------------------------------
+function walkFiles(dir, ext) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(dir)) {
+    const full = path.join(dir, entry);
+    if (fs.statSync(full).isDirectory()) {
+      results.push(...walkFiles(full, ext));
+    } else if (full.endsWith(ext)) {
+      results.push(full);
+    }
+  }
+  return results;
+}

package/templates/automation-scaffold/.env.example

@@ -0,0 +1,56 @@
+# -----------------------------------------------------------------------
+# keber/qa-framework — Environment Variables Reference
+# -----------------------------------------------------------------------
+# Copy this file to .env and fill in real values.
+# NEVER commit .env to source control.
+# -----------------------------------------------------------------------
+
+# -----------------------------------------------------------------------
+# Application Under Test
+# -----------------------------------------------------------------------
+QA_BASE_URL=https://your-app.qa.example.com
+
+# -----------------------------------------------------------------------
+# Login Configuration
+# These selectors allow the framework to work with any login form.
+# -----------------------------------------------------------------------
+QA_LOGIN_PATH=/login
+QA_LOGIN_EMAIL_SELECTOR=input[type="email"]
+QA_LOGIN_PASSWORD_SELECTOR=input[type="password"]
+QA_LOGIN_SUBMIT_SELECTOR=button[type="submit"]
+# Selector that appears AFTER successful login (used by global-setup to confirm):
+QA_LOGIN_SUCCESS_SELECTOR=.dashboard
+
+# -----------------------------------------------------------------------
+# Test Users
+# Add one block per role your project uses.
+# -----------------------------------------------------------------------
+
+# Default / Standard user
+QA_USER_EMAIL=qa-user@example.com
+QA_USER_PASSWORD=CHANGE_ME
+
+# Admin user (uncomment if multi-role setup is needed)
+# QA_ADMIN_EMAIL=qa-admin@example.com
+# QA_ADMIN_PASSWORD=CHANGE_ME
+
+# Read-only / viewer user
+# QA_READONLY_EMAIL=qa-readonly@example.com
+# QA_READONLY_PASSWORD=CHANGE_ME
+
+# If your app uses RUT-based login instead of email:
+# QA_USER_RUT=12345678-9
+
+# -----------------------------------------------------------------------
+# 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
+
+# -----------------------------------------------------------------------
+# 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

package/templates/automation-scaffold/fixtures/auth.ts

@@ -0,0 +1,77 @@
+/**
+ * fixtures/auth.ts
+ *
+ * Provides a `loginAs(page, role)` helper that navigates the login form
+ * and waits for successful authentication.
+ *
+ * Usage in spec files:
+ *   import { loginAs } from '../../fixtures/auth';
+ *   // inside a test:
+ *   await loginAs(page, 'admin');
+ *
+ * Alternatively, use storageState via global-setup.ts (recommended for
+ * 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.
+ */
+
+import { Page } from '@playwright/test';
+
+export type QARole = 'default' | 'admin' | 'readonly' | string;
+
+interface LoginConfig {
+  email:     string;
+  password:  string;
+}
+
+/** Map role name → credentials from environment variables */
+function getCredentials(role: QARole): LoginConfig {
+  switch (role) {
+    case 'admin':
+      return {
+        email:    process.env.QA_ADMIN_EMAIL    ?? '',
+        password: process.env.QA_ADMIN_PASSWORD ?? '',
+      };
+    case 'readonly':
+      return {
+        email:    process.env.QA_READONLY_EMAIL    ?? '',
+        password: process.env.QA_READONLY_PASSWORD ?? '',
+      };
+    case 'default':
+    default:
+      return {
+        email:    process.env.QA_USER_EMAIL    ?? '',
+        password: process.env.QA_USER_PASSWORD ?? '',
+      };
+  }
+}
+
+/**
+ * Navigate to the login page and authenticate as the given role.
+ * Waits for the post-login success selector before resolving.
+ */
+export async function loginAs(page: Page, role: QARole = 'default'): Promise<void> {
+  const { email, password } = getCredentials(role);
+
+  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.`
+    );
+  }
+
+  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';
+  const baseURL          = process.env.QA_BASE_URL                  ?? '';
+
+  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 });
+}