@kamleshsk/claude-qa

This is a CLI tool — run it with npx, not npm install.

npx @kamleshsk/claude-qa

Do not run npm install @kamleshsk/claude-qa. Installing it as a dependency does nothing useful — it is designed to be executed once per project via npx.

One command to install a complete Claude Code QA automation framework into any project.

What's new in v3.7.0

• Dynamic test angles — no longer bound to happy / validation / hierarchy. Angles are now an open palette. A recommended baseline set (happy, validation, hierarchy, negative, boundary, edge, permission, security, api_async, ui_ux) is always available, but every command may also invent custom angles the source material implies — e.g. accessibility, workflow, concurrency, localization, audit_log, notification, data_integrity, performance. The whole framework was made angle-agnostic: the QA portal runner accepts any registered or safe lowercase angle (no more HTTP 400 on non-baseline angles), the dashboard renders & counts custom paths, register.js validates by format instead of a fixed list, and ANGLE_MAP passes unknown full angle names through. export const ANGLES in generated modules is now variable-length.
• Strict full-case generation — every discovered case is created. /qa-complex now enumerates every discrete test case inside each reference file (numbered items, table rows, spreadsheet rows, bulleted scenarios) into a flat MASTER CASE LIST whose length is the authoritative DISCOVERED count. The Coverage Matrix and a fully-enumerated Execution Map must equal that count, and a hard count-reconciliation gate blocks completion unless DISCOVERED == execution-map rows == implemented step-groups == registry entries. Sampling words/behaviours ("representative", "subset", "top N", "etc.") are explicitly forbidden — if it finds 171 cases, it creates 171. /qa-update applies the same full-enumeration + count discipline to reference-file diffs.
• QA dashboard — fixed the long-module truncation bug. Module bodies were capped at max-height: 2000px with overflow:hidden, which silently clipped large modules at ~54 rows (hiding the rest of a path and every path below it). The cap is lifted so all cases across all paths render.
• QA dashboard — collapsible paths + per-path scrollbars. Each path section now has its own collapse chevron (click the header to expand/collapse) and its own inner scrollbar, so a 64-case path scrolls in place instead of running down the page.
• Path-level IDs. Each path now shows a copyable path ID (<module>-<code>, e.g. d-psp-hap) on the dashboard, and /qa-debugger accepts it to debug/fix an entire path at once — /qa-debugger d-psp-hap runs the whole happy path, alongside the existing single-case (d-psp-hap-001) and whole-module (d-psp) forms.

What was in v3.6.1

• /qa-complex & /qa-update — spreadsheet reference files (.csv / .xlsx / .xls) — both commands now accept Excel and CSV files as reference material. The file-extension classifier recognises .csv/.xlsx/.xls as a spreadsheet content type. Since the Read tool cannot open binary workbooks, each command now converts .xlsx/.xls to CSV first (trying ssconvert, then libreoffice --headless --convert-to csv, then a pandas per-sheet fallback) and reads the resulting CSV — treating each row as one test case. Plain .csv files are read directly. In /qa-update, the converted CSV text (not the raw binary) is stored in the .snap content field so diffs stay stable.

What was in v3.6.0

• /qa-setup — direct DB user creation — QA users are now inserted directly into the database via php artisan tinker with updateOrInsert (idempotent). No seeder file is written or required. Re-running /qa-setup safely updates existing rows.
• /qa-setup — five-stage safety protocol — all DB and credential work now follows a strict READ → ANALYSE → PLAN → CONFIRM SAFETY → ACT gate. Claude must fully write out each stage before proceeding to the next. Nothing touches the DB until STAGE 5.
• /qa-setup — auth structure discovery — Claude finds the real authenticatable model (never assumes User.php), reads migrations for exact table name and role enum values, checks for companion models, and discovers all role values from the live DB before writing a single row.
• /qa-setup — auto QA credentials — [email protected] and QA_PASSWORD=Password@1 are automatically appended to .env during Step 1 if missing. Per-role QA_<ROLE>_EMAIL and QA_<ROLE>_PASSWORD keys are appended in Step 5 for every role discovered in the DB. Existing keys are never overwritten.
• /qa-setup — mandatory Node / Playwright / Chromium verification — Step 9 now runs a strict runtime check: Node.js version (≥ 18 required), npm presence, playwright npm package in node_modules, and Chromium binary on disk. Each failure prints the exact fix command. Setup does not proceed past this check if any ❌ is present.

