@ai-qa/workflow 2.0.16 → 2.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-qa/workflow",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "description": "AI QA Workflow Template — transforms any AI agent into an autonomous QA engineer. AI explores, plans, generates tests, and heals. Scripts execute and report.",
   "keywords": [
     "qa",
@@ -33,7 +33,9 @@
     "opencode.json",
     ".qa-workflow.json",
     "router.md",
+    "tsconfig.json",
     ".github/",
+    "tsconfig.json",
     ".env"
   ],
   "license": "MIT",
@@ -57,15 +59,15 @@
     "qa:report:allure": "node ai-qa-workflow.js report:allure",
     "qa:status": "node ai-qa-workflow.js status",
     "qa:list": "node ai-qa-workflow.js list",
+    "qa:update": "node install.js . --update --yes",
     "dashboard": "cd qa-dashboard && npm start",
     "dashboard:dev": "cd qa-dashboard && npx nodemon app.js",
-    "dashboard:stop": "npx kill-port 4000"
+    "dashboard:stop": "npx kill-port 4000",
+    "allure:generate": "allure generate allure-results -o allure-report --clean",
+    "allure:open": "allure open allure-report",
+    "allure:serve": "allure serve allure-results"
   },
   "devDependencies": {
-    "@playwright/test": "^1.52.0",
-    "allure-playwright": "^3.2.1",
-    "allure-commandline": "^2.33.0",
-    "@applitools/eyes-playwright": "^1.42.0",
-    "@applitools/mcp": "^1.5.0"
+    "@types/node": "^25.9.2"
   }
 }

package/playwright.config.ts

