qaa-agent 1.7.0 → 1.7.1

package/bin/install.cjs

@@ -143,12 +143,22 @@ 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)
+  // Install .mcp.json (Playwright MCP server config) -- both to qaaDir AND global baseDir
   const mcpSrc = path.join(ROOT, '.mcp.json');
   if (fs.existsSync(mcpSrc)) {
-    const mcpDest = path.join(qaaDir, '.mcp.json');
-    copyFile(mcpSrc, mcpDest);
-    ok('Installed Playwright MCP server config (.mcp.json)');
+    // 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 || {};
+    }
+    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)');
   }
 
   // Write version

package/commands/qa-fix.md

@@ -5,12 +5,13 @@ Validate, diagnose, and fix test files — all in one command. Runs 4-layer stat
 ## Usage
 
 ```
-/qa-fix [<test-directory>] [options]
+/qa-fix [<test-files-or-directory>] [options]
 ```
 
 ### Options
 
-- `<test-directory>` — path to test files (auto-detects if omitted)
+- `<test-files-or-directory>` — one or more test file paths or a directory (auto-detects if omitted)
+- `--check` — **final check mode**: full quality verification against company preferences, codebase conventions, and execution
 - `--validate-only` — run 4-layer static validation only, no test execution or classification
 - `--classify` — run tests and classify failures, but do NOT auto-fix
 - `--run --app-url <url>` — also execute E2E tests against live app after static validation
