@ai-qa/workflow 2.0.15 → 2.0.17

package/README.md

@@ -260,38 +260,51 @@ The AI updates `docs/application-context.md` with:
 
 ---
 
-## Installation
+## Dépendances requises
 
-### Requirements
+Installez les dépendances selon vos besoins :
 
-| Component | Needed for | Install |
-|-----------|-----------|---------|
-| **Node.js 18+** | Running the pipeline | — |
-| **Playwright** | Test execution | Pre-installed via `npm install` |
-| **Chromium** | Running tests | `npx playwright install chromium` |
-| **Playwright MCP** | AI browser automation | Pre-installed via `npm install` |
-| **Applitools Eyes** | Visual testing + MCP | Pre-installed via `npm install` + `APPLITOOLS_API_KEY` |
-| **Allure** | Rich test reports | Pre-installed via `npm install` |
-| **GitHub MCP** | AI creating PRs/issues | `npm install -D @modelcontextprotocol/server-github` + `GITHUB_TOKEN` |
+### @playwright/test
+```bash
+npm install -D @playwright/test
+```
+Moteur de test E2E. **Requis.**
 
-### Install into a project
+### @types/node
+```bash
+npm install -D @types/node
+```
+Types Node.js (`process`, `Buffer`...). **Requis.**
 
+### allure-playwright
 ```bash
-npx @ai-qa/workflow init --yes
+npm install -D allure-playwright
 ```
+Reporter Allure pour Playwright. **Requis pour les rapports.**
 
-Or from local template:
+### allure-commandline
 ```bash
-node install.js ../my-project --yes
+npm install -D allure-commandline
 ```
+Génération du rapport HTML Allure. **Requis pour les rapports.**
 
-### Update
+### @applitools/eyes-playwright
+```bash
+npm install -D @applitools/eyes-playwright
+```
+Tests visuels Applitools Eyes. **Optionnel** (nécessite `APPLITOOLS_API_KEY`).
 
+### @modelcontextprotocol/server-github
 ```bash
-npx @ai-qa/workflow update --yes
+npm install -D @modelcontextprotocol/server-github
 ```
+Intégration GitHub (PRs, issues). **Optionnel** (nécessite `GITHUB_TOKEN`).
 
-> **Note:** The installer creates a `.env` template (`APPLITOOLS_API_KEY=""` and `GITHUB_TOKEN=""`...) only on fresh installs. If the `.env` file was not created (e.g., during an update), create it manually in your project root with those two keys.
+### Installation rapide (tout en une ligne)
+```bash
+npm install -D @playwright/test @types/node allure-playwright allure-commandline @applitools/eyes-playwright
+npx playwright install chromium
+```
 
 ---
 

package/install.js

@@ -14,6 +14,7 @@ const USER_FILES = new Set([
   '.qa-workflow.json',
   'opencode.json',
   'docs/application-context.md',
+  'package.json',
 ]);
 
 // Directories that are pure user data — NEVER touched
@@ -24,7 +25,7 @@ const USER_DIRS = new Set([
   'test-results',
   '.qa-context',
   '.auth',
-  '.env'
+  '.env',
 ]);
 
 // Template files to copy/update
@@ -45,6 +46,10 @@ const QA_ITEMS = [
       { src: 'opencode.json', dest: 'opencode.json' },
     { src: 'playwright.config.ts', dest: 'playwright.config.ts' },
     { src: 'cli.js', dest: 'cli.js' },
+    { src: 'package.json', dest: 'package.json' },
+    { src: 'install.js', dest: 'install.js' },
+    { src: 'tsconfig.json', dest: 'tsconfig.json' },
+
 
     ];
 
@@ -257,12 +262,12 @@ async function main() {
   // 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';
+  if (args.includes('update')) {
+      targetPath = process.cwd();
+      mode = 'update';
+  } else if (IS_SELF || args.includes('init')) {
+      targetPath = process.cwd();
+      mode = 'install';
   } else if (IS_UPDATE) {
     targetPath = path.resolve(nonFlagArgs[0] || process.cwd());
     mode = 'update';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-qa/workflow",
-  "version": "2.0.15",
+  "version": "2.0.17",
   "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",
@@ -61,11 +63,5 @@
     "dashboard:dev": "cd qa-dashboard && npx nodemon app.js",
     "dashboard:stop": "npx kill-port 4000"
   },
-  "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"
-  }
+  "devDependencies": {}
 }

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/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "types": ["node"]
+  }
+}