@ai-qa/workflow 2.0.0

package/.github/agents/playwright-test-generator.agent.md

@@ -0,0 +1,33 @@
+---
+name: playwright-test-generator
+description: Use this agent when you need to create automated browser tests using Playwright
+tools:
+  - search
+  - edit
+  - playwright/browser_click
+  - playwright/browser_navigate
+  - playwright/browser_type
+  - playwright/browser_snapshot
+  - playwright/generator_setup_page
+  - playwright/generator_read_log
+  - playwright/generator_write_test
+mcp-servers:
+  playwright:
+    type: stdio
+    command: npx
+    args:
+      - -y
+      - @playwright/mcp
+    tools:
+      - "*"
+---
+
+You are a Playwright test generator. Create robust E2E tests from test plans.
+
+For each test:
+1. Read the test plan scenario
+2. Use Playwright to manually execute steps in real-time
+3. Capture selectors and locators from actual page interaction
+4. Generate the test file using `generator_write_test`
+
+Always prefer: data-testid > aria-label > role > text > xpath (last resort)

package/.github/agents/playwright-test-healer.agent.md

@@ -0,0 +1,36 @@
+---
+name: playwright-test-healer
+description: Use this agent when you need to debug and fix failing Playwright tests
+tools:
+  - search
+  - edit
+  - playwright/browser_console_messages
+  - playwright/browser_evaluate
+  - playwright/browser_generate_locator
+  - playwright/browser_network_requests
+  - playwright/browser_snapshot
+  - playwright/test_debug
+  - playwright/test_list
+  - playwright/test_run
+mcp-servers:
+  playwright:
+    type: stdio
+    command: npx
+    args:
+      - -y
+      - @playwright/mcp
+    tools:
+      - "*"
+---
+
+You are the Playwright Test Healer. Debug and fix failing tests systematically.
+
+Protocol (token-efficient):
+1. Run only failing tests with `test_run`
+2. Debug with `test_debug` — examine the error state
+3. Classify the failure:
+   - Selector broken → edit 1-3 lines, re-run once
+   - Timing issue → add 1 wait, re-run once
+   - App bug → mark `test.fixme()`, log defect, move on
+4. Max 1 fix attempt per test. If still failing, it's a defect.
+5. Never rewrite entire files — targeted edits only.

package/.github/agents/playwright-test-planner.agent.md

@@ -0,0 +1,44 @@
+---
+name: playwright-test-planner
+description: Use this agent when you need to create comprehensive test plan for a web application or website
+tools:
+  - search
+  - playwright/browser_click
+  - playwright/browser_close
+  - playwright/browser_console_messages
+  - playwright/browser_drag
+  - playwright/browser_evaluate
+  - playwright/browser_file_upload
+  - playwright/browser_handle_dialog
+  - playwright/browser_hover
+  - playwright/browser_navigate
+  - playwright/browser_navigate_back
+  - playwright/browser_network_requests
+  - playwright/browser_press_key
+  - playwright/browser_run_code
+  - playwright/browser_select_option
+  - playwright/browser_snapshot
+  - playwright/browser_take_screenshot
+  - playwright/browser_type
+  - playwright/browser_wait_for
+  - playwright/planner_setup_page
+  - playwright/planner_save_plan
+mcp-servers:
+  playwright:
+    type: stdio
+    command: npx
+    args:
+      - -y
+      - @playwright/mcp
+    tools:
+      - "*"
+---
+
+You are an expert web test planner. You explore web apps and create detailed test plans.
+
+1. Navigate and explore the application
+2. Map user flows and identify critical paths
+3. Design comprehensive scenarios (happy path, edge cases, error handling)
+4. Save test plan using `planner_save_plan`
+
+Each scenario must include: title, steps, expected outcomes, success criteria.

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