@@ -20,7 +21,9 @@ Validate, diagnose, and fix test files — all in one command. Runs 4-layer stat
 ### Mode Detection
 
 ```
-if --validate-only:
+if --check:
+  MODE = "check"           → full quality check + execution + QA_CHECK_REPORT.md
+elif --validate-only:
   MODE = "validate"        → 4-layer static validation + VALIDATION_REPORT.md
 elif --classify:
   MODE = "classify"        → run tests + classify failures (no auto-fix)
@@ -32,6 +35,8 @@ else:
 
 | Mode | Artifacts |
 |------|-----------|
+| check | QA_CHECK_REPORT.md (full quality verification with pass/fail per test file) |
+| check --ticket | QA_CHECK_REPORT.md + UAT_VERIFICATION.md (step-by-step screenshots vs ticket acceptance criteria) |
 | validate | VALIDATION_REPORT.md (syntax, structure, dependencies, logic per file) |
 | classify | FAILURE_CLASSIFICATION_REPORT.md (per-failure evidence, no fixes) |
 | fix | FAILURE_CLASSIFICATION_REPORT.md + auto-fixed test files |
@@ -57,6 +62,249 @@ App URL: {url or "auto-detect"}
 
 ---
 
+### CHECK MODE (`--check`) — Final Quality Verification
+
+Full quality check for specific test files. Reads ALL context sources, verifies every aspect of the tests, runs them, and produces a pass/fail report. Use this as a final gate before delivering tests.
+
+**Accepts specific files:**
+```
+/qa-fix --check tests/e2e/login.e2e.spec.ts tests/e2e/checkout.e2e.spec.ts
+/qa-fix --check tests/unit/auth.unit.spec.ts
+/qa-fix --check tests/e2e/ --app-url http://localhost:3000
+```
+
+**Step 1: Read ALL context sources**
+
+Read every available context source — this is not optional, all must be read:
+
+1. **CLAUDE.md** — QA standards, POM rules, locator tiers, assertion rules, naming conventions, quality gates
+2. **~/.claude/qaa/MY_PREFERENCES.md** — company/user preferences that OVERRIDE CLAUDE.md rules
+3. **Codebase map** (`.qa-output/codebase/`):
+   - `CODE_PATTERNS.md` — naming conventions, import style, file organization (are tests matching the project's style?)
+   - `API_CONTRACTS.md` — real API shapes (are API test payloads correct?)
+   - `TEST_SURFACE.md` — function signatures (are test targets real?)
+   - `TESTABILITY.md` — mock boundaries (are mocks set up correctly?)
+4. **Locator Registry** (`.qa-output/locators/`) — real locators from the app (are POM locators accurate?)
+5. **Existing test patterns** — read 2-3 existing test files in the same repo to understand current conventions (describe block style, import patterns, assertion patterns, fixture usage)
+
+If codebase map is missing, STOP and tell the user to run `/qa-map` first.
+
+**Step 2: Verify each test file across 7 dimensions**
+
+For EACH selected test file, check:
+
+| # | Dimension | What to check | Source |
+|---|-----------|---------------|--------|
+| 1 | **Naming** | File name, test IDs, describe/it names follow conventions | CLAUDE.md + CODE_PATTERNS.md + MY_PREFERENCES.md |
+| 2 | **Structure** | Correct directory, imports resolve, follows repo patterns | CODE_PATTERNS.md + existing tests in repo |
+| 3 | **Locators** | POM locators match registry, Tier 1 preferred, no stale selectors | LOCATOR_REGISTRY.md |
+| 4 | **Assertions** | Concrete values (no toBeTruthy alone), match API contracts | CLAUDE.md + API_CONTRACTS.md |
+| 5 | **POM compliance** | No assertions in POMs, locators as properties, extends BasePage | CLAUDE.md |
+| 6 | **Code quality** | No redundant code, no dead code, no hardcoded credentials, no copy-paste | Code review |
+| 7 | **Company conventions** | Matches all rules in MY_PREFERENCES.md | MY_PREFERENCES.md |
+
+**Step 3: Run the tests**
+
+Execute the selected test files:
+
+```bash
+# Detect test runner from project config
+npx playwright test {files} --reporter=json 2>&1    # if Playwright
+npx cypress run --spec {files} 2>&1                  # if Cypress
+npx jest {files} --json 2>&1                         # if Jest
+npx vitest run {files} --reporter=json 2>&1          # if Vitest
+```
+
+If E2E tests and app URL available, also verify with Playwright MCP:
+- Navigate to each page referenced in the tests
+- `browser_snapshot()` to verify elements exist in DOM
+- Cross-reference locators against real page
+
+**Step 4: Fix issues found**
+
+For each issue found:
+- **AUTO-FIX** (HIGH confidence): naming, imports, locator mismatches, missing await, Tier 4→Tier 1 upgrade when registry has the value
+- **FLAG for review** (MEDIUM/LOW): logic changes, assertion value changes, structural refactors
+- Re-run tests after fixes (max 5 loops)
+
+**Step 5: Produce QA_CHECK_REPORT.md**
+
+```markdown
+# QA Check Report
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Files checked | {N} |
+| Dimensions checked | 7 |
+| Issues found | {N} |
+| Auto-fixed | {N} |
+| Flagged for review | {N} |
+| Tests passed | {N}/{total} |
+| Overall | PASS / PASS WITH WARNINGS / FAIL |
+
+## Per-File Results
+
+### {file_path}
+
+| Dimension | Status | Details |
+|-----------|--------|---------|
+| Naming | PASS/FAIL | {specific details} |
+| Structure | PASS/FAIL | {specific details} |
+| Locators | PASS/FAIL | {specific details} |
+| Assertions | PASS/FAIL | {specific details} |
+| POM compliance | PASS/FAIL | {specific details} |
+| Code quality | PASS/FAIL | {specific details} |
+| Company conventions | PASS/FAIL | {specific details} |
+
+**Test execution:** PASS / FAIL ({error if failed})
+**Fixes applied:** {list of auto-fixes}
+**Flagged for review:** {list of items needing human review}
+
+[... repeat per file ...]
+
+## Flagged Items (Needs Human Review)
+
+| File | Dimension | Issue | Suggested Fix |
+|------|-----------|-------|---------------|
+| ... | ... | ... | ... |
+```
+
+Write to `.qa-output/QA_CHECK_REPORT.md`.
+
+Present results to user with clear PASS/FAIL per file and overall status.
+
+**Step 6 (optional): Ticket Verification (`--ticket <source>`)**
+
+If `--ticket` flag is provided, perform UAT verification — walk through the test flow step-by-step in the browser, take screenshots at each step, and compare against the ticket's acceptance criteria.
+
+**Usage:**
+```
+/qa-fix --check --ticket #123 tests/e2e/login.e2e.spec.ts --app-url http://localhost:3000
+/qa-fix --check --ticket https://company.atlassian.net/browse/PROJ-456 tests/e2e/checkout.e2e.spec.ts
+/qa-fix --check --ticket "User logs in, sees dashboard with welcome message, clicks profile" tests/e2e/login.e2e.spec.ts
+```
+
+**Requires:** `--app-url` or auto-detected running app. Cannot do ticket verification without a live app.
+
+**Step 6a: Fetch and parse the ticket**
+
+Same ticket parsing as `/qa-create-test` from-ticket mode:
+- GitHub Issue: `gh issue view` → extract title, body, ACs
+- Jira/Linear URL: `WebFetch` → extract content
+- Plain text: use directly as acceptance criteria
+- File path: read file content
+
+Extract:
+- Acceptance criteria (AC-1, AC-2, ...)
+- Expected user flow (step-by-step)
+- Expected outcomes per step
+
+**Step 6b: Walk through the flow with Playwright MCP**
+
+For each E2E test file being checked, replay the user journey manually in the browser step-by-step:
+
+```
+For each step in the ticket's user flow:
+
+  1. Execute the action described in the step:
+     - Navigate: mcp__playwright__browser_navigate({ url: "{page}" })
+     - Fill form: mcp__playwright__browser_fill_form({ ... })
+     - Click: mcp__playwright__browser_click({ element: "..." })
+     - Wait: mcp__playwright__browser_wait_for({ text: "..." })
+
+  2. Take screenshot AFTER the action:
+     mcp__playwright__browser_take_screenshot()
+     → Save to .qa-output/uat-screenshots/{test-name}-step-{N}.png
+
+  3. Take accessibility snapshot to read page state:
+     mcp__playwright__browser_snapshot()
+
+  4. Record what the page shows:
+     - URL after action
+     - Visible text/headings
+     - Form state
+     - Error messages (if any)
+     - Elements visible/hidden
+```
+
+**Step 6c: Compare actual vs ticket**
+
+For each acceptance criterion from the ticket:
+
+| AC | Expected (from ticket) | Actual (from browser) | Screenshot | Verdict |
+|----|----------------------|---------------------|------------|---------|
+| AC-1 | User sees login form | Login form visible with email/password fields | step-1.png | MATCH |
+| AC-2 | After login, redirect to dashboard | Redirected to /dashboard, "Welcome" visible | step-3.png | MATCH |
+| AC-3 | Error message for wrong password | "Invalid credentials" alert shown | step-5.png | MATCH |
+| AC-4 | Remember me keeps session | Session persists after browser close | step-7.png | MISMATCH — session expired |
+
+Verdicts:
+- **MATCH** — actual behavior matches what the ticket describes
+- **MISMATCH** — actual behavior differs from ticket (could be app bug OR test not covering this AC)
+- **NOT TESTED** — ticket has an AC but no test step covers it
+- **EXTRA** — test covers something not in the ticket (informational, not a failure)
+
+**Step 6d: Produce UAT_VERIFICATION.md**
+
+```markdown
+# UAT Verification Report
+
+## Ticket Info
+
+| Field | Value |
+|-------|-------|
+| Source | {ticket URL or text} |
+| Title | {ticket title} |
+| ACs extracted | {count} |
+| Test files verified | {count} |
+
+## Step-by-Step Walkthrough
+
+### Step 1: {action description}
+- **Action:** Navigate to /login
+- **Screenshot:** [step-1.png](.qa-output/uat-screenshots/{test}-step-1.png)
+- **Page state:** Login form visible, email and password fields empty, "Log in" button enabled
+- **Matches AC:** AC-1 ✓
+
+### Step 2: {action description}
+- **Action:** Fill email "test@example.com", password "SecureP@ss123!"
+- **Screenshot:** [step-2.png]
+- **Page state:** Fields filled, button still enabled
+- **Matches AC:** (intermediate step, no AC)
+
+[... repeat per step ...]
+
+## AC Coverage Matrix
+
+| AC | Description | Tested | Verdict | Evidence |
+|----|-------------|--------|---------|----------|
+| AC-1 | Login form visible | Yes | MATCH | step-1.png |
+| AC-2 | Redirect to dashboard | Yes | MATCH | step-3.png |
+| AC-3 | Error on wrong password | Yes | MATCH | step-5.png |
+| AC-4 | Remember me session | No | NOT TESTED | — |
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| ACs from ticket | {N} |
+| ACs matched | {N} |
+| ACs mismatched | {N} |
+| ACs not tested | {N} |
+| Screenshots captured | {N} |
+| Overall | PASS / PARTIAL / FAIL |
+```
+
+Write to `.qa-output/UAT_VERIFICATION.md`.
+
+If any AC is MISMATCH or NOT TESTED, present to user with recommendation:
+- MISMATCH → "AC-4 says X but the app does Y — either the app has a bug or the test needs updating"
+- NOT TESTED → "AC-4 is not covered by any test step — consider adding a test case"
+
+---
+
 ### VALIDATE MODE (`--validate-only`)
 
 1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "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"