What was in v3.5.0

• Canonical docs/qa-reference/ layout — snap files now live inside <role>/<feature>/ alongside their txt reference file, named <feature>-snap.snap (e.g. docs/qa-reference/sa/product/product-snap.snap). Previously they were misplaced at the role level.
• txt reference files moved from <role>/ into <role>/<feature>/ — the feature subfolder is now the single source of truth for all artefacts belonging to a role/feature pair.
• All four QA commands updated — /qa-complex, /qa-update, /qa-simple, and /qa-debugger read and write the new <feature>-snap.snap path inside the feature folder.
• Reference-file scan fixed — find exclusion and node.js .filter() updated from -not -name ".snap" to -not -name "*-snap.snap" so snap files living inside the feature folder are never accidentally ingested as reference material.

What was in v3.4.0

• /qa-update v3.2 — GOD TIER upgrade, live browser meta-tested through a 12-layer × 3-consecutive-pass regression battery on admin-state:
  • 5-level regression verification pipeline (Structural → Runtime → Behavioral → Deep Reliability → Production Stability) with real Playwright headed browser execution at each level.
  • [QA-MONITOR] runtime monitoring injected before browser runs: page.on('pageerror'), page.on('requestfailed'), page.on('response'), console tracking, and DOM MutationObserver — all captured in RUNTIME_CONTEXT.
  • Invariant #16 — Always fill('') before fill(searchValue) in DataTable verify steps to clear any prior filter or stateSave-restored search.
  • Invariant #17 — Never add a second goto(listingUrl) after waitForNavAway() already landed on the listing page. The second goto triggers DataTables to re-initialize and restore a stale search via stateSave, racing against the new search AJAX.
  • runtime_metadata in .snap — now records verification_levels_passed, consecutive_stability_passes, fix_cycles, root_causes_resolved, last_browser_run_at, angles_executed.
  • Risk Analysis + Validation Impact + Runtime Impact added to Phase 4 human review summary.
  • Phase 8 failure recovery: full 10-category root cause detection + complete runtime context capture (console, DOM, network, DB, screenshots, timeline).
  • Phase 5-A strict per-field faker random data loop: generate → detect unique constraints → pre-check DB → loop until unique.
• /qa-debugger v3 — Step 7f added: writes .snap baseline after successful fix verification (was entirely missing in v2). Covers: folder creation, SHA-256 recomputation for all reference files, test_cases parsing from ANGLES export (handles api_async→runAsync, ui_ux→runUiUx via ANGLES lookup first, not naive camelCase), CHANGELOG append to module header.
• /qa-simple v6.2 — Phase 10.5 Regression Stability Loop + Gate 15 jQuery hidden label protection (carried from v3.2.0 work, now properly under latest tag).
• Invariant count raised to 17 in /qa-update.

What was in v3.1.0

• /qa-complex full rewrite — 11-phase pipeline: reads folder structure as spec, classifies all test types (happy/validation/negative/boundary/edge/permission/security/api_async/ui_ux), human gap-check HARD STOP, 4-layer constraint audit, fresh faker data + DB uniqueness loop, 3-level verification, writes .snap baseline for future diffs
• /qa-update full rewrite — surgical reconciler: chat-driven OR reference-driven (.snap diff), VDOM-style minimal patch (only changed lines regenerate), human gap-check HARD STOP, byte-identical preservation of all unchanged content, 3-level verification pipeline, updates .snap at completion
• Both commands now write/read docs/qa-reference/<role>/<feature>/.snap for reproducible diffs

What was in v3.0.3