@@ -6,6 +6,16 @@ export default defineConfig({
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
   workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['list'],
+    ['json', { outputFile: 'test-results/playwright-report.json' }],
+    ['html', { outputFolder: 'playwright-report' }],
+     ['allure-playwright', {
+      outputFolder: 'allure-results',
+      detail: true,
+    }],
+  ],
+
   use: {
     baseURL: process.env.APP_URL || 'http://localhost:3000',
     trace: 'on-first-retry',

package/prompting_template.md

@@ -1,283 +1,52 @@
-# Prompting Template — How to Talk to the AI QA Agent
+# Prompting Template — AI QA Agent
 
-This guide covers every prompt you need — from installation to final report. Use it as your conversation script.
+## Quick Start
 
----
-
-## Quick Start (Copy-Paste Ready)
-
-After installing the template and writing a user story, open your AI editor and send:
-
-> **"Read router.md and follow the QA workflow for my-story.md"**
-
-That's it. The AI handles everything from there, stopping at each phase for your approval.
-
----
-
-## Phase-by-Phase Prompts
-
-### Phase 0: First Contact (Environment Check)
-
-When you open the project for the **first time**, the AI automatically runs an environment check. If it doesn't, or if you want to re-check:
-
-> **"Run the environment check and tell me what's ready and what's missing"**
-
-The AI will report:
-- ✅ What's installed and configured
-- ✅ Pipeline state from `.qa-context/pipeline.json` (phases completed, last run)
-- ✅ Auth status from `.auth/credentials.json` (credentials found or missing)
-- ❌ What's missing (with commands to fix)
-- 📋 What it needs from you (user story, credentials, etc.)
-
-The AI **automatically reads `.qa-context/pipeline.json`, `.qa-context/selectors.json`, and `.qa-context/heal-history.json`** to understand the current state before starting any phase.
-
----
-
-### Phase 1: Test Planning
-
-You have a user story. You want the AI to explore the app and write a test plan.
-
-> **"Read router.md and plan tests for my-story.md"**
-
-The AI will:
-1. Read `router.md` → routes to `playwright-test-planner.agent.md`
-2. Open your app with Playwright MCP
-3. Explore navigation, flows, and UI components
-4. Map critical paths and edge cases
-5. Write a test plan to `specs/my-story-test-plan.md`
-6. **STOP and present the plan to you**
-
-#### What you should review in the plan:
-- Are all acceptance criteria covered?
-- Are edge cases and negative scenarios included?
-- Are the preconditions accurate?
-- Does the environment URL match your running app?
-
-#### Approval responses:
-| You say | Result |
-|---------|--------|
-| "Looks good, continue" | AI proceeds to test generation |
-| "Approved" | Same |
-| "Add a scenario for X" | AI updates the plan, then waits again |
-| "I'll review later, proceed" | AI proceeds (use with caution) |
-
----
-
-### Phase 2: Test Generation
-
-The plan is approved. Now you want the AI to write real Playwright tests.
-
-> **"Generate tests from the plan in specs/my-story-test-plan.md"**
-
-Or simply (if already in context):
-
-> **"Generate the tests"**
-
-The AI will:
-1. Read `playwright-test-generator.agent.md`
-2. Read `prompts/QAe2eprompt.md` for conventions
-3. Use Playwright MCP to manually execute each scenario
-4. Capture real selectors from the actual page
-5. Add visual checkpoints via Applitools on critical pages (if `APPLITOOLS_API_KEY` is set)
-6. Write complete Playwright `.spec.ts` files to `tests/`
-7. **STOP and present the code to you**
-
-#### What you should review in the test code:
-- Are selectors using real elements? (no hallucinated CSS classes)
-- Are assertions meaningful?
-- Are visual checkpoints added on critical pages? (login, dashboard, checkout)
-- Does the test handle auth/state correctly?
-- Are there timeouts or waits that might flake?
-
-#### Approval responses:
-| You say | Result |
-|---------|--------|
-| "Code looks good, execute" | User runs tests, or AI suggests running |
-| "Approved" | Same |
-| "Fix the selector on line 23" | AI corrects it, presents again |
-| "Add a test for X edge case" | AI adds the scenario, presents again |
-
----
-
-### Phase 3: Execution
-
-Tests are written and approved. Time to run them.
-
-> **User runs:** `npm run qa:execute [test-name]`
-
-Or, if you want the AI to trigger execution (if it has shell access):
-
-> **"Execute the tests and report back"**
-
-The AI runs Playwright and reports:
-- ✅ Tests passed → ready for report
-- ❌ Tests failed → moves to healing phase
-
----
-
-### Phase 4: Healing (Debugging Failures)
-
-Tests failed. You want the AI to fix them.
-
-> **"Debug and fix the failing tests"**
-
-Or specifically:
-
-> **"Read playwright-test-healer.agent.md and debug the failures in test-results/latest-run"**
-
-The AI will:
-1. Read `playwright-test-healer.agent.md`
-2. Run the failing tests with `test_run`
-3. Debug with `test_debug` — examine the actual UI state
-4. Classify the failure:
-   - **Selector broken** → proposes 1-3 line fix
-   - **Timing issue** → proposes adding a wait
-   - **App bug** → marks `test.fixme()`, logs defect
-5. **STOP and present diagnosis + proposed fix to you**
-
-#### What you should review in the diagnosis:
-- What exactly failed and why
-- What the AI wants to change (which file, which lines)
-- Is it a test issue or a real bug in your app?
-
-#### Approval responses:
-| You say | Result |
-|---------|--------|
-| "Fix it" | AI applies the 1-3 line fix and re-runs |
-| "Approved, apply the fix" | Same |
-| "That's a real bug, file it" | AI marks as defect, moves on |
-| "Try a different approach" | AI suggests alternative fix |
-| "Skip it, I'll investigate later" | AI marks as `test.fixme()` |
-
----
-
-### Phase 5: Report
-
-Tests are done. You want a summary.
-
-> **"Generate the execution report"**
-
-Or manually:
-
-> **User runs:** `npm run qa:report [run-id]`
-
-The AI will:
-1. Run `npm run qa:report` (or read the results directly)
-2. Present a summary: passed, failed, healed, defects found
-3. Update `docs/application-context.md` with learned selectors and flaky areas
-
----
-
-## Quick Reference — All Prompts in One Table
-
-| Phase | Your prompt | AI does | You do |
-|-------|------------|---------|--------|
-| **0** | *(automatic on first open)* | Environment check | Read status report |
-| **0** | "Run the environment check" | Re-check setup | Fix any missing items |
-| **1** | "Read router.md and plan tests for my-story.md" | Explore app, write plan | **Review + approve** |
-| **2** | "Generate tests from the plan" | Write Playwright code | **Review + approve** |
-| **3** | `npm run qa:execute` | Run tests | Check results |
-| **4** | "Debug and fix the failing tests" | Diagnose, propose fix | **Review + approve** |
-| **5** | "Generate the report" | Summarize results | Review final report |
+```text
+"Read router.md and follow the QA workflow for my-story.md"
+```
 
 ---
 
-## Best Practices
-
-### For Best Results
-
-1. **Write structured user stories** — Use the format in the README. Clear acceptance criteria produce better test plans.
-
-2. **Review the plan first** — The AI's understanding of your app is only as good as its exploration. Catch incorrect assumptions early.
-
-3. **Don't skip the approval gates** — Each gate is a chance to redirect the AI before it wastes time on the wrong approach.
-
-4. **Be specific in your feedback** — Instead of "this looks wrong", say "the selector on line 23 should use `data-testid` instead of class name".
-
-5. **Provide context upfront** — Populate `docs/application-context.md` with stable selectors, auth details, and tech stack notes before starting. The AI also reads `.qa-context/` automatically — you don't need to tell it.
-
-6. **Memory is persistent** — The AI stores its learning in `.qa-context/` (selectors, healing history, pipeline state). This means each session starts smarter than the last. Don't delete this folder unless you want to reset the AI's memory.
+## Commandes essentielles
 
-7. **Credentials are stored once** — The AI saves your login to `.auth/credentials.json` after first use. If your password changes, just update that file or delete it and the AI will ask again.
-
-6. **Use `npm run qa:retry` for simple flakes** — If a test fails intermittently, try the mechanical retry first before asking the AI to debug.
-
-7. **Token efficiency works both ways** — Keep your feedback concise. The AI is designed for 1-3 line fixes and targeted edits.
-
-### Common Mistakes to Avoid
-
-| Mistake | Better approach |
-|---------|----------------|
-| Sending a vague "test my app" prompt | "Read router.md and plan tests for user-story/login.md" |
-| Approving without reviewing the plan | Always check: does it cover the acceptance criteria? |
-| Letting the AI generate tests without a plan | Always do Phase 1 before Phase 2 |
-| Running tests before reviewing the code | AI can hallucinate selectors — verify them first |
-| Asking the AI to fix everything at once | One test at a time: "Debug the login test failure" |
-| Skipping the approval gate | You're the supervisor for a reason |
+| Phase | Prompt / Commande |
+|---|---|
+| Environment check | `"Run the environment check"` |
+| Planifier les tests | `"Read router.md and plan tests for user-story/my-story.md"` |
+| Générer les tests | `"Generate tests from specs/my-story-test-plan.md"` |
+| Exécuter | `npm run qa:execute` |
+| Auto-guérir | `"Debug and fix the failing tests"` |
+| Rapport | `npm run qa:report` ou `"Generate the report"` |
 
 ---
 
-## Example Full Session
-
-```
-You: "Read router.md and plan tests for login-story.md"
-
-AI: [Explores app, writes plan to specs/login-story-test-plan.md]
-    "Plan is ready. Here's what I found:
-     - 3 scenarios: login success, wrong password, locked account
-     - 1 concern: no visible error toast for locked accounts
-     Do you approve?"
-
-You: "Looks good, but add a scenario for empty email field."
-
-AI: [Updates plan]
-    "Added. 4 scenarios now. Approve?"
-
-You: "Approved, generate the tests."
-
-AI: [Writes tests/login-story.spec.ts]
-    "Tests generated. I used getByRole for buttons and getByLabel for inputs.
-    Do you approve the code?"
-
-You: "Looks good, execute."
+## Exemple de session complète
 
-AI: "Run: npm run qa:execute login-story"
+```text
+1. "Read router.md and plan tests for user-story/my-story.md"
+   → L'IA explore l'app, écrit specs/my-story-test-plan.md
+   → STOP — vous validez
 
-You: [Runs it] "Two tests failed — wrong password and locked account."
+2. "Approved, generate the tests"
+   → L'IA écrit tests/my-story.spec.ts
+   → STOP — vous validez
 
-AI: [Debugs]
-    "Diagnosis:
-     - Wrong password: error message class changed, needs new selector
-     - Locked account: the lock icon isn't rendering (app bug)
-     Fix the selector on line 42? Approve?"
+3. npm run qa:execute
+   → Tests exécutés
 
-You: "Fix the selector, mark the lock icon as a bug."
-
-AI: [Applies fix, re-runs, marks test.fixme()]
-    "Fixed: wrong password now passes. Locked account marked as defect.
-    Generate the report?"
+4. "Debug and fix the failing tests"
+   → L'IA diagnostique, corrige, réessaie (max 2x)
+   → STOP — vous validez
 
-You: "Yes, generate it."
+5. npm run qa:report:allure
+   → Rapport Allure généré
 ```
 
 ---
 
-## Quick Copy-Paste
-
-### Minimal workflow (5 prompts total)
+## Règles
 
-```
-1. "Read router.md and plan tests for my-story.md"
-2. "Approved" (after reviewing plan)
-3. "Approved" (after reviewing tests)
-   (run npm run qa:execute)
-4. "Debug and fix the failing tests"
-5. "Approved, apply the fix" (after reviewing diagnosis)
-   (run npm run qa:report)
-```
-
-### Single command to start everything
-
-```
-"Read router.md and follow the QA workflow for my-story.md"
-```
+- L'IA propose → vous approuvez → L'IA exécute
+- Ne jamais sauter la validation (Phase 1 → plan, Phase 2 → code)
+- 1 erreur à la fois pour le debug

package/qa-dashboard/app.js

@@ -89,11 +89,15 @@ app.use('/runs', require('./routes/runs'));
 app.use('/review', require('./routes/review'));
 app.use('/analytics', require('./routes/analytics'));
 app.use('/export', require('./routes/export'));
+app.use('/terminal', require('./routes/terminal'));
 app.use('/data', require('./routes/test-data'));
 
 app.use((req, res) => { res.status(404).render('error', { message: 'Page not found' }); });
 
 app.listen(PORT, () => {
-  console.log(`QA Dashboard running at http://localhost:${PORT}`);
-  console.log(`Close the browser tab to stop the server.`);
+  console.log(`\n  ┌─────────────────────────────────────┐`);
+  console.log(`  │   Orchestrator QA Dashboard        │`);
+  console.log(`  │   http://localhost:${PORT}${' '.repeat(9 - String(PORT).length)}│`);
+  console.log(`  └─────────────────────────────────────┘`);
+  console.log(`  Close the browser tab to stop the server.\n`);
 });

