qaa-agent 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "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"
@@ -21,15 +21,21 @@
   },
   "author": "Backhaus7997",
   "license": "MIT",
+  "dependencies": {
+    "@playwright/mcp": "latest"
+  },
   "files": [
     "bin/",
     "agents/",
     "workflows/",
     "templates/",
+    "docs/",
     ".claude/commands/",
     ".claude/skills/",
     ".claude/settings.json",
+    ".mcp.json",
     "CLAUDE.md",
+    "CHANGELOG.md",
     "README.md"
   ]
 }

package/workflows/qa-from-ticket.md

@@ -215,8 +215,69 @@ Generating test cases based on ticket content only (no source-level analysis).
 ```
 </step>
 
+<step name="extract_locators_from_app">
+## Step 5: Check Locator Registry and Extract from Live App (Optional)
+
+Check the locator registry for existing locators, and if needed, use Playwright MCP to extract new ones from the live app.
+
+**Step 5a: Check existing registry**
+
+Read `.qa-output/locators/LOCATOR_REGISTRY.md` if it exists. Check if locators for pages related to this ticket's feature already exist. If they do and no `--app-url` was provided, reuse them and skip browser extraction.
+
+**Step 5b: When to extract from browser**
+- Locators for this feature's pages are NOT in the registry, OR
+- An `--app-url` argument was explicitly provided (forces re-extraction)
+
+**When to skip entirely:**
+- No app URL available, no dev server detected, AND no registry exists
+- The ticket describes only backend/API functionality with no UI
+
+**Extraction process:**
+
+1. Identify relevant pages from the ticket's acceptance criteria and affected components (from Step 3 and Step 4).
+
+2. For each relevant page, navigate and capture:
+   ```
+   mcp__playwright__browser_navigate({ url: "{app_url}/{page_path}" })
+   mcp__playwright__browser_snapshot()
+   ```
+
+3. If the ticket describes a user flow (e.g., "user fills form and submits"), walk through the flow:
+   ```
+   mcp__playwright__browser_fill_form({ ... })
+   mcp__playwright__browser_click({ element: "Submit button" })
+   mcp__playwright__browser_snapshot()  // capture resulting page
+   ```
+
+4. From each snapshot, extract:
+   - All `data-testid` attributes
+   - ARIA roles with accessible names
+   - Form labels and placeholders
+   - Page structure and navigation elements
+
+5. Write per-feature locator file to `.qa-output/locators/{feature}.locators.md`:
+   ```markdown
+   # Locators -- {feature}
+
+   Extracted: {date}
+   App URL: {app_url}
+
+   ## Page: {page_name} ({url})
+
+   | Element | Locator Type | Locator Value | Tier |
+   |---------|-------------|---------------|------|
+   | ... | data-testid | ... | 1 |
+   | ... | role + name | ... | 1 |
+   | ... | label | ... | 2 |
+   ```
+
+6. Update the registry `.qa-output/locators/LOCATOR_REGISTRY.md` -- merge new locators into the central index without overwriting locators from other features.
+
+If this step is skipped entirely, the executor will propose locators based on source code analysis and CLAUDE.md conventions.
+</step>
+
 <step name="generate_test_cases">
-## Step 5: Generate Test Cases with Traceability Matrix
+## Step 6: Generate Test Cases with Traceability Matrix
 
 Map each acceptance criterion to one or more test cases, following CLAUDE.md test spec rules.
 
@@ -312,7 +373,7 @@ Write to `{OUTPUT_DIR}/TEST_CASES_FROM_TICKET.md`.
 </step>
 
 <step name="generate_test_files">
-## Step 6: Spawn Executor Agent
+## Step 7: Spawn Executor Agent
 
 Build a synthetic generation plan from the test cases and spawn the executor to write test files.
 
@@ -361,6 +422,7 @@ Task(
     <files_to_read>
     - {OUTPUT_DIR}/GENERATION_PLAN_TICKET.md
     - {OUTPUT_DIR}/TEST_CASES_FROM_TICKET.md
+    - {OUTPUT_DIR}/locators/LOCATOR_REGISTRY.md (if exists -- accumulated real locators)
     - CLAUDE.md
     </files_to_read>
     <parameters>
@@ -376,7 +438,7 @@ Extract: `files_created`, `total_files`, `commit_count`, `test_case_count`.
 </step>
 
 <step name="validate_generated_tests">
-## Step 7: Spawn Validator Agent
+## Step 8: Spawn Validator Agent
 
 Validate the generated test files against CLAUDE.md standards.
 
@@ -402,7 +464,7 @@ Extract: `overall_status`, `confidence`, `issues_found`, `issues_fixed`, `unreso
 </step>
 
 <step name="print_summary">
-## Step 8: Print Summary
+## Step 9: Print Summary
 
 Print a comprehensive summary showing traceability from ticket to tests.
 

