@kamleshsk/claude-qa

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

What it does

@kamleshsk/claude-qa gives Claude Code four powerful slash commands that turn test creation, 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 | Generate a complete test module for any feature in seconds | | /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

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

npx @kamleshsk/claude-qa

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.md            ← /qa           generate a test module for any feature
│   ├── 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-setup/
    └── module-guide.md  ← authoring guide for test modules

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 — Create QA users

Create database/seeders/QAUserSeeder.php if it doesn't exist. Discover the real auth model,
password field, and roles from the database — do not hardcode anything. Create one QA user per
role using QA_<ROLE>_EMAIL and QA_<ROLE>_PASSWORD from .env. Run php artisan db:seed
--class=QAUserSeeder, then append any missing role credential keys to .env without overwriting
existing ones. Print the final QA_* section of .env and the inserted rows to confirm they match.

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

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 <feature-name> "<what this feature does>"

Examples:

/qa users "Admin can create, edit, and delete user accounts"
/qa products "Admin can add products with price, category, and image"
/qa 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 |

/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 a test module | /qa <feature> "<description>" 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 | | 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 the seeder prompt (Setup Step 4) | | Timeout on a locator | Wrong CSS selector — use /qa-debugger or F12 the page and update the module | | Class QAUserSeeder not found | Run composer dump-autoload then retry | | Test passes locally but fails in CI | Run /qa-debugger — likely a DB state or missing QA_ env key issue |

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