• /qa renamed to /qa-simple — same usage, no test changes needed
• New /qa-complex introduced (stub)
• New /qa-update introduced (stub)
• New docs/qa-reference/ folder — drop in specs and screenshots per role/feature

What it does

@kamleshsk/claude-qa gives Claude Code six powerful slash commands that turn test creation, generation from specs, debugging, and repair into a seamless, AI-driven workflow — no configuration, no boilerplate, no guesswork.

| Command | What it does | |---|---| | /qa-setup | One-time scaffold — builds the entire QA framework from scratch | | /qa-simple | Generate a test module from a description (quick mode) | | /qa-complex | Generate a test module from reference files in docs/qa-reference/ | | /qa-update | Update or extend modules when reference files change | | /qa-debugger | Debug a single failing test — root cause, fix, verify | | /qa-healer | Heal the entire test suite in bulk — triage, batch-fix, report |

Install

Use npx — not npm install. The npm page always shows npm i but that is not how this tool works. Run it with npx to execute it directly without adding it to your dependencies.

Run this from your project root (the folder that contains composer.json or your app root):

npx @kamleshsk/claude-qa

To always get the latest version:

npx @kamleshsk/claude-qa@latest

This copies all commands, skills, and reference docs into your project and automatically installs all Node dependencies — no manual setup needed.

What gets installed

.claude/
├── commands/
│   ├── qa-setup.md      ← /qa-setup     scaffold the entire framework (run once)
│   ├── qa-simple.md     ← /qa-simple    generate a test module from a description
│   ├── qa-complex.md    ← /qa-complex   generate a test module from reference files
│   ├── qa-update.md     ← /qa-update    update modules when reference files change
│   ├── qa-debugger.md   ← /qa-debugger  debug a single failing test
│   └── qa-healer.md     ← /qa-healer    heal all broken tests in bulk
└── skills/
    └── playwright-cli/
        └── references/  ← 11 reference docs (conditional forms, sessions, tracing…)

docs/
└── qa-reference/
    ├── README.md        ← naming conventions and usage guide
    ├── admin/           ← drop reference files here for admin role
    └── doctor/          ← drop reference files here for doctor role

Setup (run once per project)

1 — Install

cd /your/project
npx @kamleshsk/claude-qa

2 — Reload Claude Code and run /qa-setup

Reload Claude Code so it picks up the new commands:

• VS Code extension: Cmd/Ctrl+Shift+P → Developer: Reload Window
• CLI: exit then claude again

Then type /qa-setup in Claude Code. When it finishes:

chmod +x scripts/qa scripts/qa-register

Then paste this into Claude Code to register the middleware alias:

Find the EnsureQAAuth middleware file, detect the Laravel version, and register the qa.auth alias
if it is missing — in bootstrap/app.php for Laravel 11+, or app/Http/Kernel.php for Laravel 10
and below. Confirm the alias is registered when done.

3 — Wire up credentials

Inspect this project's auth structure — find the real auth model, table name, and how roles are
stored. Do not assume any field names. Run pending migrations, then check if the login identifier,
role column, active gate, and email verification columns exist. Create safe idempotent migrations
for anything missing. Finally, append QA_EMAIL, QA_PASSWORD, and one credential pair per role to
.env without overwriting existing values. Derive the email domain from APP_URL (use
yourproject.local if localhost).

4 — QA users (handled automatically by /qa-setup)

/qa-setup Step 5 creates QA users directly in the database via php artisan tinker — no seeder required. It discovers the real auth model, table, and role values from the live DB, then runs updateOrInsert for one user per role. It also appends QA_<ROLE>_EMAIL and QA_<ROLE>_PASSWORD to .env for every role it finds.

If you need to re-create or update QA users at any time, just re-run /qa-setup — it is fully idempotent.

5 — Verify

Start your server and open <APP_URL>/qa in a browser. Log in with QA_EMAIL / QA_PASSWORD from .env. The dashboard should load.

Commands

/qa-setup

Scaffolds the entire QA framework from scratch. Run this once per project after installing.

