@kamleshsk/claude-qa 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,276 @@
+# @kamleshsk/claude-qa
+
+> One command to install a complete Claude Code QA automation framework into any project.
+
+[![npm](https://img.shields.io/npm/v/@kamleshsk/claude-qa)](https://www.npmjs.com/package/@kamleshsk/claude-qa)
+[![license](https://img.shields.io/npm/l/@kamleshsk/claude-qa)](./LICENSE)
+
+---
+
+## What it does
+
+Drops a full Playwright-based QA framework powered by Claude Code into any project in seconds — commands, skills, and docs included. Then automatically installs all Node dependencies so you can start writing tests immediately.
+
+```
+.claude/
+├── commands/
+│   ├── qa.md          ← /qa        generate a test module for any feature
+│   └── qa-setup.md    ← /qa-setup  scaffold the entire framework
+└── skills/
+    └── playwright-cli/
+        ├── SKILL.md
+        └── references/   (10 reference files)
+
+docs/
+└── qa-setup/
+    └── module-guide.md
+```
+
+After copying the files, the installer automatically:
+- Adds `"type": "module"`, `playwright`, `dotenv`, and QA scripts to your `package.json`
+- Runs `npm install`
+- Runs `npx playwright install chromium`
+
+No manual Node setup needed.
+
+---
+
+## Install
+
+```bash
+npx @kamleshsk/claude-qa
+```
+
+Run this from your **project root** — the folder that contains `composer.json` (or your app root). It creates all folders if they don't exist and skips files that already exist, so it is safe to re-run.
+
+---
+
+## Full Setup — Step by Step
+
+### Step 1 — Run the installer
+
+```bash
+cd /your/project
+npx @kamleshsk/claude-qa
+```
+
+You will see:
+
+```
+🚀  Installing @kamleshsk/claude-qa into:
+    /your/project
+
+📁  Copying skills and commands...
+
+  ✅ copied  .claude/commands/qa.md
+  ✅ copied  .claude/commands/qa-setup.md
+  ✅ copied  .claude/skills/playwright-cli/SKILL.md
+  ✅ copied  .claude/skills/playwright-cli/references/...
+  ✅ copied  docs/qa-setup/module-guide.md
+
+⚙️   Setting up Node dependencies...
+
+  ✅ updated  package.json
+
+📦  Running npm install...
+
+🎭  Installing Playwright Chromium...
+
+─────────────────────────────────────────────────────────
+ ✅  All done!
+
+     Open Claude Code in this project and
+     run /qa-setup to scaffold the QA framework.
+─────────────────────────────────────────────────────────
+```
+
+---
+
+### Step 2 — Add QA credentials to `.env`
+
+```dotenv
+# QA Portal login
+QA_EMAIL=qa@yourproject.local
+QA_PASSWORD=Password@1
+```
+
+The browser portal discovers roles from your database automatically and lets you enter per-role credentials from the UI when you run a test.
+
+---
+
+### Step 3 — 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
+```
+
+Claude scaffolds the entire framework — runner, config, portal controllers, views, routes, scripts, and registry. When it finishes, make the scripts executable:
+
+```bash
+chmod +x scripts/qa scripts/qa-register
+```
+
+---
+
+### Step 4 — Verify middleware, run migrations, seed QA users
+
+Paste these two prompts into Claude Code one at a time:
+
+**Middleware check:**
+```
+Verify and fix the qa.auth middleware alias registration for this Laravel version.
+```
+
+**Database:**
+```
+Check pending migrations and run them. Then create and run QAUserSeeder —
+inspect the auth model and role structure first before writing anything.
+```
+
+---
+
+### Step 5 — Verify the portal
+
+Start your server and open `<APP_URL>/qa` in the browser.
+Log in with `QA_EMAIL` / `QA_PASSWORD` from your `.env`.
+The dashboard should load.
+
+---
+
+### Step 6 — Generate your first test module
+
+```
+/qa users "Admin can create, edit, and delete user accounts"
+```
+
+Claude creates `tests/e2e/js/modules/users.js` and registers it automatically.
+Update the CSS selectors in that file using F12 DevTools on your app.
+
+---
+
+### Step 7 — Run it
+
+```bash
+# Watch the browser (first time — always start here)
+./scripts/qa users happy h
+
+# Headless
+./scripts/qa users happy
+
+# All modules
+./scripts/qa all
+```
+
+---
+
+## Quick Reference
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  SETUP (once per project)                                    ║
+╠══════════════════════════════════════════════════════════════╣
+║  1. npx @kamleshsk/claude-qa   ← installs skills + deps     ║
+║  2. Add QA_EMAIL / QA_PASSWORD to .env                       ║
+║  3. Reload Claude Code → /qa-setup                           ║
+║  4. chmod +x scripts/qa scripts/qa-register                  ║
+║  5. Middleware + migrations + QAUserSeeder (2 Claude prompts)║
+╠══════════════════════════════════════════════════════════════╣
+║  ADD A TEST MODULE                                           ║
+╠══════════════════════════════════════════════════════════════╣
+║  /qa <feature> "<description>"  →  update selectors          ║
+╠══════════════════════════════════════════════════════════════╣
+║  RUN TESTS                                                   ║
+╠══════════════════════════════════════════════════════════════╣
+║  ./scripts/qa <module> happy h    headed (watch browser)     ║
+║  ./scripts/qa <module> happy      headless                   ║
+║  ./scripts/qa all                 all modules                ║
+╠══════════════════════════════════════════════════════════════╣
+║  BROWSER PORTAL                                              ║
+╠══════════════════════════════════════════════════════════════╣
+║  Visit <APP_URL>/qa → login → pick module → Run              ║
+║  Roles auto-discovered from DB, credentials entered in UI    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## What `/qa-setup` creates
+
+```
+tests/e2e/js/
+├── config.js          reads .env credentials
+├── runner.js          step engine, login, assertions
+├── main.js            CLI entry point
+├── report.js          pass/fail reports + screenshots
+├── register.js        test registry tool
+└── modules/
+    └── index.js       module map
+
+tests/e2e/registry.json
+
+scripts/
+├── qa                 terminal shortcut
+└── qa-register        registry shortcut
+
+app/Http/Controllers/QA/   (3 controllers)
+resources/views/qa/        (portal UI)
+routes/web.php             (QA routes appended)
+app/Http/Middleware/EnsureQAAuth.php
+```
+
+---
+
+## What `/qa` generates
+
+For each feature you describe, Claude writes a complete test module with:
+
+- **Happy path** — create, edit, delete with real browser interactions
+- **Validation** — required fields rejected, handles both browser and server-side validation
+- **Hierarchy** — parent-child relationship tests (or skipped if not applicable)
+
+The module is auto-registered in `index.js` and `registry.json`.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `/qa-setup` says "unknown command" | Reload Claude Code after install (Step 3) |
+| `Target class [qa.auth] does not exist` | Run the middleware verification prompt (Step 4) |
+| `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 old values |
+| `./scripts/qa: Permission denied` | `chmod +x scripts/qa scripts/qa-register` |
+| Test fails on Login step | QA users not in DB — re-run `QAUserSeeder` (Step 4) |
+| Timeout on a locator | Wrong CSS selector — F12 the page and update the module file |
+
+---
+
+## Updating
+
+When a new version is released, re-run in your project root:
+
+```bash
+npx @kamleshsk/claude-qa@latest
+```
+
+Files that already exist are skipped. Only new or updated files are added.
+
+---
+
+## Author
+
+Created by **Kamlesh Kasambe** at [infotech.works](https://infotech.works), under the guidance of **Pooja Kolte**.
+
+---
+
+## License
+
+MIT

package/bin/install.js

@@ -1,33 +1,33 @@
 #!/usr/bin/env node
 
-const fs   = require('fs');
-const path = require('path');
+const fs             = require('fs');
+const path           = require('path');
+const { spawnSync }  = require('child_process');
 
 const SRC  = path.join(__dirname, '..', 'templates');
 const DEST = process.cwd();
 
+// ── file helpers ──────────────────────────────────────────────────────────────
+
 function copyFile(srcRel, destRel) {
   const src  = path.join(SRC, srcRel);
   const dest = path.join(DEST, destRel);
-
   fs.mkdirSync(path.dirname(dest), { recursive: true });
-
   if (fs.existsSync(dest)) {
     console.log(`  ⏭  skip   ${destRel}  (already exists)`);
     return;
   }
-
   fs.copyFileSync(src, dest);
   console.log(`  ✅ copied  ${destRel}`);
 }
 
 function copyDir(srcRel, destRel) {
-  const srcDir = path.join(SRC, srcRel);
+  const srcDir  = path.join(SRC, srcRel);
   const entries = fs.readdirSync(srcDir);
   for (const entry of entries) {
     const entrySrcRel  = path.join(srcRel, entry);
     const entryDestRel = path.join(destRel, entry);
-    const fullSrc = path.join(SRC, entrySrcRel);
+    const fullSrc      = path.join(SRC, entrySrcRel);
     if (fs.statSync(fullSrc).isDirectory()) {
       copyDir(entrySrcRel, entryDestRel);
     } else {
@@ -36,21 +36,89 @@ function copyDir(srcRel, destRel) {
   }
 }
 
+// ── node dependency setup ────────────────────────────────────────────────────
+
+function setupNodeDeps() {
+  const pkgPath = path.join(DEST, 'package.json');
+
+  let pkg = {};
+  if (fs.existsSync(pkgPath)) {
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch {}
+  }
+
+  let changed = false;
+
+  if (pkg.type !== 'module') {
+    pkg.type = 'module';
+    changed = true;
+  }
+
+  pkg.devDependencies = pkg.devDependencies || {};
+  if (!pkg.devDependencies.playwright) {
+    pkg.devDependencies.playwright = 'latest';
+    changed = true;
+  }
+  if (!pkg.devDependencies.dotenv) {
+    pkg.devDependencies.dotenv = 'latest';
+    changed = true;
+  }
+
+  pkg.scripts = pkg.scripts || {};
+  if (!pkg.scripts.qa) {
+    pkg.scripts.qa = 'node tests/e2e/js/main.js';
+    changed = true;
+  }
+  if (!pkg.scripts['qa:register']) {
+    pkg.scripts['qa:register'] = 'node tests/e2e/js/register.js';
+    changed = true;
+  }
+
+  if (changed) {
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    console.log('  ✅ updated  package.json');
+  } else {
+    console.log('  ⏭  skip   package.json  (already configured)');
+  }
+
+  console.log('\n📦  Running npm install...\n');
+  const install = spawnSync('npm', ['install'], {
+    cwd: DEST, stdio: 'inherit',
+  });
+  if (install.status !== 0) {
+    console.log('  ⚠️  npm install failed — run manually: npm install');
+    return;
+  }
+
+  console.log('\n🎭  Installing Playwright Chromium...\n');
+  const pw = spawnSync('npx', ['playwright', 'install', 'chromium'], {
+    cwd: DEST, stdio: 'inherit',
+  });
+  if (pw.status !== 0) {
+    console.log('  ⚠️  Playwright install failed — run manually: npx playwright install chromium');
+  }
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+
 console.log('\n🚀  Installing @kamleshsk/claude-qa into:');
 console.log('    ' + DEST + '\n');
 
-// Claude commands
+console.log('📁  Copying skills and commands...\n');
+
 copyFile('commands/qa.md',       '.claude/commands/qa.md');
 copyFile('commands/qa-setup.md', '.claude/commands/qa-setup.md');
 
-// Playwright skill (SKILL.md + all references)
 copyFile('skills/playwright-cli/SKILL.md', '.claude/skills/playwright-cli/SKILL.md');
 copyDir( 'skills/playwright-cli/references', '.claude/skills/playwright-cli/references');
 
-// Docs
 copyFile('docs/qa-setup/module-guide.md', 'docs/qa-setup/module-guide.md');
 
-console.log('\n─────────────────────────────────────────────');
-console.log(' Done! Open Claude Code in this project and');
-console.log(' run /qa-setup to scaffold the QA framework.');
-console.log('─────────────────────────────────────────────\n');
+console.log('\n⚙️   Setting up Node dependencies...\n');
+setupNodeDeps();
+
+console.log('\n─────────────────────────────────────────────────────────');
+console.log(' ✅  All done!');
+console.log('');
+console.log('     Open Claude Code in this project and');
+console.log('     run /qa-setup to scaffold the QA framework.');
+console.log('─────────────────────────────────────────────────────────\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kamleshsk/claude-qa",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Claude Code QA skills and commands installer — works with any project",
   "bin": {
     "claude-qa": "bin/install.js"