package/workflows/qa-pr.md

@@ -0,0 +1,389 @@
+<purpose>
+Create a draft PR from QA artifacts (test files, POMs, fixtures, reports) already on disk. Detects git platform (GitHub, Azure DevOps, GitLab), applies the team's branch naming convention (saved in preferences), stages only test/QA files, and creates a draft PR with a summary. Standalone command -- does not require the full pipeline to have run.
+</purpose>
+
+<required_reading>
+- `CLAUDE.md` -- Git workflow section (branch naming, commit conventions, PR template)
+- `~/.claude/qaa/MY_PREFERENCES.md` -- Branch naming convention (if saved)
+- `templates/pr-template.md` -- PR body template
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` to extract optional flags.
+
+**Supported arguments:**
+
+| Flag | Example | Description |
+|------|---------|-------------|
+| `--ticket` | `--ticket PROJ-123` | Ticket/issue ID for branch name |
+| `--title` | `--title "login tests"` | Short description for branch and PR title |
+| `--scope` | `--scope unit` | Limit to file type: unit, api, e2e, all (default: all) |
+| `--files` | `--files tests/unit/auth*` | Explicit file glob to include |
+| `--base` | `--base develop` | Target branch for PR (default: auto-detect) |
+
+**If no arguments provided:**
+
+Scan for QA artifacts to include:
+1. Check `.qa-output/` for generated test files, POMs, fixtures
+2. Check current git status for unstaged/untracked test files
+3. If nothing found, print error and STOP:
+```
+Error: No QA artifacts found to deliver.
+Run /qa-start, /create-test, or /qa-map first to generate artifacts.
+```
+</step>
+
+<step name="detect_platform">
+## Step 2: Detect Git Platform
+
+```bash
+REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
+```
+
+**Platform detection from remote URL:**
+
+| Pattern | Platform | CLI Tool | PR Command |
+|---------|----------|----------|------------|
+| `github.com` or `gh:` | GitHub | `gh` | `gh pr create` |
+| `dev.azure.com` or `visualstudio.com` or `azure` | Azure DevOps | `az` | `az repos pr create` |
+| `gitlab.com` or `gitlab` | GitLab | `glab` | `glab mr create` |
+
+```bash
+PLATFORM=""
+PR_CLI=""
+
+if echo "$REMOTE_URL" | grep -qi "github"; then
+  PLATFORM="github"
+  PR_CLI="gh"
+elif echo "$REMOTE_URL" | grep -qi "dev.azure.com\|visualstudio.com\|azure"; then
+  PLATFORM="azure"
+  PR_CLI="az"
+elif echo "$REMOTE_URL" | grep -qi "gitlab"; then
+  PLATFORM="gitlab"
+  PR_CLI="glab"
+else
+  PLATFORM="unknown"
+fi
+```
+
+**If platform is unknown:**
+```
+CHECKPOINT:
+type: human-action
+blocking: "Cannot detect git platform from remote URL"
+details: "Remote URL: ${REMOTE_URL}"
+awaiting: "Which platform? (github / azure / gitlab)"
+```
+
+**Verify CLI tool is available and authenticated:**
+
+For GitHub:
+```bash
+gh auth status 2>/dev/null
+```
+
+For Azure DevOps:
+```bash
+az account show 2>/dev/null
+```
+
+For GitLab:
+```bash
+glab auth status 2>/dev/null
+```
+
+If CLI tool is not installed or not authenticated:
+```
+Error: ${PR_CLI} CLI not found or not authenticated.
+
+GitHub:  Install from https://cli.github.com, then run: gh auth login
+Azure:   Install from https://aka.ms/azure-cli, then run: az login
+GitLab:  Install from https://gitlab.com/gitlab-org/cli, then run: glab auth login
+```
+</step>
+
+<step name="resolve_branch_convention">
+## Step 3: Resolve Branch Naming Convention
+
+**Check saved preferences:**
+```bash
+BRANCH_PATTERN=""
+if [ -f ~/.claude/qaa/MY_PREFERENCES.md ]; then
+  # Look for branch pattern in Workflow section
+  BRANCH_PATTERN=$(grep -A1 "branch.*pattern\|branch.*convention\|branch.*naming" ~/.claude/qaa/MY_PREFERENCES.md | tail -1)
+fi
+```
+
+**If no saved convention, ask the user:**
+
+```
+No branch naming convention configured.
+What pattern does your team use?
+
+  1) feature/{ticket}-{description}
+  2) test/{ticket}-{description}
+  3) qa/{ticket}-{description}
+  4) {user}/{ticket}-{description}
+  5) feature/QAA-{date}-{description}
+  6) Custom (write your own with placeholders)
+
+Placeholders: {ticket}, {date}, {description}, {user}, {scope}
+```
+
+**On user response:**
+- Save the chosen pattern to `~/.claude/qaa/MY_PREFERENCES.md` under `## Workflow` section
+- Format: `- Branch naming convention: {pattern} — (added {date}, context: "user configured branch pattern via /qa-pr")`
+
+**Build actual branch name from pattern:**
+
+Replace placeholders with real values:
+- `{ticket}` -- from `--ticket` flag, or prompt user if pattern requires it
+- `{date}` -- today's date YYYY-MM-DD
+- `{description}` -- from `--title` flag, sanitized to kebab-case (lowercase, hyphens, no special chars)
+- `{user}` -- from `git config user.name`, sanitized to kebab-case
+- `{scope}` -- from `--scope` flag or "qa"
+
+```bash
+BRANCH_NAME=$(echo "$BRANCH_PATTERN" | sed \
+  -e "s/{ticket}/${TICKET}/g" \
+  -e "s/{date}/${DATE}/g" \
+  -e "s/{description}/${DESCRIPTION}/g" \
+  -e "s/{user}/${USER}/g" \
+  -e "s/{scope}/${SCOPE}/g")
+```
+
+**If ticket is required by pattern but not provided:**
+```
+Your branch pattern requires a ticket ID: {pattern}
+Provide ticket ID (e.g., PROJ-123):
+```
+</step>
+
+<step name="collect_files">
+## Step 4: Collect Files to Include
+
+Gather all QA artifacts that should go into the PR.
+
+**If `--files` flag provided:** Use that glob directly.
+
+**Otherwise, auto-detect:**
+
+```bash
+QA_FILES=()
+
+# 1. Generated test files
+find . -path '*/tests/*' -name '*.spec.*' -o -name '*.test.*' -o -name '*.e2e.*' -o -name '*.cy.*' | while read f; do
+  QA_FILES+=("$f")
+done
+
+# 2. Page Object Models
+find . -path '*/pages/*' -o -path '*/page-objects/*' | grep -E '\.(ts|js|py)$' | while read f; do
+  QA_FILES+=("$f")
+done
+
+# 3. Fixtures
+find . -path '*/fixtures/*' -name '*-data.*' | while read f; do
+  QA_FILES+=("$f")
+done
+
+# 4. Config files (test configs only)
+for cfg in playwright.config.* jest.config.* vitest.config.* cypress.config.* pytest.ini conftest.py; do
+  [ -f "$cfg" ] && QA_FILES+=("$cfg")
+done
+
+# 5. QA output reports
+find .qa-output -name '*.md' 2>/dev/null | while read f; do
+  QA_FILES+=("$f")
+done
+```
+
+**Apply scope filter if `--scope` provided:**
+- `unit` -- only `*.unit.spec.*`, `*.test.*` files
+- `api` -- only `*.api.spec.*` files
+- `e2e` -- only `*.e2e.spec.*`, `*.cy.*` files + POMs
+- `all` -- everything (default)
+
+**If no files found:** Print error and STOP.
+
+**Security check:**
+- Exclude any `.env`, `credentials.*`, `secrets.*`, `*.key`, `*.pem` files
+- Warn if any file contains hardcoded passwords/tokens (grep for common patterns)
+</step>
+
+<step name="confirm_with_user">
+## Step 5: Confirmation Checkpoint
+
+Present the plan to the user and wait for confirmation.
+
+```
+╔══════════════════════════════════════════╗
+║  /qa-pr — Create QA Pull Request        ║
+╠══════════════════════════════════════════╣
+║                                          ║
+║  Platform:  {PLATFORM}                   ║
+║  Branch:    {BRANCH_NAME}                ║
+║  Target:    {DEFAULT_BRANCH}             ║
+║  Type:      Draft PR                     ║
+║                                          ║
+║  Files ({FILE_COUNT}):                   ║
+║    {N} test specs                        ║
+║    {N} page objects                      ║
+║    {N} fixtures                          ║
+║    {N} config files                      ║
+║    {N} QA reports                        ║
+║                                          ║
+╚══════════════════════════════════════════╝
+
+Proceed? (y/n)
+```
+
+**If user says no:** Print "Cancelled." and STOP.
+</step>
+
+<step name="create_branch_and_commit">
+## Step 6: Create Branch and Commit
+
+**Detect default branch:**
+```bash
+# GitHub
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null)
+
+# Azure DevOps
+if [ -z "$DEFAULT_BRANCH" ]; then
+  DEFAULT_BRANCH=$(az repos show --query 'defaultBranch' -o tsv 2>/dev/null | sed 's|refs/heads/||')
+fi
+
+# GitLab
+if [ -z "$DEFAULT_BRANCH" ]; then
+  DEFAULT_BRANCH=$(glab repo view --json default_branch --jq '.default_branch' 2>/dev/null)
+fi
+
+# Fallback
+DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
+```
+
+**Override with `--base` flag if provided.**
+
+**Create branch:**
+```bash
+git checkout -b "$BRANCH_NAME" "origin/$DEFAULT_BRANCH"
+```
+
+**Handle collision:**
+```bash
+if git rev-parse --verify "$BRANCH_NAME" 2>/dev/null; then
+  SUFFIX=2
+  while git rev-parse --verify "${BRANCH_NAME}-${SUFFIX}" 2>/dev/null; do
+    SUFFIX=$((SUFFIX + 1))
+  done
+  BRANCH_NAME="${BRANCH_NAME}-${SUFFIX}"
+  git checkout -b "$BRANCH_NAME" "origin/$DEFAULT_BRANCH"
+fi
+```
+
+**Stage and commit:**
+```bash
+git add ${QA_FILES[@]}
+git commit -m "qa(pr): add ${FILE_COUNT} QA artifacts — ${DESCRIPTION}"
+```
+</step>
+
+<step name="push_and_create_pr">
+## Step 7: Push and Create PR
+
+**Push branch:**
+```bash
+git push -u origin "$BRANCH_NAME"
+```
+
+**Build PR body from template (if available) or minimal summary:**
+
+If `templates/pr-template.md` exists and QA reports are available, populate it.
+Otherwise use minimal body:
+
+```markdown
+## QA Artifacts
+
+${FILE_COUNT} files added:
+- ${test_count} test specs
+- ${pom_count} page objects
+- ${fixture_count} fixtures
+
+${TICKET_REF}
+
+---
+Generated by QAA (QA Automation Agent)
+```
+
+**Create PR by platform:**
+
+**GitHub:**
+```bash
+PR_URL=$(gh pr create \
+  --draft \
+  --title "qa: ${DESCRIPTION}" \
+  --body "${PR_BODY}")
+```
+
+**Azure DevOps:**
+```bash
+PR_URL=$(az repos pr create \
+  --draft \
+  --title "qa: ${DESCRIPTION}" \
+  --description "${PR_BODY}" \
+  --source-branch "$BRANCH_NAME" \
+  --target-branch "$DEFAULT_BRANCH" \
+  --query 'url' -o tsv)
+```
+
+**GitLab:**
+```bash
+PR_URL=$(glab mr create \
+  --draft \
+  --title "qa: ${DESCRIPTION}" \
+  --description "${PR_BODY}" \
+  --source-branch "$BRANCH_NAME" \
+  --target-branch "$DEFAULT_BRANCH" \
+  --yes)
+```
+
+**On failure:** Print error with branch name so user can create PR manually.
+</step>
+
+<step name="print_result">
+## Step 8: Print Result
+
+```
+╔══════════════════════════════════════════╗
+║  PR Created ✓                            ║
+╠══════════════════════════════════════════╣
+║                                          ║
+║  ${PR_URL}                               ║
+║                                          ║
+║  Branch:   ${BRANCH_NAME}                ║
+║  Target:   ${DEFAULT_BRANCH}             ║
+║  Files:    ${FILE_COUNT}                 ║
+║  Status:   Draft                         ║
+║                                          ║
+╚══════════════════════════════════════════╝
+```
+</step>
+
+</process>
+
+<error_handling>
+| Error | Cause | Action |
+|-------|-------|--------|
+| No QA artifacts found | Nothing generated yet | Print error, suggest /qa-start or /create-test |
+| Platform not detected | Unusual remote URL | Ask user to specify platform |
+| CLI not installed | gh/az/glab missing | Print install instructions for detected platform |
+| CLI not authenticated | Not logged in | Print auth command for detected platform |
+| Branch already exists | Name collision | Auto-append numeric suffix |
+| Push fails | Permission or network | Print error, keep local commits |
+| PR creation fails | API error | Print error with branch name for manual PR creation |
+| Ticket required but missing | Pattern uses {ticket} | Prompt user for ticket ID |
+</error_handling>

package/.claude/commands/qa-analyze.md

@@ -1,21 +0,0 @@
-# QA Repository Analysis
-
-Analysis-only mode. Scans a repository, detects framework and stack, and produces QA assessment documents. No test generation. No PR creation.
-
-## Usage
-
-/qa-analyze [--dev-repo <path>] [--qa-repo <path>]
-
-- No arguments: analyzes current directory
-- --dev-repo: explicit path to developer repository
-- --qa-repo: path to existing QA repository (produces gap analysis instead of blueprint)
-
-## Instructions
-
-1. Read `CLAUDE.md` -- all QA standards.
-2. Execute the workflow:
-
-Follow the workflow defined in `@workflows/qa-analyze.md` end-to-end.
-Preserve all workflow gates (scan verification, artifact checks).
-
-$ARGUMENTS