package/qa-dashboard/package.json

@@ -5,7 +5,7 @@
   "main": "app.js",
   "scripts": {
     "start": "node app.js",
-    "dev": "node app.js"
+    "dev": "nodemon app.js"
   },
   "dependencies": {
     "chart.js": "^4.4.0",
@@ -14,5 +14,8 @@
     "express": "^4.18.2",
     "express-ejs-layouts": "^2.5.1",
     "morgan": "^1.10.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.0"
   }
 }

package/qa-dashboard/routes/index.js

@@ -5,7 +5,6 @@ const pm = require('../services/project-manager');
 router.get('/', (req, res) => {
   const projects = pm.getAll();
 
-  // Single-project mode: always use the first (and only) registered project
   const project = projects.length > 0 ? projects[0] : null;
 
   let stats = {
@@ -15,7 +14,10 @@ router.get('/', (req, res) => {
     runs: 0,
     passedRuns: 0,
     passRate: 0,
-    lastRunStatus: null, // 'passed' | 'failed' | null
+    lastRunStatus: null,
+    storiesList: [],
+    latestRun: null,
+    hasAllure: false,
   };
 
   if (project) {
@@ -27,6 +29,18 @@ router.get('/', (req, res) => {
     stats.plans   = list.plans.length;
     stats.specs   = list.specs.length;
     stats.runs    = runDirs.length;
+    stats.hasAllure = bridge.hasAllureReport();
+
+    stats.storiesList = list.stories.map(s => {
+      const baseName = s.replace(/\.md$/i, '');
+      return {
+        name: s,
+        hasPlan: list.plans.some(p => p.toLowerCase().includes(baseName.toLowerCase())),
+        planName: list.plans.find(p => p.toLowerCase().includes(baseName.toLowerCase())),
+        hasSpec: list.specs.some(sp => sp.toLowerCase().includes(baseName.toLowerCase())),
+        specName: list.specs.find(sp => sp.toLowerCase().includes(baseName.toLowerCase())),
+      };
+    });
 
     if (runDirs.length > 0) {
       const results = runDirs.map(d => bridge.getRunResult(d.name)).filter(Boolean);
@@ -35,9 +49,17 @@ router.get('/', (req, res) => {
         ? Math.round((stats.passedRuns / results.length) * 100)
         : 0;
 
-      // Most recent run result
       const latest = bridge.getRunResult(runDirs[0].name);
-      if (latest) stats.lastRunStatus = latest.success ? 'passed' : 'failed';
+      if (latest) {
+        stats.lastRunStatus = latest.success ? 'passed' : 'failed';
+        stats.latestRun = {
+          id: runDirs[0].name,
+          duration: latest.duration,
+          passedCount: latest.passedTests ? latest.passedTests.length : 0,
+          failedCount: latest.failedTests ? latest.failedTests.length : 0,
+          testName: latest.test,
+        };
+      }
     }
   }
 

package/qa-dashboard/routes/projects.js

@@ -29,7 +29,31 @@ router.get('/:id', (req, res) => {
   const statusResult = bridge.status();
   const list = bridge.listAll();
 
-  res.render('project', { project, status: statusResult, list });
+  const storiesWithStatus = list.stories.map(s => {
+    const baseName = s.replace(/\.md$/i, '');
+    const planName = list.plans.find(p => p.toLowerCase().includes(baseName.toLowerCase()));
+    const specName = list.specs.find(sp => sp.toLowerCase().includes(baseName.toLowerCase()));
+    const runDirs = bridge.getRunDirs();
+    const hasRun = runDirs.some(d => {
+      const result = bridge.getRunResult(d.name);
+      return result && result.test && result.test.toLowerCase().includes(baseName.toLowerCase());
+    });
+    return {
+      name: s,
+      baseName,
+      hasPlan: !!planName,
+      planName,
+      hasSpec: !!specName,
+      specName,
+      hasRun,
+    };
+  });
+
+  const hasAllure = bridge.hasAllureReport();
+  const runDirs = bridge.getRunDirs();
+  const latestRun = runDirs.length > 0 ? runDirs[0].name : null;
+
+  res.render('project', { project, status: statusResult, list, storiesWithStatus, hasAllure, latestRun });
 });
 
 router.post('/:id/remove', (req, res) => {

package/qa-dashboard/routes/runs.js

@@ -115,4 +115,42 @@ router.get('/:runId/compare/:otherRunId', (req, res) => {
   ] });
 });
 
+// Rerun a specific test from a previous run
+router.post('/:runId/rerun', (req, res) => {
+  const projectId = req.query.project;
+  const project = projectId ? pm.get(projectId) : pm.getAll()[0];
+  if (!project) return res.status(404).json({ error: 'Project not found' });
+
+  const bridge = pm.getBridge(project.id);
+  const result = bridge.getRunResult(req.params.runId);
+  if (!result) return res.status(404).json({ error: 'Run not found' });
+
+  const testName = result.test || '';
+  if (!testName || testName === 'all') {
+    // Rerun all tests
+    const runResult = bridge.execute('');
+    return res.json({ success: runResult.success, output: runResult.output, error: runResult.error });
+  }
+
+  const runResult = bridge.execute(testName);
+  res.json({ success: runResult.success, output: runResult.output, error: runResult.error, runId: extractRunId(runResult.output) });
+});
+
+// Regenerate Allure report
+router.post('/allure-regenerate', (req, res) => {
+  const projectId = req.query.project;
+  const project = projectId ? pm.get(projectId) : pm.getAll()[0];
+  if (!project) return res.status(404).json({ error: 'Project not found' });
+
+  const bridge = pm.getBridge(project.id);
+  const result = bridge.runCommand('npx allure generate allure-results --clean -o allure-report');
+  res.json({ success: result.success, output: result.output, error: result.error });
+});
+
+function extractRunId(output) {
+  if (!output) return null;
+  const match = output.match(/run-[\d-T-]+/);
+  return match ? match[0] : null;
+}
+
 module.exports = router;

package/qa-dashboard/routes/stories.js

@@ -44,7 +44,24 @@ router.get('/:storyName', (req, res) => {
   const plan = planName ? bridge.getPlanContent(planName) : null;
   const spec = specName ? bridge.getSpecContent(specName) : null;
 
-  res.render('story', { project, story: { name: req.params.storyName, content, plan, planName, spec, specName } });
+  const runDirs = bridge.getRunDirs();
+  const results = runDirs.map(d => {
+    const r = bridge.getRunResult(d.name);
+    if (!r) return null;
+    const testMatch = specName ? r.test && r.test.toLowerCase().includes(baseName.toLowerCase()) : true;
+    return testMatch ? {
+      id: d.name,
+      success: r.success,
+      duration: r.duration,
+      passedCount: r.passedTests ? r.passedTests.length : 0,
+      failedCount: r.failedTests ? r.failedTests.length : 0,
+    } : null;
+  }).filter(Boolean);
+
+  const hasRun = results.length > 0;
+  const hasAllure = bridge.hasAllureReport();
+
+  res.render('story', { project, story: { name: req.params.storyName, content, plan, planName, spec, specName, results, hasRun, hasAllure } });
 });
 
 // Helper to stream CLI command output asynchronously to client

package/qa-dashboard/routes/terminal.js

@@ -0,0 +1,51 @@
+const express = require('express');
+const router = express.Router();
+const pm = require('../services/project-manager');
+const { spawn } = require('child_process');
+
+router.get('/', (req, res) => {
+  const projects = pm.getAll();
+  const projectId = req.query.project || (projects.length > 0 ? projects[0].id : null);
+  const project = projects.find(p => p.id === projectId);
+  res.render('terminal', { project, projects });
+});
+
+// Execute a command asynchronously with streaming output
+router.post('/run', (req, res) => {
+  const projects = pm.getAll();
+  const projectId = req.query.project || (projects.length > 0 ? projects[0].id : null);
+  const project = projects.find(p => p.id === projectId);
+  if (!project) return res.status(404).send('Project not found');
+
+  const { command } = req.body;
+  if (!command) return res.status(400).send('No command provided');
+
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  res.setHeader('Transfer-Encoding', 'chunked');
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+
+  const child = spawn(command, [], {
+    cwd: project.path,
+    shell: true,
+    env: { ...process.env, FORCE_COLOR: '0' },
+  });
+
+  child.stdout.on('data', (data) => res.write(data.toString()));
+  child.stderr.on('data', (data) => res.write(data.toString()));
+
+  child.on('close', (code) => {
+    res.write(`\n\n--- [FINISHED: ${code === 0 ? 'SUCCESS' : 'FAILED'}] (exit code: ${code}) ---\n`);
+    res.end();
+  });
+
+  child.on('error', (err) => {
+    res.write(`\nError: ${err.message}\n`);
+    res.end();
+  });
+
+  req.on('close', () => {
+    if (child && !child.killed) child.kill('SIGINT');
+  });
+});
+
+module.exports = router;