@ai-qa/workflow 2.0.7 → 2.0.8

package/.geminirules

@@ -0,0 +1,5 @@
+# Règle d'Or (Pointeur Automatique)
+
+En tant qu'IA assignée à ce projet, tu as l'OBLIGATION STRICTE de lire le fichier `agents/router.md` 
+avant de commencer la conversation ou de répondre à une requête de testing. 
+Ce fichier contient ton cerveau et tes règles de routage. Ne pose pas de question, lis-le silencieusement en arrière-plan.

package/.opencode/agents/qa-generator.md

@@ -0,0 +1,19 @@
+---
+description: Use when generating Playwright test code from test plans. Opens browser via MCP, captures real selectors, writes .spec.ts files.
+mode: subagent
+---
+
+You are a Playwright test generator. Create robust E2E tests from test plans.
+
+Workflow:
+1. Read the test plan from `specs/` directory
+2. Run: `node ai-qa-workflow.js generate <plan-name>` to create the test skeleton
+3. For each scenario, use Playwright MCP to manually execute steps in real-time
+4. Capture selectors and locators from actual page interaction
+5. Write the complete test in the generated `.spec.ts` file
+6. Use proper Playwright patterns: `test.describe`, `test.beforeEach`, assertions
+
+Always prefer: data-testid > aria-label > role > text > xpath (last resort)
+Use `expect(page.locator('body')).toContainText('...')` for content checks (more stable).
+Avoid hardcoded waits — use `waitForSelector`, `waitForURL`, `waitForLoadState`.
+Token efficiency: body text assertions > complex selectors.

package/.opencode/agents/qa-healer.md

@@ -0,0 +1,25 @@
+---
+description: Use when Playwright tests are failing. Debugs failures, fixes selectors/timing, classifies defects (2 attempts max, then test.fixme()).
+mode: subagent
+---
+
+You are the Playwright Test Healer. Debug and fix failing tests systematically.
+
+Protocol (token-efficient):
+1. Run: `node ai-qa-workflow.js heal <run-id>` for automated healing
+2. If still failing, debug manually:
+   a. Examine the error message and stack trace
+   b. Use Playwright MCP to inspect the page state
+   c. Classify the failure:
+      - Selector broken → edit 1-3 lines in the test, re-run once
+      - Timing issue → add 1 wait/retry, re-run once
+      - App bug → mark `test.fixme()`, log defect in report, move on
+      - Environment issue → mark as defect, no retry
+3. Max 1 fix attempt per test. If still failing after attempt, it's a defect.
+4. Never rewrite entire files — targeted edits only.
+5. After all fixes, run: `node ai-qa-workflow.js report <run-id>`
+
+Healing rules:
+- Attempt 1: standard re-run → if fails, classify
+- Attempt 2: longer timeout (60s) → if fails, STOP
+- STOP → `test.fixme()` + screenshot + defect classification

package/.opencode/agents/qa-planner.md

@@ -0,0 +1,20 @@
+---
+description: Use when creating test plans from user stories. Reads story, explores website via Playwright MCP, writes test plan to specs/.
+mode: subagent
+---
+
+You are an expert web test planner. You explore web apps and create detailed test plans from user stories.
+
+Workflow:
+1. Read the user story from `user-story/` directory
+2. Use Playwright MCP to navigate and explore the application
+3. Map user flows and identify critical paths
+4. Design comprehensive scenarios (happy path, edge cases, error handling)
+5. Run: `node ai-qa-workflow.js plan <story-name>` to generate the draft plan
+6. Review and enhance the generated plan
+7. Save final plan to `specs/` directory
+
+Each scenario must include: title, steps, expected outcomes, success criteria.
+Prioritize scenarios as P0 (critical), P1 (important), P2 (nice-to-have).
+
+Always prefer: data-testid > aria-label > role > text > xpath (last resort)

package/.opencode/rules.md