@@ -0,0 +1,365 @@
+# AI QA Pipeline
+
+**User Story → Test Plan → Test Generation → Execution → Self-Healing → Dashboard**
+
+One-command install into any web project. Works standalone or with any AI assistant (opencode, GitHub Copilot, Claude Code).
+
+---
+
+## One-Command Install
+
+```bash
+npx @ai-qa/workflow init --yes
+```
+
+That's it. This single command installs the full pipeline into your current project:
+
+- Copies pipeline scripts (planner, generator, executor, healer, reporter)
+- Installs Playwright + dashboard dependencies
+- Adds npm scripts (`qa:*` commands)
+- Creates directories (`user-story/`, `specs/`, `tests/`, `test-results/`)
+- Registers your project in the dashboard
+
+### Update an existing installation
+
+```bash
+npx @ai-qa/workflow update --yes
+```
+
+Updates pipeline files while **preserving** your configuration (`.qa-workflow.json`, `opencode.json`), user stories, test specs, and run results.
+
+### What you get
+
+```
+your-project/
+├── ai-qa-workflow.js          # CLI orchestrator (10 commands)
+├── .qa-workflow.json          # Project config (auto-detected, editable)
+├── scripts/                   # 6 automation modules
+├── opencode.json              # MCP config (Playwright + GitHub)
+├── .github/agents/            # AI agent definitions
+├── prompts/                   # AI workflow instructions
+├── qa-dashboard/              # Web UI (port 4000)
+├── user-story/                # Your .md stories
+├── specs/                     # Generated test plans
+├── tests/                     # Generated Playwright specs
+└── test-results/              # Run results, reports, screenshots
+```
+
+### Quick start after install
+
+```bash
+# 1. Initialize (auto-detects project config)
+npm run qa:init
+
+# 2. Write a user story in user-story/ or let the AI create one
+
+# 3. Run full pipeline
+npm run qa:run my-story.md
+
+# 4. Start the dashboard
+npm run dashboard
+```
+
+---
+
+## How It Works
+
+The pipeline takes a **user story** (Markdown file) through 5 automated stages:
+
+```
+user-story.md  →  Test Plan  →  Test Spec (.spec.ts)  →  Execute  →  Heal  →  Report
+     │               │                 │                    │          │         │
+  planner.js    generator.js      executor.js          healer.js   reporter.js  └→ docs/
+     │               │                 │                    │          │
+  (AI creates   (AI generates    (Playwright runs     (2 auto-retry     └→ dashboard
+   scenarios)    Playwright       tests, captures      attempts, then
+                 code with        results)             marks as defect)
+                 real selectors)
+```
+
+Each stage can run standalone (`npm run qa:plan`, `qa:generate`, `qa:execute`, `qa:heal`, `qa:report`) or all at once (`npm run qa:run`).
+
+---
+
+## Zero-Config Design
+
+The template works out of the box by **auto-detecting** your project configuration.
+
+On `npm run qa:init`, it scans your project and generates `.qa-workflow.json`:
+
+| Scan source | What it detects |
+|-------------|----------------|
+| `package.json` | Project name, description, dev server port |
+| `README.md` | Project name, URL, description |
+| `docker-compose.yml` | Exposed port, project name |
+| `.env` | `APP_URL`, `APP_ENV` / `NODE_ENV` |
+| `playwright.config.*` | Browser type (edge, webkit) |
+| Directory structure | Framework (Angular, Next.js, Python) |
+
+If a file is missing, the template falls back to sensible defaults. No manual setup required.
+
+### The Config File (`.qa-workflow.json`)
+
+```json
+{
+  "project": {
+    "name": "my-app",
+    "description": "My web application",
+    "url": "http://localhost:5173",
+    "environment": "Development"
+  },
+  "browser": {
+    "type": "chromium",
+    "cdpPort": 9222,
+    "headed": false
+  },
+  "test": {
+    "timeout": 120000,
+    "retries": 0,
+    "workers": 1
+  },
+  "auth": {
+    "user": "",
+    "credentials": {}
+  }
+}
+```
+
+Edit this file to override auto-detected values. The template merges your settings with defaults — you only need to set what differs.
+
+### Application Context (`docs/application-context.md`)
+
+This file serves as a **knowledge base for AI agents** during test planning and healing. On `init` it's created from config values. As you use the pipeline, AI agents populate it with:
+
+- **Stable selectors** — CSS/XPath selectors discovered during exploration
+- **Known flaky areas** — elements or flows that frequently break
+- **Auth details** — users, tokens, environments
+- **Tech stack notes** — framework specifics the AI should know
+
+For best results, edit this file with your project's specifics before running the pipeline.
+
+---
+
+## Installation
+
+### Requirements
+
+| Component | Needed for | Install |
+|-----------|-----------|---------|
+| **Node.js 18+** | Running the pipeline | — |
+| **Playwright** | Test execution | `npm install @playwright/test` |
+| **Chromium** | Running tests | `npx playwright install chromium` |
+| **Playwright MCP** | AI browser automation (explore, click, type) | `npm install -D @playwright/mcp` |
+| **GitHub MCP** | AI creating PRs/issues from results | `npm install -D @modelcontextprotocol/server-github` + `GITHUB_TOKEN` env |
+
+### Install into a project
+
+```bash
+# From npm (recommended — works anywhere)
+npx @ai-qa/workflow init --yes
+
+# From local template
+node install.js ../my-project --yes
+```
+
+The installer copies all pipeline files, creates directories, adds npm scripts, installs dashboard dependencies, and registers your project in the dashboard.
+
+### Update an installed project
+
+```bash
+# From npm
+npx @ai-qa/workflow update --yes
+
+# From local template
+node install.js ../my-project --update --yes
+```
+
+Updates pipeline files while preserving: `.qa-workflow.json`, `opencode.json`, `user-story/`, `specs/`, `tests/`, `test-results/`, `qa-dashboard/data/`, `qa-dashboard/node_modules/`.
+
+### Commands added to your project
+
+```bash
+npm run qa:init          # Initialize + auto-detect config
+npm run qa:run <story>   # Full pipeline: plan → generate → execute → heal → report
+npm run qa:plan <story>  # Generate test plan only
+npm run qa:generate      # Generate test code from plan
+npm run qa:execute       # Run Playwright tests
+npm run qa:heal          # Self-heal failed tests
+npm run qa:report        # Generate final report
+npm run qa:status        # Check pipeline state
+npm run qa:list          # List stories, plans, specs
+npm run dashboard        # Launch web dashboard at :4000
+```
+
+---
+
+## How to Get the Most Out of It
+
+### 1. Provide good context upfront
+
+Before running the pipeline, populate `docs/application-context.md`:
+
+```markdown
+## Project
+- Name: My App
+- URL: https://staging.myapp.com
+- Environment: Staging
+
+## Authentication
+- Login flow: email + password via /api/auth/login
+- Test user: test@example.com / TestPass123
+
+## Stable Selectors
+- Login button: button[data-testid="login-btn"]
+- Error toast: .toast-error
+```
+
+The AI reads this file during test planning and healing. The more accurate this is, the better the generated tests.
+
+### 2. Write structured user stories
+
+Your `user-story/*.md` files should follow this format:
+
+```markdown
+# User Login
+
+**Story ID**: US-001
+**Title**: User Login
+**Feature**: Authentication
+
+## Description
+As a registered user, I want to log in with my credentials so I can access the dashboard.
+
+## Preconditions
+- User exists with email test@example.com
+- Browser is on the login page
+
+## Acceptance Criteria
+1. Enter valid email and password
+2. Click "Sign In"
+3. Redirected to dashboard
+4. User name displayed in header
+```
+
+Well-structured stories produce better test plans. The planner extracts acceptance criteria, preconditions, and feature name automatically.
+
+### 3. Review generated test plans
+
+After `npm run qa:plan`, check `specs/*-test-plan.md`. The AI generates scenarios from acceptance criteria. Review and edit before generating test code:
+
+- Add edge cases the AI missed
+- Add negative test scenarios
+- Fix any incorrect assumptions about the app
+
+### 4. Use the run mode that fits your workflow
+
+| Mode | Command | Best for |
+|------|---------|----------|
+| **Full auto** | `npm run qa:run <story>` | Quick smoke tests, CI pipelines |
+| **Step by step** | plan → generate → execute → heal → report | Reviewing each stage, manual edits |
+| **Manual test only** | `npm run qa:execute <test>` | When tests are already written |
+| **Heal only** | `npm run qa:heal [runId]` | After manual test edits |
+
+### 5. Understand self-healing
+
+The healer makes up to **2 attempts** per failed test:
+
+1. **Standard re-run** — flakes due to timing or network
+2. **Longer timeout (60s)** — slow responses
+3. **Stop** — marks as defect, classifies the failure
+
+Failure classification:
+| Type | Label | Auto-healed? |
+|------|-------|-------------|
+| Selector not found | `selector` | ✅ Usually |
+| Timeout | `timing` | ✅ Usually |
+| Target closed | `environment` | ❌ Bug |
+| Network error | `environment` | ❌ Bug |
+| Test syntax error | `test-syntax` | ❌ Manual fix |
+
+### 6. Check the dashboard
+
+```bash
+npm run dashboard
+# → http://localhost:4000
+```
+
+The dashboard shows multi-project management, execution history with pass/fail/healed stats, analytics charts (pass rate, duration, healing vs defects), and test data generation tools.
+
+---
+
+## Self-Healing Rules
+
+| Attempt | Strategy | If still fails |
+|---------|----------|----------------|
+| 1 | Standard re-run | Classify failure |
+| 2 | Longer timeout (60s) | Mark as defect |
+| STOP | — | `test.fixme()` + classify |
+
+---
+
+## Project Structure
+
+```
+your-project/
+├── ai-qa-workflow.js          # CLI orchestrator (9 commands)
+├── .qa-workflow.json          # Project config (auto-detected, editable)
+├── scripts/
+│   ├── utils.js               # Config loading, auto-detection, shared helpers
+│   ├── planner.js             # user-story → test-plan template
+│   ├── generator.js           # test-plan → test spec skeleton
+│   ├── executor.js            # runs Playwright tests
+│   ├── healer.js              # 2 attempts max, classifies defects
+│   └── reporter.js            # markdown + JSON reports
+├── opencode.json              # MCP config (Playwright + GitHub)
+├── .github/agents/            # AI agent definitions
+├── prompts/                   # AI workflow instructions
+├── qa-dashboard/              # Web UI (port 4000)
+├── user-story/                # Your .md stories
+├── specs/                     # Generated test plans
+├── tests/                     # Generated Playwright specs
+├── test-results/              # Run results, reports, screenshots
+└── docs/                      # Application context (AI knowledge base)
+```
+
+---
+
+## Allure Reports
+
+The pipeline supports **Allure** for rich, interactive test reports.
+
+### Setup
+
+```bash
+# 1. Install Allure dependencies
+npm install -D allure-playwright
+
+# 2. Add to Playwright config (playwright.config.ts or .js)
+# reporter: [["list"], ["allure-playwright"]],
+
+# 3. Run tests (generates allure-results/)
+npm run qa:execute
+
+# 4. Generate the HTML report
+npm run qa:report:allure
+```
+
+### View in Dashboard
+
+Once generated, the Allure report is available from the dashboard:
+
+- **Runs list** → "Allure Report" button on each run
+- **Run detail** → "Open Allure Report ↗" in the Report Actions card
+- Direct URL: `/allure-report?project=<project-id>`
+
+The dashboard auto-detects `allure-report/index.html` and shows the buttons only when the report exists.
+
+---
+
+## Token Efficiency (for AI)
+
+1. Body text assertions over complex selectors
+2. Screenshots off by default (only on failure)
+3. Healer makes 1 fix attempt max per test
+4. Real bugs classified immediately — no retries
+5. AI edits 1-3 lines maximum per fix