@kamleshsk/claude-qa 1.0.1

package/templates/commands/qa.md

@@ -0,0 +1,231 @@
+---
+description: Generate a new QA test module for a feature
+allowed-tools: Bash, Read, Write
+argument-hint: <feature-name> "<context description>"
+---
+
+You are a QA test generator. Your job is to CREATE a new Playwright test module
+and register it in the framework. Follow every step in order. Do not ask questions — infer from
+the context provided and the reference files you read.
+
+Arguments: $ARGUMENTS
+
+---
+
+## Step 0 — Parse arguments
+
+Split `$ARGUMENTS` into:
+- **feature_name**: the first whitespace-separated token (lowercase, no spaces).
+  This becomes the filename: `tests/e2e/js/modules/<feature_name>.js`
+- **context**: everything after the first token. This describes what the feature does and
+  what flows to test.
+
+If fewer than 2 tokens are provided, print this and STOP:
+
+```
+Usage: /qa <feature-name> "<context description>"
+
+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"
+```
+
+---
+
+## Step 1 — Read the mandatory reference files
+
+Run these two reads in parallel:
+
+Read `tests/e2e/js/modules/index.js`
+Read `tests/e2e/js/register.js`
+
+From `index.js`, find the first module that is already imported (not commented out).
+Read that module file as your structure reference — it is the canonical example for this project.
+
+If no modules exist yet (all lines are commented out), use the structure defined in Step 4 below as the template.
+
+Do not proceed past this step until all files are loaded.
+
+---
+
+## Step 2 — Determine the role and URL prefix for this project
+
+Run these in parallel:
+
+```bash
+grep -E "^QA_[A-Z]+_EMAIL=" .env 2>/dev/null | sed 's/QA_\([A-Z]*\)_EMAIL=.*/\1/' | tr '[:upper:]' '[:lower:]'
+```
+
+This prints every role this project has configured (e.g. `admin`, `manager`, `doctor`). These are the only valid role keys.
+
+Also read `tests/e2e/js/runner.js` — look at the `login()` method to understand how the URL pattern is built per role.
+
+From the feature context in `$ARGUMENTS`, decide which role owns this feature. Use the exact lowercase role key from the grep output above.
+
+The `r.login('<role>')` call uses that key. The step label is `'Login as <Role>'` title-cased.
+
+Use this role consistently throughout the generated file.
+
+---
+
+## Step 3 — Check whether the module already exists
+
+```bash
+test -f "tests/e2e/js/modules/<feature_name>.js" && echo EXISTS || echo MISSING
+```
+
+If EXISTS: print a warning and STOP:
+```
+⚠️  tests/e2e/js/modules/<feature_name>.js already exists.
+    Edit it directly or choose a different feature name.
+```
+
+---
+
+## Step 4 — Generate the module file
+
+Write `tests/e2e/js/modules/<feature_name>.js` following the **exact structure of the reference module you read in Step 1** — match its section order, helper functions, import style, and export shape exactly.
+
+### Section 1 — dbCleanup
+
+Copy the dbCleanup pattern from the reference module. Adapt the table name and test value for this feature.
+
+- Table name: infer from the feature name (e.g. `users` → `users` table)
+- Test value: use a clearly QA-specific string that won't exist in real data (e.g. `'QA Test User'`, `'QA Test Product'`)
+- Use `spawnSync` (not `execSync`) — shell expands `$c` before PHP sees it
+
+### Section 2 — dialog/toast helper
+
+Look at the reference module. If it defines a dialog-wait helper (e.g. `swalWait`, `toastWait`, or similar), copy it unchanged. If the reference module has no such helper, omit this section.
+
+Do not assume SweetAlert or any specific dialog library — use whatever the reference module uses.
+
+### Section 3 — runHappy
+
+Follow the CRUD sequence from the reference module. Adapt for this feature:
+
+1. Login: `r.login('<role from Step 2>')`
+2. Navigate to the listing page for this feature
+3. Open the create form — link or button depending on the app
+4. Fill ALL required fields — **before writing this step, read the actual form HTML and count every field with a `required` attribute, including `<select>` dropdowns** — missing a required select causes silent validation failure and cascading timeouts
+5. Submit the form using **`r.page.locator('[type="submit"]').first().click()`** — never `getByRole('button', { name: '...' })` for form submission; CSS `text-transform` makes accessible-name matching unreliable in Playwright
+6. After submit: if the app redirects to a listing (standard server-side flow), use `r.page.waitForURL('**/listing-url**', { timeout: 8000 })` — if it stays on the same page and shows a toast, use `r.assertToast()`
+7. Verify the record appears in the listing
+8. Edit the record — find the row, open edit form, update a field, submit with `[type="submit"]`, wait for redirect or toast
+9. Delete the record — find the row, trigger delete, confirm using the same confirmation pattern the reference module uses
+
+Name each step descriptively. Do not use `← CHANGE THIS` comments. Infer selectors from the feature name using the same naming convention the reference module demonstrates.
+
+### Section 4 — runValidation
+
+Follow the validation pattern from the reference module:
+- Login → navigate directly to the add form URL (faster than navigating via listing)
+- At least one step: submit without filling required fields → assert an error is visible
+- **Use `r.page.locator('[type="submit"]').first().click()` for the submit — same rule as Section 3**
+- **Check whether the form has `novalidate` attribute** — if yes, the `:invalid` CSS pseudo-class never fires because browser HTML5 validation is bypassed. Server-side validation renders errors in the app's own markup. Read the reference module to see which error class it checks; use that class in the locator (e.g. `:invalid, .is-invalid, .text-red-600`)
+
+### Section 5 — runHierarchy
+
+If this feature has no parent-child relationship, skip:
+```js
+function runHierarchy(r) {
+  r.skip('No hierarchy for <Feature>', '<reason>');
+}
+```
+If it does have hierarchy, follow the hierarchy test pattern from the reference module.
+
+### Export (always at the bottom — copy exact shape from reference module)
+```js
+export const ANGLES = {
+  happy:      runHappy,
+  validation: runValidation,
+  hierarchy:  runHierarchy,
+};
+```
+
+### Import block (always at the top — copy exact imports from reference module, adapt as needed)
+
+---
+
+## Step 5 — Register in index.js
+
+Read the current `tests/e2e/js/modules/index.js` to find the highest existing numeric key.
+Add the new module as the next number.
+
+Edit `tests/e2e/js/modules/index.js`:
+- Add `import * as <feature_name> from './<feature_name>.js';` at the top with the other imports
+- Add `<feature_name>, '<next_number>': <feature_name>,` to `MODULE_MAP`
+- Add `<feature_name>: '<Feature Label>', '<next_number>': '<Feature Label>',` to `MODULE_LABELS`
+
+`<Feature Label>` = title-cased feature name (e.g., `doctors` → `'Doctors'`).
+
+---
+
+## Step 6 — Register test cases using the existing qa-register script
+
+Do NOT construct JSON manually or use the Write tool here. Use the existing `./scripts/qa-register` script — it owns all registry logic (ID generation, file writing, TESTCASES.md rebuild).
+
+**6a — Check if already registered:**
+
+```bash
+grep -q '"<feature_name>"' tests/e2e/registry.json 2>/dev/null && echo "ALREADY_REGISTERED" || echo "NOT_REGISTERED"
+```
+
+If output is `ALREADY_REGISTERED`, print `registry: <feature_name> already registered — skipped` and go to Step 7.
+
+**6b — Register happy and validation angles:**
+
+```bash
+node tests/e2e/js/register.js add <feature_name> happy "<context from $ARGUMENTS>"
+node tests/e2e/js/register.js add <feature_name> validation "Validation — required fields rejected on <Feature Label>"
+```
+
+**6c — Register hierarchy only if the generated runHierarchy has actual test steps:**
+
+Look at the `runHierarchy` function written in Step 4. If it contains only a single `r.skip(...)` call, skip this. If it has real steps, run:
+
+```bash
+node tests/e2e/js/register.js add <feature_name> hierarchy "Hierarchy — <Feature Label> requires a valid parent record"
+```
+
+**6d — Verify:**
+
+```bash
+grep -q '"<feature_name>"' tests/e2e/registry.json && echo "✅ registry.json updated" || echo "❌ FAILED — check scripts/qa-register exists and is correct"
+```
+
+If ❌, read `tests/e2e/js/register.js` to understand what went wrong before retrying.
+
+---
+
+## Step 7 — Print summary
+
+Print exactly:
+
+```
+✅ Created:     tests/e2e/js/modules/<feature_name>.js
+✅ Registered:  tests/e2e/js/modules/index.js  (key: <next_number>)
+✅ Registry:    tests/e2e/registry.json  (<feature_name>-hap-001, <feature_name>-val-001)
+
+─────────────────────────────────────────────────
+ Next steps
+─────────────────────────────────────────────────
+
+ 1. Inspect the target pages (F12 DevTools) and update selectors in:
+      tests/e2e/js/modules/<feature_name>.js
+
+ 2. Seed the QA user if not done yet:
+      php artisan db:seed --class=QAUserSeeder
+
+ 3. Run headed to verify (watch the browser):
+      ./scripts/qa <feature_name> happy h
+
+ 4. Once passing, mark all angles implemented:
+      ./scripts/qa-register status <feature_name>-hap-001 implemented
+      ./scripts/qa-register status <feature_name>-val-001 implemented
+
+ 5. Run all angles:
+      ./scripts/qa <feature_name>
+─────────────────────────────────────────────────
+```