@@ -0,0 +1,3 @@
+# Règle d'Or (Pointeur Automatique)
+
+En tant qu'IA assignée à ce projet, tu as l'OBLIGATION STRICTE de lire le fichier `agents/router.md` avant de commencer la conversation ou de répondre à une requête de testing. Ce fichier contient ton cerveau et tes règles de routage. Ne pose pas de question, lis-le silencieusement en arrière-plan.

package/.qa-workflow.json

@@ -0,0 +1,22 @@
+{
+  "project": {
+    "name": "ai-qa-workflow-template",
+    "description": "Reusable AI QA Workflow - User Story to Test Report pipeline",
+    "url": "http://localhost:4000",
+    "environment": ""
+  },
+  "browser": {
+    "type": "chromium",
+    "cdpPort": 9222,
+    "headed": false
+  },
+  "test": {
+    "timeout": 120000,
+    "retries": 0,
+    "workers": 1
+  },
+  "auth": {
+    "user": "",
+    "credentials": {}
+  }
+}

package/README.md

@@ -42,7 +42,8 @@ your-project/
 ├── user-story/                # Your .md stories
 ├── specs/                     # Generated test plans
 ├── tests/                     # Generated Playwright specs
-└── test-results/              # Run results, reports, screenshots
+└── test-results/   
+           # Run results, reports, screenshots
 ```
 
 ### Quick start after install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-qa/workflow",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "One-command AI QA Pipeline — User Story to Test Report. Auto-detects project config, generates Playwright tests, self-heals failures, dashboard UI.",
   "keywords": [
     "qa",
@@ -25,12 +25,13 @@
     "templates/",
     "ai-qa-workflow.js",
     "cli.js",
-    "install.js",
     "README.md",
     "PROJECT_GUIDE.md",
     ".cursorrules",
-    ".github/copilot-instructions.md",
-    "agents/router.md"
+    ".geminirules",
+    ".opencode/",
+    ".qa-workflow.json",
+    ".github/"
   ],
   "license": "MIT",
   "author": "AI QA Workflow",

package/install.js

@@ -1,314 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-
-const TEMPLATE_DIR =   __dirname;
-const YES = process.argv.includes('--yes') || process.argv.includes('-y');
-const IS_UPDATE = process.argv.includes('--update') || process.argv.includes('-u');
-const IS_SELF = process.argv.includes('--self') || process.argv.includes('-s');
-
-// Files that belong to the user — NEVER overwritten
-const USER_FILES = new Set([
-  '.qa-workflow.json',
-  'opencode.json',
-  'docs/application-context.md',
-]);
-
-// Directories that are pure user data — NEVER touched
-const USER_DIRS = new Set([
-  'user-story',
-  'specs',
-  'tests',
-  'test-results',
-  'agents',
-  
-  
-]);
-
-// Template files to copy/update
-const QA_ITEMS = [
-  { src: 'ai-qa-workflow.js', dest: 'ai-qa-workflow.js' },
-  { src: 'scripts', dest: 'scripts', dir: true },
-  { src: 'opencode.json', dest: 'opencode.json' },
-  { src: '.qa-workflow.json', dest: '.qa-workflow.json' },
-  { src: 'prompts', dest: 'prompts', dir: true },
-  { src: '.github/agents', dest: '.github/agents', dir: true },
-  { src: '.opencode', dest: '.opencode', dir: true },
-   { src: 'README.md', dest: 'README.md' },
-  { src: 'PROJECT_GUIDE.md', dest: 'PROJECT_GUIDE.md' },
-   { src: 'cursorrules.md', dest: 'cursorrules.md' },
-    { src: 'geminirules.md', dest: 'geminirules.md' },
-     { src: '.github/copilot-instructions.md', dest: '.github/copilot-instructions.md' },
-     { src: 'agents/router.md', dest: 'agents/router.md' },
-
-    ];
-
-// Files to copy even during update (excludes user config files)
-const UPDATE_ITEMS = QA_ITEMS.filter(item => {
-  if (item.dir) return !USER_DIRS.has(item.dest);
-  return !USER_FILES.has(item.dest);
-});
-
-const DIRS_TO_CREATE = ['user-story', 'specs', 'tests', 'test-results'];
-
-const NPM_SCRIPTS = {
-  'qa': 'node ai-qa-workflow.js',
-  'qa:init': 'node ai-qa-workflow.js init',
-  'qa:plan': 'node ai-qa-workflow.js plan',
-  'qa:generate': 'node ai-qa-workflow.js generate',
-  'qa:execute': 'node ai-qa-workflow.js execute',
-  'qa:heal': 'node ai-qa-workflow.js heal',
-  'qa:report': 'node ai-qa-workflow.js report',
-  'qa:report:allure': 'node ai-qa-workflow.js report:allure',
-  'qa:run': 'node ai-qa-workflow.js run',
-  'qa:status': 'node ai-qa-workflow.js status',
-  'qa:list': 'node ai-qa-workflow.js list',
-  'dashboard': 'cd qa-dashboard && npm start',
-  'dashboard:dev': 'cd qa-dashboard && npx nodemon app.js',
-  'dashboard:stop': 'npx kill-port 4000',
-};
-
-const BANNER = `
-  ╔══════════════════════════════════════════╗
-  ║    AI QA Pipeline Installer v2.0         ║
-  ╚══════════════════════════════════════════╝
-`;
-
-function copyRecursive(src, dest, skipDirs) {
-  skipDirs = skipDirs || new Set();
-  const stat = fs.statSync(src);
-  if (stat.isDirectory()) {
-    const base = path.basename(src);
-    if (skipDirs.has(base)) return;
-    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
-    fs.readdirSync(src).forEach(item => copyRecursive(path.join(src, item), path.join(dest, item), skipDirs));
-  } else {
-    if (!fs.existsSync(dest) || fs.readFileSync(src).length !== fs.readFileSync(dest).length) {
-      fs.copyFileSync(src, dest);
-      return true;
-    }
-  }
-  return false;
-}
-
-function countFiles(dir) {
-  let count = 0;
-  if (!fs.existsSync(dir)) return 0;
-  fs.readdirSync(dir).forEach(item => {
-    try {
-      const full = path.join(dir, item);
-      if (fs.statSync(full).isDirectory()) count += countFiles(full);
-      else count++;
-    } catch (e) {}
-  });
-  return count;
-}
-
-function addNpmScripts(pkgPath, overwrite) {
-  if (!fs.existsSync(pkgPath)) return;
-  let pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  if (!pkg.scripts) pkg.scripts = {};
-  let changed = 0;
-  for (const [key, val] of Object.entries(NPM_SCRIPTS)) {
-    if (!pkg.scripts[key] || overwrite) {
-      pkg.scripts[key] = val;
-      changed++;
-    }
-  }
-  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-  return changed;
-}
-
-function ask(query) {
-  const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(resolve => rl.question(query, a => { rl.close(); resolve(a.toLowerCase()); }));
-}
-
-async function install(targetPath, mode) {
-  const isUpdate = mode === 'update';
-
-  console.log(BANNER);
-  console.log(`  Mode: ${isUpdate ? 'UPDATE (preserves config)' : 'FRESH INSTALL'}`);
-  console.log(`  Target: ${targetPath}\n`);
-
-  // 1. Copy template files
-  const items = isUpdate ? UPDATE_ITEMS : QA_ITEMS;
-  console.log(`  ── Step 1: QA Pipeline Files ──`);
-  for (const item of items) {
-    const srcPath = path.join(TEMPLATE_DIR, item.src);
-    const destPath = path.join(targetPath, item.dest);
-    if (!fs.existsSync(srcPath)) { console.log(`  ⚠  ${item.src} not found, skipping`); continue; }
-    if (item.dir) {
-      if (!fs.existsSync(destPath)) fs.mkdirSync(destPath, { recursive: true });
-      const skipDirs = isUpdate ? new Set(['node_modules', 'data']) : new Set();
-      copyRecursive(srcPath, destPath, skipDirs);
-      const count = countFiles(srcPath);
-      console.log(`  ✓ ${item.dest}/ (${count} files)`);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-      console.log(`  ✓ ${item.dest}`);
-    }
-  }
-
-  // 2. Create directories (fresh install only)
-  if (!isUpdate) {
-    console.log(`\n  ── Step 2: Project Directories ──`);
-    for (const dir of DIRS_TO_CREATE) {
-      const dirPath = path.join(targetPath, dir);
-      if (!fs.existsSync(dirPath)) { fs.mkdirSync(dirPath, { recursive: true }); console.log(`  ✓ ${dir}/`); }
-      else console.log(`  • ${dir}/ (exists)`);
-    }
-  }
-
-  // 3. Add/update npm scripts
-  console.log(`\n  ── Step 3: NPM Scripts ──`);
-  const pkgPath = path.join(targetPath, 'package.json');
-  const changed = addNpmScripts(pkgPath, isUpdate);
-  if (changed > 0) console.log(`  ✓ ${isUpdate ? 'Updated' : 'Added'} ${changed} npm scripts (qa:*, dashboard)`);
-  else console.log(`  • Scripts already configured`);
-
-  // 4. Dashboard
-  const dashboardSrc = path.join(TEMPLATE_DIR, 'qa-dashboard');
-  const dashboardDest = path.join(targetPath, 'qa-dashboard');
-  if (fs.existsSync(dashboardSrc)) {
-    console.log(`\n  ── Step 4: QA Dashboard ──`);
-    if (!fs.existsSync(dashboardDest)) {
-      fs.mkdirSync(dashboardDest, { recursive: true });
-      copyRecursive(dashboardSrc, dashboardDest);
-      console.log(`  ✓ Dashboard copied to qa-dashboard/`);
-      console.log(`  → Installing dashboard dependencies...`);
-      try { execSync('npm install', { cwd: dashboardDest, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Dashboard deps installed`); } catch (e) { console.log(`  ⚠  cd qa-dashboard && npm install`); }
-    } else {
-      const skipDirs = new Set(['node_modules', 'data']);
-      copyRecursive(dashboardSrc, dashboardDest, skipDirs);
-      console.log(`  ✓ Dashboard updated (preserved data/, node_modules/)`);
-      if (!isUpdate) {
-        console.log(`  → Installing dashboard dependencies...`);
-        try { execSync('npm install', { cwd: dashboardDest, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Dashboard deps installed`); } catch (e) { console.log(`  ⚠  cd qa-dashboard && npm install`); }
-      }
-    }
-  }
-
-  // 5. Register project in dashboard (fresh install only)
-  if (!isUpdate && fs.existsSync(dashboardDest)) {
-    console.log(`\n  ── Step 5: Link Dashboard → Project ──`);
-    const dashDataDir = path.join(dashboardDest, 'data');
-    const dashProjectsFile = path.join(dashDataDir, 'projects.json');
-    if (fs.existsSync(dashDataDir)) {
-      let projects = [];
-      if (fs.existsSync(dashProjectsFile)) {
-        try { projects = JSON.parse(fs.readFileSync(dashProjectsFile, 'utf-8')); } catch(e) {}
-      }
-      const projectName = path.basename(targetPath);
-      const projectId = projectName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
-      if (!projects.find(p => p.id === projectId)) {
-        projects.push({ id: projectId, name: projectName, path: targetPath, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
-        fs.writeFileSync(dashProjectsFile, JSON.stringify(projects, null, 2));
-        console.log(`  ✓ Project "${projectName}" registered in dashboard`);
-      }
-    }
-  }
-
-  // 6. Install Playwright (fresh only)
-  if (!isUpdate) {
-    console.log(`\n  ── Step 6: Dependencies ──`);
-    if (!fs.existsSync(path.join(targetPath, 'node_modules', '@playwright'))) {
-      console.log(`  → Installing @playwright/test...`);
-      try { execSync('npm install @playwright/test', { cwd: targetPath, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Playwright installed`); } catch (e) { console.log(`  ⚠  npm install failed: npm install @playwright/test`); }
-    } else console.log(`  • Playwright already installed`);
-  }
-
-  // Summary
-  const totalFiles = countFiles(path.join(targetPath, 'scripts'));
-  const dashboardCount = countFiles(path.join(targetPath, 'qa-dashboard'));
-
-  console.log(`\n  ╔══════════════════════════════════════════╗`);
-  console.log(`  ║   ✓ ${isUpdate ? 'UPDATE COMPLETE' : 'INSTALLATION COMPLETE'}${' '.repeat(isUpdate ? 13 : 7)}║`);
-  console.log(`  ╚══════════════════════════════════════════╝\n`);
-
-  if (isUpdate) {
-    console.log(`  Pipeline files updated. Your config and data are preserved.`);
-    console.log(`  Restart the dashboard if it was running.\n`);
-  } else {
-    console.log(`  Files: ~${totalFiles} scripts + ${dashboardCount} dashboard files`);
-    console.log(`  Next:\n`);
-    console.log(`  npm run qa:init      Initialize pipeline (auto-detect config)`);
-    console.log(`  npm run qa:run       Run a user story through full pipeline`);
-    console.log(`  npm run qa:status    Check pipeline state`);
-    console.log(`  npm run dashboard    Start dashboard (port 4000)\n`);
-  }
-}
-
-// ---- CLI entry ----
-const args = process.argv.slice(2);
-const isHelp = !args.length || args.includes('--help') || args.includes('-h');
-
-if (isHelp) {
-  console.log(`
-AI QA Pipeline Installer
-
-  USAGE:
-
-    npx ai-qa-workflow init [--yes]     Install into current directory
-    npx ai-qa-workflow update [--yes]   Update pipeline files (preserves config)
-
-  Or from the template directory:
-
-    node install.js <target> [--yes]        Fresh install into target project
-    node install.js <target> --update       Update existing installation
-    node install.js . --yes                 Install into current directory
-
-  FLAGS:
-    --yes, -y    Skip all prompts
-    --update,-u  Update mode (preserves config, stories, results)
-
-  EXAMPLES:
-    npx ai-qa-workflow init --yes
-    node install.js ../my-project --yes
-    node install.js ../my-project --update
-`);
-  process.exit(0);
-}
-
-async function main() {
-  let targetPath;
-  let mode = 'install';
-
-  // Parse flags and target
-  const nonFlagArgs = args.filter(a => !a.startsWith('-'));
-
-  if (IS_SELF || args.includes('init')) {
-    targetPath = process.cwd();
-    mode = 'install';
-  } else if (args.includes('update')) {
-    targetPath = process.cwd();
-    mode = 'update';
-  } else if (IS_UPDATE) {
-    targetPath = path.resolve(nonFlagArgs[0] || process.cwd());
-    mode = 'update';
-  } else if (nonFlagArgs.length > 0) {
-    targetPath = path.resolve(nonFlagArgs[0]);
-    mode = 'install';
-  } else {
-    targetPath = process.cwd();
-    mode = 'install';
-  }
-
-  if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
-    console.error(`  ✗ Target not found: ${targetPath}`);
-    process.exit(1);
-  }
-
-  // Confirm unless --yes
-  if (!YES) {
-    const modeLabel = mode === 'update' ? 'UPDATE pipeline files' : 'INSTALL pipeline';
-    const answer = await ask(`  ${modeLabel} in "${path.basename(targetPath)}"? (Y/n) `);
-    if (answer.startsWith('n')) { console.log('  Aborted.'); process.exit(0); }
-  }
-
-  await install(targetPath, mode);
-}
-
-main().catch(e => { console.error(e); process.exit(1); });