qaa-agent 1.6.3 → 1.7.0

package/{.claude/skills → skills}/qa-testid-injector/SKILL.md

@@ -1,93 +1,93 @@
----
-name: qa-testid-injector
-description: QA Test ID Injector. Scans source code to find interactive UI elements missing data-testid attributes and injects them following naming convention. Use when user wants to add test IDs, improve testability, audit missing test hooks, prepare for E2E automation, or add data-testid attributes before writing Playwright/Cypress tests. Triggers on "add test IDs", "add data-testid", "test hooks", "missing testid", "testability audit", "prepare for automation", "inject test attributes", "make components testable".
----
-
-# QA Test ID Injector
-
-## Purpose
-
-Scan application source code, identify interactive UI elements lacking stable test selectors, and inject `data-testid` attributes following a consistent naming convention. Runs as **Step 0** — before any test generation.
-
-## Core Rule
-
-**Every interactive element MUST have a stable, unique `data-testid` before E2E tests are generated against it.**
-
-## Naming Convention
-
-Pattern: `{context}-{description}-{element-type}` in kebab-case.
-
-### Element Type Suffixes
-
-| Element | Suffix | Example |
-|---------|--------|---------|
-| button | -btn | login-submit-btn |
-| input | -input | login-email-input |
-| select | -select | settings-language-select |
-| textarea | -textarea | feedback-comment-textarea |
-| link | -link | navbar-profile-link |
-| form | -form | checkout-payment-form |
-| img | -img | product-hero-img |
-| table | -table | users-list-table |
-| row | -row | users-item-row |
-| modal | -modal | confirm-delete-modal |
-| container | -container | dashboard-stats-container |
-| list | -list | notifications-list |
-| item | -item | notifications-item |
-| dropdown | -dropdown | navbar-user-dropdown |
-| tab | -tab | settings-security-tab |
-| checkbox | -checkbox | terms-accept-checkbox |
-| radio | -radio | shipping-express-radio |
-| toggle | -toggle | notifications-enabled-toggle |
-| badge | -badge | cart-count-badge |
-| alert | -alert | error-validation-alert |
-
-### Context Derivation
-
-1. **Page-level**: From component filename or route (LoginPage.tsx -> login)
-2. **Component-level**: From component name (<NavBar> -> navbar)
-3. **Nested**: Parent -> child hierarchy, max 3 levels deep
-4. **Dynamic lists**: Use template literals with unique keys
-
-## Execution Phases
-
-### Phase 1: SCAN
-- Detect framework (React/Vue/Angular/HTML) from package.json and file extensions
-- List all component files (exclude test/spec/stories)
-- Prioritize by interaction density (forms > pages > layouts)
-- Output: SCAN_MANIFEST.md
-
-### Phase 2: AUDIT
-- For each file, identify interactive elements
-- Classify: P0 (must have), P1 (should have), P2 (nice to have)
-- Record existing data-testid as EXISTING (don't modify)
-- Record missing as MISSING with proposed value
-- Output: TESTID_AUDIT_REPORT.md
-
-### Phase 3: INJECT
-- Add data-testid as LAST attribute before closing >
-- Preserve all existing formatting
-- Only add the attribute — change nothing else
-- Framework-specific handling (JSX, Vue, Angular, HTML)
-- Output: INJECTION_CHANGELOG.md + modified source files
-
-### Phase 4: VALIDATE
-- Syntax check all modified files
-- Uniqueness check (no duplicate testids per page)
-- Convention compliance check
-- Output: INJECTION_VALIDATION.md
-
-## Third-Party Components
-
-1. Props passthrough (if library supports it) — direct data-testid
-2. Wrapper div (if no passthrough) — wrap with data-testid div
-3. inputProps/slotProps (MUI-specific) — use component-specific prop APIs
-
-## Quality Gate
-
-- [ ] Every interactive element has a data-testid
-- [ ] All values follow {context}-{description}-{element-type} convention
-- [ ] No duplicate data-testid values in same page/route scope
-- [ ] No existing code modified beyond adding the attribute
-- [ ] Syntax validation passes on all modified files
-- [ ] Dynamic list items use template literals with unique keys
+---
+name: qa-testid-injector
+description: QA Test ID Injector. Scans source code to find interactive UI elements missing data-testid attributes and injects them following naming convention. Use when user wants to add test IDs, improve testability, audit missing test hooks, prepare for E2E automation, or add data-testid attributes before writing Playwright/Cypress tests. Triggers on "add test IDs", "add data-testid", "test hooks", "missing testid", "testability audit", "prepare for automation", "inject test attributes", "make components testable".
+---
+
+# QA Test ID Injector
+
+## Purpose
+
+Scan application source code, identify interactive UI elements lacking stable test selectors, and inject `data-testid` attributes following a consistent naming convention. Runs as **Step 0** — before any test generation.
+
+## Core Rule
+
+**Every interactive element MUST have a stable, unique `data-testid` before E2E tests are generated against it.**
+
+## Naming Convention
+
+Pattern: `{context}-{description}-{element-type}` in kebab-case.
+
+### Element Type Suffixes
+
+| Element | Suffix | Example |
+|---------|--------|---------|
+| button | -btn | login-submit-btn |
+| input | -input | login-email-input |
+| select | -select | settings-language-select |
+| textarea | -textarea | feedback-comment-textarea |
+| link | -link | navbar-profile-link |
+| form | -form | checkout-payment-form |
+| img | -img | product-hero-img |
+| table | -table | users-list-table |
+| row | -row | users-item-row |
+| modal | -modal | confirm-delete-modal |
+| container | -container | dashboard-stats-container |
+| list | -list | notifications-list |
+| item | -item | notifications-item |
+| dropdown | -dropdown | navbar-user-dropdown |
+| tab | -tab | settings-security-tab |
+| checkbox | -checkbox | terms-accept-checkbox |
+| radio | -radio | shipping-express-radio |
+| toggle | -toggle | notifications-enabled-toggle |
+| badge | -badge | cart-count-badge |
+| alert | -alert | error-validation-alert |
+
+### Context Derivation
+
+1. **Page-level**: From component filename or route (LoginPage.tsx -> login)
+2. **Component-level**: From component name (<NavBar> -> navbar)
+3. **Nested**: Parent -> child hierarchy, max 3 levels deep
+4. **Dynamic lists**: Use template literals with unique keys
+
+## Execution Phases
+
+### Phase 1: SCAN
+- Detect framework (React/Vue/Angular/HTML) from package.json and file extensions
+- List all component files (exclude test/spec/stories)
+- Prioritize by interaction density (forms > pages > layouts)
+- Output: SCAN_MANIFEST.md
+
+### Phase 2: AUDIT
+- For each file, identify interactive elements
+- Classify: P0 (must have), P1 (should have), P2 (nice to have)
+- Record existing data-testid as EXISTING (don't modify)
+- Record missing as MISSING with proposed value
+- Output: TESTID_AUDIT_REPORT.md
+
+### Phase 3: INJECT
+- Add data-testid as LAST attribute before closing >
+- Preserve all existing formatting
+- Only add the attribute — change nothing else
+- Framework-specific handling (JSX, Vue, Angular, HTML)
+- Output: INJECTION_CHANGELOG.md + modified source files
+
+### Phase 4: VALIDATE
+- Syntax check all modified files
+- Uniqueness check (no duplicate testids per page)
+- Convention compliance check
+- Output: INJECTION_VALIDATION.md
+
+## Third-Party Components
+
+1. Props passthrough (if library supports it) — direct data-testid
+2. Wrapper div (if no passthrough) — wrap with data-testid div
+3. inputProps/slotProps (MUI-specific) — use component-specific prop APIs
+
+## Quality Gate
+
+- [ ] Every interactive element has a data-testid
+- [ ] All values follow {context}-{description}-{element-type} convention
+- [ ] No duplicate data-testid values in same page/route scope
+- [ ] No existing code modified beyond adding the attribute
+- [ ] Syntax validation passes on all modified files
+- [ ] Dynamic list items use template literals with unique keys

package/{.claude/skills → skills}/qa-workflow-documenter/SKILL.md

@@ -1,87 +1,87 @@
----
-name: qa-workflow-documenter
-description: QA Workflow Documenter. Generates structured QA workflow documentation with decision trees, playbooks, and AI interaction protocols. Use when user wants to document QA processes, create testing playbooks, define workflow steps, document QA procedures, create decision trees for testing, or standardize QA processes. Triggers on "document workflow", "QA process", "testing playbook", "workflow documentation", "QA procedures", "decision tree", "standardize process", "document QA steps".
----
-
-# QA Workflow Documenter
-
-## Purpose
-
-Generate structured, AI-specific QA workflow documentation with decision trees, playbooks, and AI interaction protocols. Every step answers: WHO does it, WHAT they do, WHAT input they need, WHAT output they produce.
-
-## Core Principle
-
-**AI-first language**: Use precise verbs — scan, extract, classify, generate, validate. Never use vague terms like "review", "check", "handle".
-
-## Output Artifacts
-
-1. **WORKFLOW_[NAME].md** — Step-by-step workflow with decision gates
-2. **DECISION_TREE.md** — Visual decision trees for key branch points
-3. **AI_PROMPTS_CATALOG.md** — Reusable prompt patterns for each workflow step
-4. **CHECKLIST.md** — Pre/post verification checklists
-
-## Workflow Template Structure
-
-### Header Block
-```markdown
-# Workflow: [Name]
-**Version**: [semver]
-**Applies to**: [project types / tech stacks]
-**Prerequisites**: [what must exist before starting]
-**Estimated duration**: [time range]
-**Actors**: [AI Agent, QA Engineer, Team Lead]
-```
-
-### Step Format
-```markdown
-## Step N: [Name]
-**Actor**: [who executes this step]
-**Input**: [what they receive]
-**Action**: [precise description using action verbs]
-**Output**: [what they produce]
-**Decision Gate**: [condition to proceed vs branch]
-
-### AI Prompt Pattern
-[If this step involves an AI agent, include the prompt template]
-```
-
-## Workflow Types
-
-### 1. Repository Intake Workflow
-New repo arrives -> scan -> classify -> assess risk -> recommend strategy
-
-### 2. Test Case Generation Workflow
-Analysis done -> select targets -> generate cases -> validate -> deliver
-
-### 3. QA Repo Bootstrap Workflow
-Blueprint ready -> create structure -> generate configs -> seed initial tests
-
-### 4. Validation & Bug Triage Workflow
-Tests generated -> run -> classify failures -> fix loop -> report
-
-### 5. Test Maintenance Workflow
-Existing tests -> audit -> prioritize fixes -> apply -> verify
-
-## Decision Tree Format
-
-```markdown
-## Decision: [What decision]
-
-```
-[Question]?
-├── YES → [Action A]
-│   └── [Sub-question]?
-│       ├── YES → [Action A1]
-│       └── NO → [Action A2]
-└── NO → [Action B]
-```
-```
-
-## Quality Gate
-
-- [ ] Every step has Actor, Input, Action, Output
-- [ ] No vague verbs (review → scan + classify, check → validate against criteria)
-- [ ] Decision gates have clear YES/NO branches
-- [ ] AI prompt patterns included for AI-executed steps
-- [ ] Prerequisites listed for every workflow
-- [ ] Output artifacts named and described
+---
+name: qa-workflow-documenter
+description: QA Workflow Documenter. Generates structured QA workflow documentation with decision trees, playbooks, and AI interaction protocols. Use when user wants to document QA processes, create testing playbooks, define workflow steps, document QA procedures, create decision trees for testing, or standardize QA processes. Triggers on "document workflow", "QA process", "testing playbook", "workflow documentation", "QA procedures", "decision tree", "standardize process", "document QA steps".
+---
+
+# QA Workflow Documenter
+
+## Purpose
+
+Generate structured, AI-specific QA workflow documentation with decision trees, playbooks, and AI interaction protocols. Every step answers: WHO does it, WHAT they do, WHAT input they need, WHAT output they produce.
+
+## Core Principle
+
+**AI-first language**: Use precise verbs — scan, extract, classify, generate, validate. Never use vague terms like "review", "check", "handle".
+
+## Output Artifacts
+
+1. **WORKFLOW_[NAME].md** — Step-by-step workflow with decision gates
+2. **DECISION_TREE.md** — Visual decision trees for key branch points
+3. **AI_PROMPTS_CATALOG.md** — Reusable prompt patterns for each workflow step
+4. **CHECKLIST.md** — Pre/post verification checklists
+
+## Workflow Template Structure
+
+### Header Block
+```markdown
+# Workflow: [Name]
+**Version**: [semver]
+**Applies to**: [project types / tech stacks]
+**Prerequisites**: [what must exist before starting]
+**Estimated duration**: [time range]
+**Actors**: [AI Agent, QA Engineer, Team Lead]
+```
+
+### Step Format
+```markdown
+## Step N: [Name]
+**Actor**: [who executes this step]
+**Input**: [what they receive]
+**Action**: [precise description using action verbs]
+**Output**: [what they produce]
+**Decision Gate**: [condition to proceed vs branch]
+
+### AI Prompt Pattern
+[If this step involves an AI agent, include the prompt template]
+```
+
+## Workflow Types
+
+### 1. Repository Intake Workflow
+New repo arrives -> scan -> classify -> assess risk -> recommend strategy
+
+### 2. Test Case Generation Workflow
+Analysis done -> select targets -> generate cases -> validate -> deliver
+
+### 3. QA Repo Bootstrap Workflow
+Blueprint ready -> create structure -> generate configs -> seed initial tests
+
+### 4. Validation & Bug Triage Workflow
+Tests generated -> run -> classify failures -> fix loop -> report
+
+### 5. Test Maintenance Workflow
+Existing tests -> audit -> prioritize fixes -> apply -> verify
+
+## Decision Tree Format
+
+```markdown
+## Decision: [What decision]
+
+```
+[Question]?
+├── YES → [Action A]
+│   └── [Sub-question]?
+│       ├── YES → [Action A1]
+│       └── NO → [Action A2]
+└── NO → [Action B]
+```
+```
+
+## Quality Gate
+
+- [ ] Every step has Actor, Input, Action, Output
+- [ ] No vague verbs (review → scan + classify, check → validate against criteria)
+- [ ] Decision gates have clear YES/NO branches
+- [ ] AI prompt patterns included for AI-executed steps
+- [ ] Prerequisites listed for every workflow
+- [ ] Output artifacts named and described

package/workflows/qa-gap.md

@@ -129,11 +129,16 @@ Spawn the analyzer agent in gap analysis mode to compare dev repo testable surfa
 ```
 Task(
   prompt="
-    <objective>Perform gap analysis comparing dev repo testable surfaces against QA repo test coverage. Produce QA_ANALYSIS.md, TEST_INVENTORY.md, and GAP_ANALYSIS.md.</objective>
+    <objective>Perform gap analysis comparing dev repo testable surfaces against QA repo test coverage. Use codebase map for deep context and locator registry for frontend coverage assessment. Produce QA_ANALYSIS.md, TEST_INVENTORY.md, and GAP_ANALYSIS.md.</objective>
     <execution_context>@agents/qaa-analyzer.md</execution_context>
     <files_to_read>
     - {OUTPUT_DIR}/SCAN_MANIFEST.md
     - CLAUDE.md
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists -- locator coverage for risk assessment)
+    - .qa-output/codebase/RISK_MAP.md (if exists -- business-critical paths for risk assessment)
+    - .qa-output/codebase/CRITICAL_PATHS.md (if exists -- user flows for E2E scope)
+    - .qa-output/codebase/TEST_ASSESSMENT.md (if exists -- existing test quality)
+    - .qa-output/codebase/COVERAGE_GAPS.md (if exists -- uncovered modules)
     </files_to_read>
     <parameters>
     workflow_option: 2
@@ -142,6 +147,7 @@ Task(
     gap_analysis_path: {OUTPUT_DIR}/GAP_ANALYSIS.md
     dev_repo_path: {DEV_REPO}
     qa_repo_path: {QA_REPO}
+    codebase_map_dir: .qa-output/codebase
     </parameters>
   "
 )

package/workflows/qa-start.md

@@ -645,6 +645,29 @@ Agent(subagent_type="general-purpose",
 3. **Dependencies** -- Imports resolve, fixtures exist, configs present
 4. **Logic** -- Assertions are concrete, test IDs are unique, no assertions in page objects
 
+**5. Browser verification (if app URL available and Playwright MCP connected):**
+
+After the 4-layer static validation, use Playwright MCP to verify E2E tests against the live app:
+
+1. Navigate to each page referenced in the E2E tests:
+   ```
+   mcp__playwright__browser_navigate({ url: "{app_url}/{route}" })
+   ```
+
+2. Take an accessibility snapshot to verify locators used in tests actually exist:
+   ```
+   mcp__playwright__browser_snapshot()
+   ```
+
+3. Cross-reference locators in generated tests against the real DOM:
+   - Verify `data-testid` values exist on the page
+   - Verify ARIA roles and names match test expectations
+   - Flag any test locator that does not match a real DOM element
+
+4. If mismatches are found, fix the test locators to match the real DOM and count as a fix loop iteration.
+
+This browser verification step prevents delivering tests with locators that will immediately fail at runtime.
+
 **Fix loop:** The validator automatically attempts to fix issues it finds. Maximum 3 fix loop iterations. After each fix attempt, re-validate.
 
 **Parse validator return:**
@@ -716,7 +739,7 @@ node bin/qaa-tools.cjs state patch --"Status" "Classifying test failures" 2>/dev
 ```
 Agent(subagent_type="general-purpose",
   prompt="
-    <objective>Classify test failures and attempt auto-fixes for test errors</objective>
+    <objective>Classify test failures and attempt auto-fixes for test errors. Use Playwright MCP to reproduce E2E failures in the browser when available.</objective>
     <execution_context>@agents/qaa-bug-detective.md</execution_context>
     <files_to_read>
     - {test execution results -- from validator or direct test run}
@@ -725,6 +748,7 @@ Agent(subagent_type="general-purpose",
     </files_to_read>
     <parameters>
     output_path: {output_dir}/FAILURE_CLASSIFICATION_REPORT.md
+    app_url: {app_url if available}
     </parameters>
   "
 )

package/workflows/qa-testid.md

@@ -180,17 +180,22 @@ Spawn the testid-injector agent which operates in 4 phases: SCAN, AUDIT, INJECT,
 ```
 Task(
   prompt="
-    <objective>Audit frontend components for data-testid coverage and inject missing attributes</objective>
+    <objective>Audit frontend components for data-testid coverage and inject missing attributes. Use Playwright MCP to verify against live DOM. Use codebase map for component structure context. Update locator registry with discovered and injected locators.</objective>
     <execution_context>@agents/qaa-testid-injector.md</execution_context>
     <files_to_read>
     - {OUTPUT_DIR}/SCAN_MANIFEST.md
     - CLAUDE.md
     - data-testid-SKILL.md
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists -- existing locators to cross-reference)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists -- component naming conventions for context derivation)
+    - .qa-output/codebase/TEST_SURFACE.md (if exists -- UI component list with props/events)
+    - .qa-output/codebase/TESTABILITY.md (if exists -- component testability for injection priority)
     </files_to_read>
     <parameters>
     source_dir: {SOURCE_DIR}
     frontend_framework: {FRONTEND_FRAMEWORK}
     output_path: {OUTPUT_DIR}/TESTID_AUDIT_REPORT.md
+    app_url: {auto-detect from dev server or ask user}
     </parameters>
   "
 )
@@ -213,6 +218,29 @@ Task(
 
 5. **VALIDATE phase:** Runs syntax checks on all modified files, verifies uniqueness of data-testid values per page/route scope, checks naming convention compliance, and verifies no unintended source code changes (non-interference check). If syntax fails, reverts the specific file.
 
+6. **BROWSER VERIFY phase (if app URL available and Playwright MCP connected):**
+
+   After injection and static validation, use Playwright MCP to verify the injected `data-testid` attributes are present in the rendered DOM:
+
+   1. Navigate to each page/route that has injected components:
+      ```
+      mcp__playwright__browser_navigate({ url: "{app_url}/{route}" })
+      ```
+
+   2. Take an accessibility snapshot to inspect the rendered DOM:
+      ```
+      mcp__playwright__browser_snapshot()
+      ```
+
+   3. Cross-reference: for each injected `data-testid`, verify it appears in the snapshot. Report:
+      - **CONFIRMED**: `data-testid` found in rendered DOM
+      - **NOT RENDERED**: Component exists in source but not rendered on this route (may appear conditionally)
+      - **MISSING**: `data-testid` expected but not found in DOM (possible injection error)
+
+   4. Add browser verification results to the TESTID_AUDIT_REPORT.md as a "Browser Verification" section.
+
+   This step is **optional** -- if no app URL is available or the app is not running, skip and rely on static validation only.
+
 **Handle injector return:**
 
 Extract:

package/workflows/qa-validate.md

@@ -131,11 +131,15 @@ Spawn the validator agent to perform 4-layer validation with fix loop.
 ```
 Task(
   prompt="
-    <objective>Validate test files against CLAUDE.md standards across 4 layers (Syntax, Structure, Dependencies, Logic)</objective>
+    <objective>Validate test files against CLAUDE.md standards across 4 layers (Syntax, Structure, Dependencies, Logic). Use codebase map for context and locator registry to verify locator accuracy.</objective>
     <execution_context>@agents/qaa-validator.md</execution_context>
     <files_to_read>
     - CLAUDE.md
     - {synthetic file list or generation plan path}
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists -- real locators for cross-checking POM accuracy)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists -- naming conventions for structure validation)
+    - .qa-output/codebase/TEST_SURFACE.md (if exists -- function signatures for target verification)
+    - .qa-output/codebase/API_CONTRACTS.md (if exists -- API shapes for assertion verification)
     </files_to_read>
     <parameters>
     test_dir: {TEST_DIR}