It generates:

• tests/e2e/js/runner.js — the TestRunner class with interactive autofill, step helpers, and login
• tests/e2e/js/main.js — CLI entry point with module picker and headless/headed modes
• tests/e2e/js/register.js — test case registry (add, list, update status)
• tests/e2e/js/config.js — loads .env and builds credentials map per role
• scripts/qa, scripts/qa-register — shell wrappers
• Laravel QA portal — /qa login page and dashboard

Usage:

/qa-setup

/qa-simple

Generates a complete Playwright test module for any feature — happy path, validation, and hierarchy angles, all in one shot.

Claude reads your migrations, controllers, and Blade templates to understand the feature's constraints, then writes a production-quality test module with:

• Happy path — create, verify, edit, delete with full CRUD coverage
• Validation — required fields, duplicate UNIQUE checks, max-length+1, format violations
• Hierarchy — parent-child relationships, cascade delete, FK constraint verification
• Interactive autofill — Autofill / Submit overlay in headed mode for manual review
• Runtime-unique test data — _tag pattern ensures no collisions between runs

Usage:

/qa-simple <feature-name> "<what this feature does>"

Examples:

/qa-simple users "Admin can create, edit, and delete user accounts"
/qa-simple products "Admin can add products with price, category, and image"
/qa-simple orders "Manager can view, approve, and cancel orders"

After generation, run the test headed to watch it live:

./scripts/qa users happy h

What Claude handles automatically:

| Scenario | How it's handled | |---|---| | Conditional fields (x-show, x-if, wire:show) | Sets controlling field first, waits for visibility | | Select2 / TomSelect dropdowns | page.evaluate() + dispatchEvent pattern | | Flatpickr / datepickers | _flatpickr.setDate() JS API | | AJAX-cascaded dropdowns | :not([disabled]) wait — never sleep() | | Image / file uploads | Auto-fills from public/qa-samples/ | | Edit pages with image-delete buttons | Uses data-testid="save-<resource>" — never .first() | | Same-URL redirect after save | domcontentloaded + toast waitFor — never networkidle |

Migrating from v2.x? /qa has been renamed to /qa-simple. Same syntax, same output. The old .claude/commands/qa.md is removed automatically when you run npx @kamleshsk/claude-qa@latest.

/qa-complex

Generates a complete Playwright test module from reference artefact files — PDFs, Word docs, screenshots, or plain-text specs stored in docs/qa-reference/.

Claude reads the artefacts, extracts feature understanding (CRUD operations, required fields, validation rules, parent-child relationships), and detects which test angles to generate. It then performs the same 4-layer constraint audit as /qa-simple before writing any test step.

Usage:

/qa-complex <role/feature>

Examples:

/qa-complex admin/doctor       ← reads all files at docs/qa-reference/admin/doctor/
/qa-complex doctor/order       ← reads docs/qa-reference/doctor/order/

Supported reference file types:

| Extension | Contents | |-----------|----------| | .txt | Plain-text scenarios, acceptance criteria, user stories | | .pdf | Formal spec documents, QA plans, exported sheets | | .docx | Word documents with test case tables or scenario lists | | .csv / .xlsx / .xls | Spreadsheets — one test case per row, header row = field meaning | | .png / .jpg | UI screenshots, annotated mockups, wireframes |

Multiple files per feature are merged:

docs/qa-reference/admin/doctor/doctor.pdf    ← formal spec
docs/qa-reference/admin/doctor/doctor.png    ← UI screenshot

Both are read together when you run /qa-complex admin/doctor.

What happens at runtime:

1. Reads all reference files for the given role/feature
2. Extracts Feature Understanding — CRUD ops, fields, constraints
3. Detects which angles to generate: happy, validation, hierarchy
4. Prints detection summary and waits for your confirmation before generating
5. Performs 4-layer constraint audit (DB → controller → Blade → JS)
6. Generates the module, registers it, and updates index.js

When to use /qa-complex vs /qa-simple:

• Use /qa-simple when you can describe the feature in a sentence
• Use /qa-complex when you have a spec document, screenshot, or acceptance criteria file

/qa-update

Detects what has changed in reference files relative to what existing test modules cover, then updates or extends those modules. Works on both simple (description-based) and complex (reference-file-backed) modules.

Usage:

/qa-update                              ← scan all modules, update changed
/qa-update admin/doctor                 ← update one module
/qa-update --add-missing                ← add missing angles to all modules
/qa-update admin/doctor --add-missing   ← update + add missing angles to one module

What it does:

1. Finds all modules backed by reference files in docs/qa-reference/
2. Reads the reference files and the existing module
3. Detects new CRUD ops, new required fields, new validation rules, or missing angles
4. Prints a change report and waits for your confirmation
5. Appends new steps or angles — never removes or modifies existing steps
6. Runs the updated module headlessly to verify

--add-missing flag: Adds absent test angles to modules that don't have them. For reference-backed modules, angles are derived from the reference files. For simple modules (no reference file), Claude infers runValidation from the form fields in runHappy.

Safety rules (non-negotiable):

• Only appends — never removes or overwrites existing steps
• Only touches tests/e2e/js/modules/ — nothing else
• If a change requires modifying existing step logic, it's flagged as a manual action

/qa-debugger

Debugs a single failing test — finds the root cause, applies the minimum fix, verifies it holds, and checks for regressions.

Usage:

/qa-debugger <test-case-name-or-id>

Examples:

/qa-debugger users-hap-001          ← registry ID
/qa-debugger users happy            ← module + angle
/qa-debugger users                  ← entire module (all angles)
/qa-debugger "Admin can create"     ← title substring

What it does, step by step:

1. Locates the test in the registry or by file search
2. Reproduces the failure in headless mode, captures the full step trace
3. Inspects DB state before and after — detects leftover records from incomplete cleanup
4. Scans network traffic — surfaces 422/401/403/500 responses for server-side failures
5. Classifies the root cause from 9 failure classes (selector miss, nav timeout, DB state, auth, timing…)
6. Auto-scans for missing data-testid — checks every testid the test uses against all Blade templates, proposes the exact Blade edit
7. Fixes the minimum change that resolves the root cause
8. Verifies with 3 consecutive runs — a single pass is not enough
9. Regression-checks related modules using precise scope discovery (by testid, role, and DB table)
10. Confirms flakiness with 12 consecutive runs when the test initially passes

Failure classes it handles:

| Class | Signal | Fix | |---|---|---| | Selector miss | strict mode violation: N elements | Scope locator or add data-testid | | Element missing | locator.waitFor: Timeout | Check data-testid in Blade template | | Nav timeout | page.waitForURL: Timeout | Same-URL redirect → use domcontentloaded + toast wait | | Form submit | Wrong page after submit | Use [data-testid="save-<resource>"] on edit forms | | Validation fail | 422 response / unexpected redirect | Read form HTML for missing required fields | | DB state | Duplicate key / row not found | Broaden dbCleanup() to cover qa.%@test.local and QA Test % | | Auth failure | Redirect to /login, 401/403 | Check QA_<ROLE>_EMAIL / QA_<ROLE>_PASSWORD in .env | | Timing / race | Intermittent passes and fails | Replace networkidle with domcontentloaded + element waitFor |

/qa-healer

Heals the entire broken test suite in one shot. Where /qa-debugger fixes one test at a time, /qa-healer treats the whole suite as a single repair job — triage all failures, group them by root cause, apply batch fixes, verify, and report.

Usage:

/qa-healer                          ← heal all implemented modules
/qa-healer --module=users           ← heal only the users module
/qa-healer --status=all             ← run every registered module
/qa-healer --module=orders --status=broken

What makes it brilliant:

Instead of running /qa-debugger 12 times for 12 broken tests, the healer first classifies every failure, then groups them. If 8 tests fail because a Blade template lost its data-testid in a refactor, the healer adds the attribute to that one template and confirms all 8 pass. One edit. Eight tests healed.

