qaa-agent 1.6.2 → 1.6.3

package/docs/DEMO.md

@@ -1,182 +1,182 @@
-# QAA — QA Automation Agent
-
-## What is it?
-
-QAA is a multi-agent system that automates QA test creation for any software project. You point it at a codebase, and it analyzes the architecture, maps the code, generates a full test suite following industry standards, validates everything, and delivers the result as a draft pull request — ready for review.
-
-No manual test writing. No guessing what to cover. One command, full pipeline.
-
-## The Problem
-
-Writing test suites is slow, repetitive, and often inconsistent. Teams face:
-
-- **Starting from zero is painful** — a new project with no tests means weeks of setup before the first real test runs
-- **Coverage gaps are invisible** — without analysis, teams don't know what's missing until something breaks in production
-- **Standards drift** — different team members write tests differently: inconsistent locators, vague assertions, mixed naming conventions
-- **QA is always behind dev** — features ship faster than tests get written, and the gap keeps growing
-- **Existing QA teams still spend hours on repetitive work** — even with a mature test suite, adding tests for new features means manually inspecting pages, finding locators, writing POMs, running tests, fixing failures, repeat
-
-## The Solution
-
-QAA runs a pipeline of specialized AI agents, each responsible for one stage:
-
-```
-scan → map → analyze → plan → generate → validate → deliver
-```
-
-| Stage | What happens | Output |
-|-------|-------------|--------|
-| **Scan** | Detects framework, language, testable surfaces | SCAN_MANIFEST.md |
-| **Map** | Deep-scans codebase for testability, risk, patterns, existing tests (4 parallel agents) | 8 codebase documents |
-| **Analyze** | Produces risk assessment, test inventory, testing pyramid | QA_ANALYSIS.md, TEST_INVENTORY.md |
-| **Plan** | Groups test cases by feature, assigns to files, resolves dependencies | GENERATION_PLAN.md |
-| **Generate** | Writes test files, POMs, fixtures, configs following project standards | Test suite on disk |
-| **Validate** | 4-layer validation (syntax, structure, dependencies, logic) with auto-fix | VALIDATION_REPORT.md |
-| **Deliver** | Creates branch, commits per stage, pushes, opens draft PR | Pull request URL |
-
-Every agent reads the project's QA standards (CLAUDE.md) before producing output. Every test case has a unique ID, concrete inputs, and explicit expected outcomes — never "works correctly."
-
-## Three Workflows
-
-QAA adapts to where the project is in its QA maturity:
-
-**1. No QA repo yet** — `/qa-start --dev-repo ./myproject`
-Full pipeline from scratch. Produces a complete test suite, QA repo blueprint, and a draft PR with everything.
-
-**2. Immature QA repo** — `/qa-start --dev-repo ./myproject --qa-repo ./tests`
-Scans both repos, identifies gaps, fixes broken tests, adds missing coverage, standardizes existing tests.
-
-**3. Mature QA repo** — `/qa-start --dev-repo ./myproject --qa-repo ./tests`
-Only adds surgical test additions where coverage is thin. Doesn't touch working tests.
-
-## The "Brain" — Codebase Map
-
-Before generating anything, QAA maps the entire codebase with 4 parallel agents:
-
-- **Testability** — what's testable, pure functions vs stateful code, mock boundaries
-- **Risk** — business-critical paths, security-sensitive areas, data integrity risks
-- **Patterns** — naming conventions, API shapes, import style, code patterns
-- **Existing tests** — current test quality, frameworks in use, coverage gaps
-
-These 8 documents become the shared context that every downstream agent reads. The analyzer uses risk data to prioritize tests. The planner uses testability data to estimate complexity. The executor uses code patterns to generate tests that match the project's style.
-
-Result: generated tests feel native to the codebase, not generic boilerplate.
-
-## Day-to-Day for a QA Engineer
-
-This is where QAA shines for teams that already have a mature QA repo. The full pipeline is for bootstrapping — but the real daily value is the targeted workflow.
-
-### The scenario
-
-You're a QA engineer. A developer just shipped a new "password reset" feature. You need tests. Here's what happens:
-
-### Step 1: Map the codebase (once)
-
-```
-/qa-map
-```
-
-QAA scans the entire project and builds its "brain" — 8 documents covering testability, risk areas, API contracts, code patterns, and existing test coverage. This runs once and stays valid until the codebase changes significantly.
-
-### Step 2: Create tests for the feature
-
-```
-/create-test "password reset"
-```
-
-QAA already knows the codebase. It reads the brain documents, finds the relevant source files (`auth.service.ts`, `reset.controller.ts`, the reset page component), understands the API contracts, and generates:
-
-- Unit tests for the reset token logic with concrete inputs and expected outputs
-- API tests for `POST /api/auth/reset-password` with real request/response shapes
-- E2E tests with Page Object Models that use the project's existing POM base class
-- Fixtures with test data (fake emails, expired tokens, invalid tokens)
-
-All following the project's naming conventions, import style, and assertion patterns.
-
-### Step 3: Validate and fix in a loop
-
-```
-/qa-validate ./tests
-```
-
-The validator runs 4 layers of checks on every generated file:
-
-1. **Syntax** — does it parse? Are imports correct?
-2. **Structure** — does it follow POM rules? Are locators in the right tier?
-3. **Dependencies** — do all imports resolve? Are mocks set up correctly?
-4. **Logic** — are assertions concrete? Do test IDs follow the convention?
-
-If issues are found, the validator auto-fixes them and re-checks — up to 3 loops. If something still fails, the bug detective classifies it: is it an application bug, a test code error, or an environment issue?
-
-### Step 4: Run the tests with Playwright
-
-QAA integrates with Playwright to actually execute the generated E2E tests against a running application. It opens the browser, navigates pages, fills forms, clicks buttons, and captures what happens. If a test fails, it reads the error, inspects the page state, and determines whether the locator is wrong, the page changed, or there's a real bug.
-
-The loop looks like this:
-
-```
-generate → validate → run → failures? → classify → fix test code → run again → pass
-```
-
-This continues until the tests pass or the issue is classified as an application bug that needs a developer fix.
-
-### Step 5: Ship it
-
-```
-/qa-pr --ticket PROJ-456 "password reset tests"
-```
-
-QAA creates a branch following your team's naming convention (it asked you once and remembers forever), commits the test files, pushes, and opens a draft PR on GitHub, Azure DevOps, or GitLab — whatever your team uses. You get the link.
-
-### The full daily flow
-
-```
-/qa-map                                          → builds the "brain" (once)
-/create-test "password reset"                    → generates tests using codebase knowledge
-/qa-validate ./tests/unit/auth*                  → validates + auto-fixes
-/qa-pr --ticket PROJ-456 "password reset tests"  → draft PR with link
-```
-
-From ticket to PR in minutes, not hours. And the tests follow the same standards as every other test in the repo because QAA read the existing patterns first.
-
-### What about tickets?
-
-If you work from Jira, Linear, or GitHub Issues, skip the manual description:
-
-```
-/qa-from-ticket https://company.atlassian.net/browse/PROJ-456
-```
-
-QAA fetches the ticket, extracts acceptance criteria and edge cases, maps each criterion to test cases with a traceability matrix, generates the tests, validates them, and gives you a report showing which AC is covered by which test.
-
-### When tests break after a deploy
-
-```
-/qa-fix ./tests/e2e/checkout*
-```
-
-QAA reads the failing tests, runs them, classifies each failure (app bug vs test code error vs environment issue), and auto-fixes the test code errors. Application bugs get flagged for the dev team with evidence — the exact assertion that failed, what was expected, and what was received.
-
-## Standards
-
-Every test artifact follows strict rules:
-
-- **Testing pyramid** — 60-70% unit, 10-15% integration, 20-25% API, 3-5% E2E
-- **Locator hierarchy** — data-testid first, ARIA roles, labels, CSS as last resort (with TODO)
-- **Page Object Model** — one class per page, no assertions in POMs, locators as properties
-- **Assertions** — concrete values only. `expect(status).toBe(200)` not `expect(status).toBeTruthy()`
-- **Naming** — unique IDs per test case: `UT-AUTH-001`, `API-USERS-003`, `E2E-CHECKOUT-001`
-
-## Learning System
-
-QAA remembers your preferences across sessions. When you correct it — "use Playwright, not Cypress" or "our branches start with feature/" — it saves the rule permanently. Next time, every agent reads your preferences before generating output.
-
-Preferences override defaults. Your team's conventions always win.
-
-## Numbers
-
-17 commands. 7 skills. 11 agents. 10 templates. 7 workflows.
-
-Supports GitHub, Azure DevOps, and GitLab. Works with Playwright, Cypress, Jest, Vitest, pytest, and more — detects what the project uses and matches it.
-
-One goal: you focus on building features, QAA handles the tests.
+# QAA — QA Automation Agent
+
+## What is it?
+
+QAA is a multi-agent system that automates QA test creation for any software project. You point it at a codebase, and it analyzes the architecture, maps the code, generates a full test suite following industry standards, validates everything, and delivers the result as a draft pull request — ready for review.
+
+No manual test writing. No guessing what to cover. One command, full pipeline.
+
+## The Problem
+
+Writing test suites is slow, repetitive, and often inconsistent. Teams face:
+
+- **Starting from zero is painful** — a new project with no tests means weeks of setup before the first real test runs
+- **Coverage gaps are invisible** — without analysis, teams don't know what's missing until something breaks in production
+- **Standards drift** — different team members write tests differently: inconsistent locators, vague assertions, mixed naming conventions
+- **QA is always behind dev** — features ship faster than tests get written, and the gap keeps growing
+- **Existing QA teams still spend hours on repetitive work** — even with a mature test suite, adding tests for new features means manually inspecting pages, finding locators, writing POMs, running tests, fixing failures, repeat
+
+## The Solution
+
+QAA runs a pipeline of specialized AI agents, each responsible for one stage:
+
+```
+scan → map → analyze → plan → generate → validate → deliver
+```
+
+| Stage | What happens | Output |
+|-------|-------------|--------|
+| **Scan** | Detects framework, language, testable surfaces | SCAN_MANIFEST.md |
+| **Map** | Deep-scans codebase for testability, risk, patterns, existing tests (4 parallel agents) | 8 codebase documents |
+| **Analyze** | Produces risk assessment, test inventory, testing pyramid | QA_ANALYSIS.md, TEST_INVENTORY.md |
+| **Plan** | Groups test cases by feature, assigns to files, resolves dependencies | GENERATION_PLAN.md |
+| **Generate** | Writes test files, POMs, fixtures, configs following project standards | Test suite on disk |
+| **Validate** | 4-layer validation (syntax, structure, dependencies, logic) with auto-fix | VALIDATION_REPORT.md |
+| **Deliver** | Creates branch, commits per stage, pushes, opens draft PR | Pull request URL |
+
+Every agent reads the project's QA standards (CLAUDE.md) before producing output. Every test case has a unique ID, concrete inputs, and explicit expected outcomes — never "works correctly."
+
+## Three Workflows
+
+QAA adapts to where the project is in its QA maturity:
+
+**1. No QA repo yet** — `/qa-start --dev-repo ./myproject`
+Full pipeline from scratch. Produces a complete test suite, QA repo blueprint, and a draft PR with everything.
+
+**2. Immature QA repo** — `/qa-start --dev-repo ./myproject --qa-repo ./tests`
+Scans both repos, identifies gaps, fixes broken tests, adds missing coverage, standardizes existing tests.
+
+**3. Mature QA repo** — `/qa-start --dev-repo ./myproject --qa-repo ./tests`
+Only adds surgical test additions where coverage is thin. Doesn't touch working tests.
+
+## The "Brain" — Codebase Map
+
+Before generating anything, QAA maps the entire codebase with 4 parallel agents:
+
+- **Testability** — what's testable, pure functions vs stateful code, mock boundaries
+- **Risk** — business-critical paths, security-sensitive areas, data integrity risks
+- **Patterns** — naming conventions, API shapes, import style, code patterns
+- **Existing tests** — current test quality, frameworks in use, coverage gaps
+
+These 8 documents become the shared context that every downstream agent reads. The analyzer uses risk data to prioritize tests. The planner uses testability data to estimate complexity. The executor uses code patterns to generate tests that match the project's style.
+
+Result: generated tests feel native to the codebase, not generic boilerplate.
+
+## Day-to-Day for a QA Engineer
+
+This is where QAA shines for teams that already have a mature QA repo. The full pipeline is for bootstrapping — but the real daily value is the targeted workflow.
+
+### The scenario
+
+You're a QA engineer. A developer just shipped a new "password reset" feature. You need tests. Here's what happens:
+
+### Step 1: Map the codebase (once)
+
+```
+/qa-map
+```
+
+QAA scans the entire project and builds its "brain" — 8 documents covering testability, risk areas, API contracts, code patterns, and existing test coverage. This runs once and stays valid until the codebase changes significantly.
+
+### Step 2: Create tests for the feature
+
+```
+/create-test "password reset"
+```
+
+QAA already knows the codebase. It reads the brain documents, finds the relevant source files (`auth.service.ts`, `reset.controller.ts`, the reset page component), understands the API contracts, and generates:
+
+- Unit tests for the reset token logic with concrete inputs and expected outputs
+- API tests for `POST /api/auth/reset-password` with real request/response shapes
+- E2E tests with Page Object Models that use the project's existing POM base class
+- Fixtures with test data (fake emails, expired tokens, invalid tokens)
+
+All following the project's naming conventions, import style, and assertion patterns.
+
+### Step 3: Validate and fix in a loop
+
+```
+/qa-validate ./tests
+```
+
+The validator runs 4 layers of checks on every generated file:
+
+1. **Syntax** — does it parse? Are imports correct?
+2. **Structure** — does it follow POM rules? Are locators in the right tier?
+3. **Dependencies** — do all imports resolve? Are mocks set up correctly?
+4. **Logic** — are assertions concrete? Do test IDs follow the convention?
+
+If issues are found, the validator auto-fixes them and re-checks — up to 3 loops. If something still fails, the bug detective classifies it: is it an application bug, a test code error, or an environment issue?
+
+### Step 4: Run the tests with Playwright
+
+QAA integrates with Playwright to actually execute the generated E2E tests against a running application. It opens the browser, navigates pages, fills forms, clicks buttons, and captures what happens. If a test fails, it reads the error, inspects the page state, and determines whether the locator is wrong, the page changed, or there's a real bug.
+
+The loop looks like this:
+
+```
+generate → validate → run → failures? → classify → fix test code → run again → pass
+```
+
+This continues until the tests pass or the issue is classified as an application bug that needs a developer fix.
+
+### Step 5: Ship it
+
+```
+/qa-pr --ticket PROJ-456 "password reset tests"
+```
+
+QAA creates a branch following your team's naming convention (it asked you once and remembers forever), commits the test files, pushes, and opens a draft PR on GitHub, Azure DevOps, or GitLab — whatever your team uses. You get the link.
+
+### The full daily flow
+
+```
+/qa-map                                          → builds the "brain" (once)
+/create-test "password reset"                    → generates tests using codebase knowledge
+/qa-validate ./tests/unit/auth*                  → validates + auto-fixes
+/qa-pr --ticket PROJ-456 "password reset tests"  → draft PR with link
+```
+
+From ticket to PR in minutes, not hours. And the tests follow the same standards as every other test in the repo because QAA read the existing patterns first.
+
+### What about tickets?
+
+If you work from Jira, Linear, or GitHub Issues, skip the manual description:
+
+```
+/qa-from-ticket https://company.atlassian.net/browse/PROJ-456
+```
+
+QAA fetches the ticket, extracts acceptance criteria and edge cases, maps each criterion to test cases with a traceability matrix, generates the tests, validates them, and gives you a report showing which AC is covered by which test.
+
+### When tests break after a deploy
+
+```
+/qa-fix ./tests/e2e/checkout*
+```
+
+QAA reads the failing tests, runs them, classifies each failure (app bug vs test code error vs environment issue), and auto-fixes the test code errors. Application bugs get flagged for the dev team with evidence — the exact assertion that failed, what was expected, and what was received.
+
+## Standards
+
+Every test artifact follows strict rules:
+
+- **Testing pyramid** — 60-70% unit, 10-15% integration, 20-25% API, 3-5% E2E
+- **Locator hierarchy** — data-testid first, ARIA roles, labels, CSS as last resort (with TODO)
+- **Page Object Model** — one class per page, no assertions in POMs, locators as properties
+- **Assertions** — concrete values only. `expect(status).toBe(200)` not `expect(status).toBeTruthy()`
+- **Naming** — unique IDs per test case: `UT-AUTH-001`, `API-USERS-003`, `E2E-CHECKOUT-001`
+
+## Learning System
+
+QAA remembers your preferences across sessions. When you correct it — "use Playwright, not Cypress" or "our branches start with feature/" — it saves the rule permanently. Next time, every agent reads your preferences before generating output.
+
+Preferences override defaults. Your team's conventions always win.
+
+## Numbers
+
+17 commands. 7 skills. 11 agents. 10 templates. 7 workflows.
+
+Supports GitHub, Azure DevOps, and GitLab. Works with Playwright, Cypress, Jest, Vitest, pytest, and more — detects what the project uses and matches it.
+
+One goal: you focus on building features, QAA handles the tests.