qaa-agent 1.7.1 → 1.7.3

package/README.md

@@ -0,0 +1,380 @@
+# QAA - QA Automation Agent
+
+[![npm version](https://img.shields.io/npm/v/qaa-agent.svg)](https://www.npmjs.com/package/qaa-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Multi-agent QA pipeline for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Analyzes any codebase, generates a complete test suite following industry standards, validates everything, and delivers the result as a draft pull request.
+
+```
+scan → map → analyze → plan → generate → validate → deliver
+```
+
+No manual test writing. No guessing what to cover. One command, full pipeline.
+
+---
+
+## The Problem
+
+- **Starting from zero is painful** — a new project with no tests means weeks of setup
+- **Coverage gaps are invisible** — without analysis, teams don't know what's missing until production breaks
+- **Standards drift** — different team members write tests differently: inconsistent locators, vague assertions, mixed naming
+- **QA is always behind dev** — features ship faster than tests get written
+
+## The Solution
+
+QAA runs a pipeline of 12 specialized AI agents, each responsible for one stage:
+
+| Stage | What happens | Output |
+|-------|-------------|--------|
+| **Scan** | Detects framework, language, testable surfaces | `SCAN_MANIFEST.md` |
+| **Map** | Deep-scans codebase with 4 parallel agents (testability, risk, patterns, existing tests) | 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, opens draft PR | Pull request URL |
+
+---
+
+## Install
+
+```bash
+npx qaa-agent
+```
+
+The interactive installer:
+
+1. Copies agents, commands, skills, templates, and workflows into your runtime directory
+2. Configures the [Playwright MCP](https://github.com/anthropics/mcp-playwright) server in your user-scope config (`~/.claude.json`) so it's available in **all projects**
+3. Merges required permissions into `settings.json`
+
+**Supported runtimes:** Claude Code, OpenCode
+
+**Install scope:** Global (`~/.claude/`, available in all projects) or Local (`./.claude/`, this project only)
+
+### Requirements
+
+- [Node.js](https://nodejs.org/) 18+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
+
+### Playwright MCP (required for E2E)
+
+QAA uses [`@playwright/mcp`](https://www.npmjs.com/package/@playwright/mcp) to open a real browser, extract locators from live pages, run E2E tests, and auto-fix locator mismatches.
+
+**You need to install the Playwright MCP server manually in your environment:**
+
+<details>
+<summary><strong>VS Code (Claude Code extension)</strong></summary>
+
+1. Open VS Code Settings (`Ctrl+Shift+P` > `Preferences: Open User Settings (JSON)`)
+2. Add the MCP server config:
+
+```json
+{
+  "claude-code.mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+Or add it to your project's `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Code CLI</strong></summary>
+
+Add to `~/.claude.json` (user-scope, all projects):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+Or add a `.mcp.json` file in your project root for project-scope only.
+
+</details>
+
+Once configured, Playwright MCP enables QAA to:
+- Open a real browser and navigate your running app
+- Extract actual locators (`data-testid`, ARIA roles, labels) from live pages
+- Run E2E tests, capture failures, and auto-fix locator mismatches
+- Build a persistent **Locator Registry** (`.qa-output/locators/`) that caches real locators across features
+
+---
+
+## Quick Start
+
+### New project, no tests
+
+```
+/qa-start --dev-repo ./myproject --auto
+```
+
+Runs the full pipeline end-to-end: scan, map, analyze, plan, generate, validate, and deliver as a draft PR.
+
+### Mature project, new feature
+
+```
+/qa-map                                          # build the "brain" (once)
+/qa-create-test "password reset"                 # generate tests using codebase knowledge
+/qa-pr --ticket PROJ-123 "password reset tests"  # ship as draft PR
+```
+
+### From a Jira ticket
+
+```
+/qa-from-ticket https://company.atlassian.net/browse/PROJ-456
+/qa-pr --ticket PROJ-456 "login flow tests"
+```
+
+### Fix broken tests after a deploy
+
+```
+/qa-fix ./tests/e2e/checkout*
+/qa-pr --ticket PROJ-789 "fix checkout tests"
+```
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/qa-start` | Full pipeline end-to-end (scan through PR) |
+| `/qa-map` | Deep codebase analysis with 4 parallel agents |
+| `/qa-create-test <feature>` | Generate tests for a specific feature |
+| `/qa-fix [path]` | Diagnose and fix broken tests |
+| `/qa-audit [path]` | 6-dimension quality audit with scoring |
+| `/qa-pr` | Create a draft pull request from QA artifacts |
+| `/qa-testid [path]` | Inject `data-testid` attributes into components |
+
+### Additional Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/qa-from-ticket <url>` | Generate tests from a Jira/Linear/GitHub Issue |
+| `/qa-analyze` | Analyze a repo without generating tests |
+| `/qa-validate [path]` | Validate test files against standards |
+| `/qa-gap` | Find coverage gaps between dev and QA repos |
+| `/qa-report` | Generate a QA status report |
+| `/qa-audit` | Full quality audit with weighted scoring |
+| `/qa-blueprint` | Generate QA repo structure from scratch |
+| `/qa-research` | Research best testing stack for a project |
+| `/qa-pom` | Generate Page Object Models |
+| `/update-test` | Improve existing tests incrementally |
+
+See [COMMANDS.md](docs/COMMANDS.md) for full usage details and flags.
+
+---
+
+## Three Workflows
+
+QAA adapts to the project's QA maturity:
+
+**Option 1: No QA repo yet** — Full pipeline from scratch. Produces a complete test suite, repo blueprint, and draft PR.
+
+```
+/qa-start --dev-repo ./myproject
+```
+
+**Option 2: Immature QA repo** — Scans both repos, fixes broken tests, fills coverage gaps, standardizes existing tests.
+
+```
+/qa-start --dev-repo ./myproject --qa-repo ./tests
+```
+
+**Option 3: Mature QA repo** — Surgical additions only. Finds thin coverage areas and adds targeted tests without touching working code.
+
+```
+/qa-start --dev-repo ./myproject --qa-repo ./tests
+```
+
+---
+
+## The "Brain" — Codebase Map
+
+Before generating anything, QAA maps the codebase with 4 parallel agents producing 8 documents:
+
+| Focus | Documents |
+|-------|-----------|
+| **Testability** | `TESTABILITY.md`, `TEST_SURFACE.md` — what's testable, entry points, mock boundaries |
+| **Risk** | `RISK_MAP.md`, `CRITICAL_PATHS.md` — business-critical paths, security-sensitive areas |
+| **Patterns** | `CODE_PATTERNS.md`, `API_CONTRACTS.md` — naming conventions, API shapes, import style |
+| **Existing tests** | `TEST_ASSESSMENT.md`, `COVERAGE_GAPS.md` — current quality, frameworks, gaps |
+
+Every downstream agent reads these documents. The result: generated tests feel native to the codebase, not generic boilerplate.
+
+---
+
+## Standards Enforced
+
+Every generated artifact follows strict rules defined in [CLAUDE.md](CLAUDE.md):
+
+### Testing Pyramid
+
+```
+         /  E2E  \        3-5%   (critical path smoke only)
+        /  API    \       20-25% (endpoints + contracts)
+       / Integration\     10-15% (component interactions)
+      /    Unit      \    60-70% (business logic, pure functions)
+```
+
+### Locator Hierarchy
+
+1. **Tier 1 (Best):** `data-testid`, ARIA roles with accessible names
+2. **Tier 2 (Good):** Form labels, placeholders, visible text
+3. **Tier 3 (Acceptable):** Alt text, title attributes
+4. **Tier 4 (Last Resort):** CSS selectors, XPath — always with a `// TODO` comment
+
+### Page Object Model
+
+- One class per page, no god objects
+- No assertions in POMs — assertions belong in test specs
+- Locators as readonly properties
+- Every POM extends a shared `BasePage`
+
+### Assertion Quality
+
+```typescript
+// Good — concrete values
+expect(response.status).toBe(200);
+expect(data.name).toBe('Test User');
+
+// Bad — never do this
+expect(response.status).toBeTruthy();
+expect(data).toBeDefined();
+```
+
+### Test Case IDs
+
+Every test case has a unique ID following the pattern:
+- `UT-MODULE-001` — unit tests
+- `INT-MODULE-001` — integration tests
+- `API-RESOURCE-001` — API tests
+- `E2E-FLOW-001` — E2E tests
+
+---
+
+## Validation
+
+Generated tests pass through a 4-layer validation with auto-fix (up to 3 loops):
+
+1. **Syntax** — does it parse? Are imports correct?
+2. **Structure** — POM rules, file organization, naming conventions
+3. **Dependencies** — all imports resolve, mocks set up correctly
+4. **Logic** — assertions are concrete, locators follow tier hierarchy
+
+If issues remain, the **Bug Detective** classifies each failure:
+
+| Classification | Action |
+|----------------|--------|
+| `APPLICATION BUG` | Flagged for developer — not auto-fixed |
+| `TEST CODE ERROR` | Auto-fixed at HIGH confidence |
+| `ENVIRONMENT ISSUE` | Documented with setup instructions |
+| `INCONCLUSIVE` | Flagged with evidence for manual review |
+
+---
+
+## Framework Support
+
+QAA auto-detects the project's existing stack and matches it:
+
+**Languages:** JavaScript/TypeScript, Python, Java, .NET/C#, Go, Ruby, PHP, Rust
+
+**Test Frameworks:** Playwright, Cypress, Jest, Vitest, pytest, Selenium, and more
+
+**Build Tools:** Vite, Next.js, Nuxt, Angular, Vue, Webpack, SvelteKit
+
+**Git Platforms:** GitHub, Azure DevOps, GitLab
+
+---
+
+## 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 to `MY_PREFERENCES.md`. Every agent reads your preferences before generating output.
+
+Your team's conventions always win over defaults.
+
+---
+
+## Architecture
+
+```
+qaa-agent/
+  agents/          # 12 specialized QA agents
+  commands/        # 7 slash commands (user-facing entry points)
+  skills/          # 6 reusable skills
+  templates/       # 10 artifact templates (output format contracts)
+  workflows/       # 7 workflow orchestration specs
+  bin/             # Installer and CLI tools
+  docs/            # User documentation
+  CLAUDE.md        # QA standards (read by every agent)
+  .mcp.json        # Playwright MCP server config
+  settings.json    # Claude Code permissions
+```
+
+### Agents
+
+| Agent | Responsibility |
+|-------|---------------|
+| `qa-scanner` | Framework detection, file tree scanning |
+| `qa-codebase-mapper` | 4-parallel-agent deep analysis |
+| `qa-analyzer` | Risk assessment, test inventory, pyramid |
+| `qa-planner` | Test case grouping, file assignment |
+| `qa-executor` | Test file, POM, fixture generation |
+| `qa-validator` | 4-layer validation with auto-fix |
+| `qa-e2e-runner` | Browser-based test execution via Playwright MCP |
+| `qa-bug-detective` | Failure classification with evidence |
+| `qa-testid-injector` | `data-testid` attribute injection |
+| `qa-project-researcher` | Testing stack research |
+| `qa-discovery` | Project discovery |
+| `qa-pipeline-orchestrator` | Pipeline coordination |
+
+---
+
+## Git Workflow
+
+QAA follows strict git conventions:
+
+- **Branch:** `qa/auto-{project}-{date}` (e.g., `qa/auto-shopflow-2026-03-18`)
+- **Commits:** One per agent stage — `qa(scanner): produce SCAN_MANIFEST.md for shopflow`
+- **PR:** Draft PR with analysis summary, test counts, coverage metrics, validation status
+
+---
+
+## Documentation
+
+- [Commands Reference](docs/COMMANDS.md) — all commands with flags and examples
+- [Demo & Walkthrough](docs/DEMO.md) — problem/solution explanation with real workflows
+- [Changelog](CHANGELOG.md) — version history
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+Built by [Capmation](https://github.com/capmation)

package/bin/install.cjs

@@ -143,22 +143,24 @@ async function main() {
   copyFile(path.join(ROOT, 'CLAUDE.md'), path.join(qaaDir, 'CLAUDE.md'));
   ok('Installed QA standards (CLAUDE.md)');
 
-  // Install .mcp.json (Playwright MCP server config) -- both to qaaDir AND global baseDir
+  // Install .mcp.json (Playwright MCP server config)
   const mcpSrc = path.join(ROOT, '.mcp.json');
   if (fs.existsSync(mcpSrc)) {
     // Copy to qaa dir for reference
     copyFile(mcpSrc, path.join(qaaDir, '.mcp.json'));
-    // Merge into global ~/.claude/.mcp.json so Playwright MCP is available in ALL projects
-    const globalMcpPath = path.join(baseDir, '.mcp.json');
-    let globalMcp = { mcpServers: {} };
-    if (fs.existsSync(globalMcpPath)) {
-      try { globalMcp = JSON.parse(fs.readFileSync(globalMcpPath, 'utf8')); } catch {}
-      globalMcp.mcpServers = globalMcp.mcpServers || {};
+
+    // Merge MCP servers into ~/.claude.json (user-scope) so they're available in ALL projects
+    // Note: ~/.claude/.mcp.json is project-scope for ~/.claude/ only — NOT global
+    const userConfigPath = path.join(HOME, '.claude.json');
+    let userConfig = {};
+    if (fs.existsSync(userConfigPath)) {
+      try { userConfig = JSON.parse(fs.readFileSync(userConfigPath, 'utf8')); } catch {}
     }
+    userConfig.mcpServers = userConfig.mcpServers || {};
     const qaaMcp = JSON.parse(fs.readFileSync(mcpSrc, 'utf8'));
-    Object.assign(globalMcp.mcpServers, qaaMcp.mcpServers);
-    fs.writeFileSync(globalMcpPath, JSON.stringify(globalMcp, null, 2));
-    ok('Installed Playwright MCP server config (global — available in all projects)');
+    Object.assign(userConfig.mcpServers, qaaMcp.mcpServers);
+    fs.writeFileSync(userConfigPath, JSON.stringify(userConfig, null, 2));
+    ok('Installed Playwright MCP server config (user-scope — available in all projects)');
   }
 
   // Write version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "QA Automation Agent for Claude Code — multi-agent pipeline that analyzes repos, generates tests, validates, and creates PRs",
   "bin": {
     "qaa-agent": "./bin/install.cjs"