How it works:

Step 1  Environment check — verifies runner, registry, and app reachability
Step 2  Baseline run — all modules headlessly, 3 in parallel (bounded pool)
Step 3  Triage — classify every failure by root cause, group into a triage report
Step 4  Batch repair — fix by class in priority order (DB state → testid → selector → timing)
Step 5  Verify — re-run each repaired module 3 times (1 pass is not enough)
Step 6  Stability check — 10-run flakiness confirmation for "healthy" modules
Step 7  Healing report — full summary with manual-action fallbacks
Step 8  Registry update — marks healed modules as implemented

Example healing report:

╔══════════════════════════════════════════════════════════════════════╗
║  QA HEALER — HEALING REPORT                                           ║
╚══════════════════════════════════════════════════════════════════════╝

Scope        : 8 modules  (--status=implemented)
Baseline     : 5 healthy  /  3 broken

 TRIAGE SUMMARY
  data-testid-missing : 2 modules — fixed (1 Blade file updated)
  selector-miss       : 1 module  — fixed
  Could not auto-fix  : 0

 POST-FIX RESULTS
  ✅ Healed  : products:happy, orders:happy, orders:validation
  ❌ Still broken : none

 MANUAL ACTIONS REQUIRED
  (none)

Safe by design — the healer only touches tests/e2e/js/modules/ and resources/views/. Anything requiring a controller, route, or migration change is flagged as a manual action.

Running tests

# Headed (watch the browser live) — start here the first time
./scripts/qa users happy h

# Headless
./scripts/qa users happy

# All angles for a module
./scripts/qa users all

# All modules
./scripts/qa all x

Quick Reference

| Task | Command | |---|---| | Install framework | npx @kamleshsk/claude-qa | | Update to latest | npx @kamleshsk/claude-qa@latest | | Scaffold QA portal | /qa-setup in Claude Code | | Make scripts executable | chmod +x scripts/qa scripts/qa-register | | Generate test from description | /qa-simple <feature> "<description>" in Claude Code | | Generate test from reference files | /qa-complex <role>/<feature> in Claude Code | | Update module from changed spec | /qa-update in Claude Code | | Debug a failing test | /qa-debugger <module> <angle> in Claude Code | | Heal all broken tests | /qa-healer in Claude Code | | Run a module (headed) | ./scripts/qa <module> happy h | | Run a module (headless) | ./scripts/qa <module> happy | | Run all modules | ./scripts/qa all x | | Open browser portal | <APP_URL>/qa |

Troubleshooting

| Problem | Fix | |---|---| | Commands say "unknown command" | Reload Claude Code after install | | Commands say "unknown command" after update | Reload Claude Code — new command files were installed | | /qa not found after updating | Renamed to /qa-simple in v3.0.0 — update your usage | | Target class [qa.auth] does not exist | Run the middleware verification prompt (Setup Step 2) | | 404 at /qa | Tell Claude: "Add the QA routes to routes/web.php" | | Login fails on portal | Run php artisan config:clear — cached config may have stale values | | ./scripts/qa: Permission denied | chmod +x scripts/qa scripts/qa-register | | Test fails on Login step | QA users not in DB — re-run /qa-setup (Step 5 re-inserts users directly, idempotent) | | Timeout on a locator | Wrong CSS selector — use /qa-debugger or F12 the page and update the module | | playwright not found / Chromium missing | Run npm install && npx playwright install chromium from project root | | Test passes locally but fails in CI | Run /qa-debugger — likely a DB state or missing QA_ env key issue | | /qa-complex says role not found | Add QA_<ROLE>_EMAIL to .env and re-run | | /qa-complex says no reference files | Add files to docs/qa-reference/<role>/<feature>/ folder |

Updating

npx @kamleshsk/claude-qa@latest

Command files are always overwritten with the latest version. Your test modules and runner files are never touched.

Author

Created by Kamlesh Kasambe at infotech.works, under the guidance of Pooja Kolte.

License

MIT