package/templates/docs/qa-setup/module-guide.md

@@ -0,0 +1,398 @@
+# QA Automation — Module Guide
+
+> **Who reads this:** Dev, after `/qa-setup` has been run and the framework files are in place.
+> The framework is generic. This guide covers the project-specific part: writing module files.
+
+---
+
+## What you need to write (one file per feature under test)
+
+After setup, these three things are project-specific and must be written fresh:
+
+| File | What to do |
+|---|---|
+| `tests/e2e/js/modules/index.js` | Register each module (already scaffolded by setup — just uncomment) |
+| `tests/e2e/js/modules/<name>.js` | Write one file per feature (the actual test steps) |
+| `tests/e2e/js/register.js` | Update `MODULES` array + `MODULE_LABELS` at the top |
+
+Everything else (config, runner, report, main, scripts) is already done.
+
+---
+
+## Step 1 — Update register.js
+
+Open `tests/e2e/js/register.js`. At the top, replace the empty arrays:
+
+```js
+const MODULES = ['users', 'roles', 'settings'];  // ← your module names
+
+const MODULE_LABELS = {
+  users:    'Users',
+  roles:    'Roles',
+  settings: 'Settings',
+};
+```
+
+Module names must be lowercase, no spaces. They must match the keys in `modules/index.js`.
+
+---
+
+## Step 2 — Choose the role for your module
+
+Every module logs in as exactly one role. The env var naming convention is:
+
+```
+QA_<DB_ROLE_VALUE>_EMAIL    e.g. QA_ADMIN_EMAIL, QA_DOCTOR_EMAIL, QA_MANAGER_EMAIL
+QA_<DB_ROLE_VALUE>_PASSWORD e.g. QA_ADMIN_PASSWORD, QA_DOCTOR_PASSWORD
+```
+
+Pass the role name to `r.login()` in **lowercase** — it maps to the env var automatically:
+
+| DB role value | `.env` variables | `r.login()` call | Default post-login URL |
+|---|---|---|---|
+| `ADMIN` | `QA_ADMIN_EMAIL` / `QA_ADMIN_PASSWORD` | `r.login()` or `r.login('admin')` | `**/admin**` |
+| `DOCTOR` | `QA_DOCTOR_EMAIL` / `QA_DOCTOR_PASSWORD` | `r.login('doctor')` | `**/dev/**` |
+| `MANAGER` | `QA_MANAGER_EMAIL` / `QA_MANAGER_PASSWORD` | `r.login('manager')` | `**/manager**` |
+| any other | `QA_<ROLE>_EMAIL` / `QA_<ROLE>_PASSWORD` | `r.login('<role>')` | `**/<role>**` |
+
+Override the post-login URL pattern for any role via env (no code change needed):
+```
+QA_ADMIN_URL_PATTERN=**/admin**
+QA_DOCTOR_URL_PATTERN=**/dev/**
+```
+
+The role string you pass to `r.login()` must be **lowercase** and must match the `QA_<ROLE>_` env var prefix (case-insensitive via `.toUpperCase()` in config.js).
+
+---
+
+## Step 3 — Find the selectors for your module
+
+Before writing a module file, inspect the target app's HTML (F12 DevTools).
+
+**For every form in scope, note:**
+
+| What to find | Where to look | Used in code as |
+|---|---|---|
+| Input field `id` | Click field → Inspect → `id="..."` | `r.page.locator('#fieldId')` |
+| Submit button | Inspect the button — prefer `[type="submit"]` over text matching | `r.page.locator('[type="submit"]').first().click()` |
+| Submit button text (non-submit type) | Read the button label | `r.page.getByRole('button', { name: 'Save' })` |
+| Required `<select>` / dropdown | Inspect every field with `required` — includes role, status, category | `r.page.selectOption('[name="role"]', 'admin')` |
+| Table cell CSS class | Inspect a `<td>` | `r.page.locator('td.cell-name:has-text(...)')` |
+| Edit button class | Inspect the edit icon on a row | `row.locator('.edit-btn-class')` |
+| Delete button class | Inspect the delete icon | `row.locator('.delete-btn-class')` |
+| Drawer or full-page form? | Does clicking Add open a side panel or navigate? | Drawer: `locator('#drawerId')`. Full-page: `waitForURL('**/create**')` |
+| Flash/toast format | Inspect the success banner after a save — is it `.alert`, `id="flash-*"`, or a JS library? | Use `r.assertToast()` or `waitForURL()` — see Common problems |
+| AJAX-cascaded dropdowns | Does selecting a parent trigger a spinner? | Add `await sleep(1200)` after each cascaded `selectOption()` |
+
+---
+
+## Step 4 — Write the module file
+
+Copy this template to `tests/e2e/js/modules/<yourmodule>.js`. Update every section marked with a `// ← UPDATE:` comment. Read the rules below the template before you start — they prevent the most common failure modes.
+
+```js
+// tests/e2e/js/modules/<feature>.js     // ← UPDATE: rename to your feature
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const TEST_VAL   = 'QA Test Record';          // ← UPDATE: clearly QA-specific test name
+const TEST_EMAIL = 'qa-test@example.local';   // ← UPDATE: only if feature uses email
+
+// ── DB cleanup ────────────────────────────────────────────────────────────────
+// Use spawnSync (not execSync) so PHP's $variable names survive intact.
+function dbCleanup() {
+  spawnSync('php', ['artisan', 'tinker', '--execute',
+    `DB::table('records')->where('name', '${TEST_VAL}')->delete();` // ← UPDATE: table + field
+  ], { cwd: ROOT, stdio: 'inherit' });
+}
+
+// ── Optional: dialog/toast helper ────────────────────────────────────────────
+// Only include this if the app uses SweetAlert2. Delete the whole block if not.
+// async function swalWait(page, timeout = 8000) {
+//   try {
+//     await page.locator('.swal2-popup').waitFor({ state: 'visible', timeout: 5000 });
+//     await page.locator('.swal2-popup').waitFor({ state: 'hidden', timeout });
+//   } catch { /* ignore */ }
+// }
+
+// ── Happy path ────────────────────────────────────────────────────────────────
+async function runHappy(r) {
+  dbCleanup();
+  const base = r.config.base_url;
+
+  // Login — r.login() = admin, r.login('manager') = manager, etc.
+  await r.step('Login as Admin', () => r.login('admin')); // ← UPDATE: role
+
+  await r.step('Navigate to listing', async () => {       // ← UPDATE: label + URL
+    await r.page.goto(`${base}/admin/records`);            // ← UPDATE: listing URL
+    await r.page.waitForLoadState('networkidle');
+  });
+
+  // ── Open the create form ───────────────────────────────────────────────────
+  // Use getByRole('link', ...) if Add is an <a> tag, getByRole('button', ...) if a <button>.
+  await r.step('Open create form', async () => {           // ← UPDATE
+    await r.page.getByRole('link', { name: /add record/i }).click(); // ← UPDATE
+    await r.page.waitForLoadState('networkidle');
+  });
+
+  // ── Fill and submit ────────────────────────────────────────────────────────
+  // RULES:
+  //   1. Use locator('[type="submit"]').first().click() for ALL submit buttons — never
+  //      getByRole('button', { name: '...' }) for submit actions. CSS text-transform
+  //      (e.g. Tailwind `uppercase`) makes accessible-name matching unreliable.
+  //   2. Fill EVERY required field in the form — text inputs AND <select> dropdowns.
+  //      Check the form HTML for `required` attributes before writing this step.
+  //   3. After submit:
+  //      - If the app redirects to a listing page (standard server-side): use waitForURL.
+  //      - If the app shows an inline toast without navigating: use r.assertToast().
+  await r.step('Fill and submit new record', async () => { // ← UPDATE: label
+    await r.page.fill("[name='name']", TEST_VAL);           // ← UPDATE: fields
+    // await r.page.selectOption("[name='status']", 'active'); // ← ADD: every required <select>
+    await r.page.locator('[type="submit"]').first().click();
+    await r.page.waitForURL(`**/admin/records**`, { timeout: 8000 }); // ← UPDATE: listing URL pattern
+    // — OR if no redirect: await r.assertToast();
+  });
+
+  await r.step('Verify record appears in listing', async () => {
+    await r.page.goto(`${base}/admin/records`);             // ← UPDATE
+    await r.page.waitForLoadState('networkidle');
+    await r.assertRowExists(TEST_VAL);
+  });
+
+  // ── Edit ───────────────────────────────────────────────────────────────────
+  await r.step('Open edit form', async () => {              // ← UPDATE
+    const row = r.page.locator(`table tr:has-text('${TEST_VAL}')`).first();
+    await row.getByRole('link', { name: /edit/i }).click(); // ← UPDATE: edit trigger
+    await r.page.waitForLoadState('networkidle');
+  });
+
+  await r.step('Update and save', async () => {             // ← UPDATE
+    await r.page.fill("[name='name']", TEST_VAL + ' Edited'); // ← UPDATE: field + value
+    await r.page.locator('[type="submit"]').first().click();
+    await r.page.waitForURL(`**/admin/records**`, { timeout: 8000 }); // ← UPDATE
+    // — OR if no redirect: await r.assertToast();
+  });
+
+  await r.step('Verify updated record in listing', async () => {
+    await r.page.goto(`${base}/admin/records`);             // ← UPDATE
+    await r.page.waitForLoadState('networkidle');
+    await r.assertRowExists(TEST_VAL + ' Edited');
+  });
+
+  // ── Delete ─────────────────────────────────────────────────────────────────
+  // Choose ONE of the delete patterns based on what the app uses:
+  await r.step('Delete record', async () => {               // ← UPDATE
+    const row = r.page.locator(`table tr:has-text('${TEST_VAL} Edited')`).first();
+
+    // Pattern A — native browser confirm dialog (onsubmit="return confirm(...)")
+    r.page.once('dialog', dialog => dialog.accept());
+    await row.getByRole('button', { name: /delete/i }).click();
+
+    // Pattern B — SweetAlert2 confirm button (if the app uses swal2)
+    // await row.getByRole('button', { name: /delete/i }).click();
+    // await r.page.locator('.swal2-confirm').waitFor({ state: 'visible', timeout: 5000 });
+    // await r.page.locator('.swal2-confirm').click();
+    // await swalWait(r.page);
+
+    await r.assertRowGone(TEST_VAL + ' Edited');
+  });
+
+  dbCleanup();
+}
+
+// ── Validation ────────────────────────────────────────────────────────────────
+// RULES:
+//   1. Use locator('[type="submit"]').first().click() — same as runHappy.
+//   2. Forms with `novalidate` skip browser HTML5 validation — the :invalid pseudo-class
+//      NEVER fires. Server-side errors render as the app's own markup (e.g. .text-red-600
+//      in Laravel Breeze). Inspect the form after a failed submit to find the right class.
+//   3. Add the app's error class to the locator: ':invalid, .is-invalid, .text-red-600'
+async function runValidation(r) {
+  const base = r.config.base_url;
+
+  await r.step('Login and navigate to create form', async () => { // ← UPDATE
+    await r.login('admin');                                         // ← UPDATE: match runHappy role
+    await r.page.goto(`${base}/admin/records/create`);              // ← UPDATE: direct create URL
+    await r.page.waitForLoadState('networkidle');
+  });
+
+  await r.step('Submit blank form — required fields rejected', async () => {
+    await r.page.locator('[type="submit"]').first().click();
+    // ← UPDATE: add the app's error CSS class (inspect after failed submit)
+    const err = r.page.locator(':invalid, .is-invalid, .text-red-600').first();
+    await err.waitFor({ state: 'visible', timeout: 6000 });
+  });
+}
+
+// ── Hierarchy ─────────────────────────────────────────────────────────────────
+function runHierarchy(r) {
+  r.skip('No hierarchy for <Feature>', '<reason>'); // ← UPDATE or add real steps
+}
+
+// ── Export — do not change ────────────────────────────────────────────────────
+export const ANGLES = {
+  happy:      runHappy,
+  validation: runValidation,
+  hierarchy:  runHierarchy,
+};
+```
+
+**Three rules that must be followed for every module — no exceptions:**
+
+| Rule | Wrong | Right |
+|---|---|---|
+| Submit buttons | `getByRole('button', { name: 'Save' }).click()` | `locator('[type="submit"]').first().click()` |
+| After redirect-based save | `r.assertToast()` | `r.page.waitForURL('**/listing**', { timeout: 8000 })` |
+| Validation errors (novalidate) | `locator(':invalid')` | `locator(':invalid, .is-invalid, .text-red-600')` (add your app's class) |
+
+And one checklist item before writing the fill step: **open the form in DevTools and count every field with `required` attribute — fill all of them, including `<select>` dropdowns.** A missing required select silently fails validation and all downstream steps fail with timeouts.
+
+---
+
+## Step 5 — Register the module in index.js
+
+Open `tests/e2e/js/modules/index.js` and uncomment (or add) your module:
+
+```js
+import * as users from './users.js';   // ← add this line
+
+export const MODULE_MAP = {
+  users, '1': users,                   // ← add this line
+};
+
+export const MODULE_LABELS = {
+  users: 'Users', '1': 'Users',        // ← add this line
+};
+```
+
+Numeric keys (`'1'`, `'2'`, etc.) are shorthand — the user can type `1` instead of `users` in the picker.
+
+---
+
+## Step 6 — Register test cases
+
+```bash
+./scripts/qa-register add users happy "Admin can create a user"
+./scripts/qa-register add users happy "Admin can edit a user name"
+./scripts/qa-register add users happy "Admin can delete a user"
+./scripts/qa-register add users validation "Blank name is rejected"
+```
+
+IDs auto-assign: `users-hap-001`, `users-hap-002`, etc.
+
+---
+
+## Step 7 — Run it
+
+```bash
+# Headed browser (watch what happens — always start here)
+./scripts/qa users happy h
+
+# Once it passes, confirm headless works
+./scripts/qa users happy x
+```
+
+If a step fails, check the artifact folder:
+
+```bash
+ls tests/e2e/artifacts/
+cat tests/e2e/artifacts/<timestamp>/users/happy/report.md
+open tests/e2e/artifacts/<timestamp>/users/happy/1-fail.png
+```
+
+---
+
+## Selector quick reference
+
+```js
+// Input by id
+await r.page.locator('#fieldId').fill('value');
+
+// Select dropdown by label text
+await r.page.locator('#selectId').selectOption({ label: 'Option Name' });
+
+// Select dropdown by value attribute
+await r.page.locator('#selectId').selectOption({ value: 'VALUE' });
+
+// Submit button (preferred — works regardless of button text or CSS text-transform)
+await r.page.locator('[type="submit"]').first().click();
+
+// Button by visible text (only when NOT a submit button, e.g. drawer close, step nav)
+await r.page.getByRole('button', { name: 'Save' }).click();
+
+// Table row containing a cell with specific text
+const row = r.page.locator('tr', {
+  has: r.page.locator("td.cell-class:has-text('My Record')")
+}).first();
+
+// AJAX cascade — always wait after selecting a parent dropdown
+await r.page.locator('#countrySelect').selectOption({ label: 'United States' });
+await sleep(1200);
+await r.page.locator('#stateSelect').selectOption({ label: 'California' });
+
+// Full-page form navigation
+await r.page.waitForURL('**/products/create**', { timeout: 8000 });
+```
+
+---
+
+## Why `spawnSync` not `execSync` for DB cleanup
+
+`execSync` runs through the shell, which expands `$c` as a shell variable (empty string) before PHP sees it, causing a PHP parse error. `spawnSync` passes the string directly to the `php` process with no shell in between.
+
+```js
+// ✅ Correct
+spawnSync('php', ['-r', `$c=new PDO(...); ...`], { stdio: 'pipe' });
+
+// ❌ Wrong — shell expands $c before PHP sees it
+execSync(`php -r "$c=new PDO(...);"`)
+```
+
+---
+
+## Common problems
+
+### `QA credentials not set`
+Add `QA_EMAIL` + `QA_PASSWORD` to `.env`. Or add `SUPER_ADMIN_EMAIL` + `SUPER_ADMIN_PASSWORD` as fallback.
+
+### `Server not responding on http://127.0.0.1:8000`
+Start the app server first. For Laravel: `php artisan serve --port=8000`.
+Or override the URL: `./scripts/qa users --base-url=http://127.0.0.1:8001`
+
+### Login step passes but the page after login is wrong
+Check the `waitForURL` pattern in `runner.js` `login()`. The default is `**/admin**`. If your app goes to `/dashboard` after login, change this.
+
+### Screenshot shows login page instead of the expected page
+The `login()` step silently failed (wrong credentials or wrong URL). Check `.env` credentials and the `login()` selectors in runner.js.
+
+### Test passes locally but fails in CI
+1. **Timing** — CI machines are slower. Increase `sleep()` durations or use `waitFor()`.
+2. **DB access** — `dbCleanup()` can't reach the CI database. Check DB host/port config.
+3. **Chromium missing** — add `npx playwright install chromium --with-deps` to the CI job.
+
+### Login button times out — `getByRole('button', ...)` never finds it
+Apps that use CSS `text-transform: uppercase` on the login button (e.g. Tailwind's `uppercase` class) expose a Playwright accessible-name bug: the browser accessibility tree returns the visual all-caps text (`"LOG IN"`), and the matching behaves unexpectedly for certain Playwright/Chromium combinations. The `login()` method in `runner.js` has been updated to use `locator('[type="submit"]').first()` instead. If you copied an older version, update `runner.js` line 87 to match.
+
+### Form submits but stays on the create page — validation errors instead of success
+A required field was not filled. The most common culprit is a `<select>` for role, status, category, or similar. Open the form in DevTools, look for `required` attributes, and add a `selectOption()` call for every select field before clicking submit. Submitting with a missing required select returns a validation error — the redirect to the listing never happens, and all subsequent steps fail.
+
+### Validation step — `:invalid` selector never fires
+Forms with the `novalidate` attribute skip browser HTML5 validation. The `:invalid` CSS pseudo-class is never set. Server-side validation errors render as framework-specific markup (e.g. Laravel Breeze renders `<p class="text-red-600">`). Update the validation step selector to match what the app actually shows:
+```js
+// Instead of just :invalid, .is-invalid — also include the app's error class
+const invalid = r.page.locator(':invalid, .is-invalid, .text-red-600').first();
+```
+Inspect the error output in the browser after a failed form submit to find the correct class.
+
+### `assertToast` times out after create / update / delete
+The app may use a custom flash message format not covered by the built-in selectors. Two options:
+1. **If the app uses `id="flash-*"` naming** — already handled; `runner.js` `assertToast()` includes `[id^='flash-']`.
+2. **If the app uses redirects with no visible toast** — replace `r.assertToast()` with a URL check:
+   ```js
+   await r.page.locator('[type="submit"]').first().click();
+   await r.page.waitForURL('**/your-listing-url**', { timeout: 8000 });
+   ```
+   This is more reliable for standard server-redirect flows (Laravel `redirect()->with('success', ...)`).
+3. **If using a JS toast library not in the list** — add your selector to `assertToast()` in `runner.js`.