qa

name	qa
description	Run the E2E QA test suite against the live application using Playwright MCP and nREPL. Use when testing the app end-to-end.
argument-hint	[script-number | range | comma-list | 'all' | 'next' | 'status']

E2E QA Runner

Execute the structured QA test scripts in qa/scripts/ against the live application.

Current Progress

!cat qa/scripts/progress.md

How It Works

The QA suite is split into 20 individually-executable test scripts in qa/scripts/. Each script:

• Targets a specific feature area (e.g., "Owner Locations CRUD", "POS Split Payments")
• Contains step-by-step TEST items tagged as READ, WRITE, NAVIGATE, or GUARD
• Requires mandatory SCREENSHOT proof at state transitions
• Tracks pass/fail per item

Invocation

• /qa or /qa next — Run the next incomplete script (first — status in progress.md)
• /qa all — Run all scripts from the beginning (Session 1 through Session 5)
• /qa 03 or /qa 3 — Run a specific script by number (e.g., 03-owner-locations.md)
• /qa status — Show current progress.md without running anything
• /qa 03-08 — Run a range of scripts sequentially
• /qa 00,03,05,21 — Run a comma-separated list of specific scripts in the order given. Whitespace around commas is ignored.
• /qa 00,03-05,21-23 — Mix ranges and single numbers in one invocation. Ranges are expanded left-to-right, duplicates are de-duped, and order of first appearance is preserved.

Execution Protocol

Before running any script, read and internalize the rules in qa/scripts/EXECUTION-RULES.md. These are non-negotiable:

1. Execute EVERY test item in order. Do NOT skip. Do NOT reorder.
2. Do NOT move to the next TEST until the current TEST is fully verified.
3. "Page loads" is NOT "feature works." If a test says WRITE, perform the write.
4. Take a SCREENSHOT at every SCREENSHOT marker. These are mandatory proof-of-work.
5. If a test FAILS, log the failure and continue. Do NOT silently skip. Do NOT fix bugs mid-QA.
6. When a script completes, update qa/scripts/progress.md with pass/fail/skip counts.
7. If you cannot finish a script, STOP at the nearest --- break. Update progress.md as PARTIAL. Do NOT rush remaining items to "finish."

Steps

1. Determine which script(s) to run

Parse $ARGUMENTS:

• next or empty: Read qa/scripts/progress.md, find the first row with Status —, that's the script to run.
• all: Start from script 00.
• A number (e.g., 3, 03, 15): Run that specific script. Zero-pad to 2 digits to find the file.
• A range (e.g., 03-08): Run scripts 03 through 08 sequentially.
• A comma-separated list (e.g., 00,03,05,21): Split on ,, trim whitespace around each token, zero-pad each to 2 digits, and run them in the order given. Empty tokens are ignored.
• A mixed list with ranges (e.g., 00,03-05,21-23): Each comma-separated token is parsed independently — a bare number becomes a single script, a NN-MM token expands to the contiguous range. Concatenate the results left-to-right, de-duplicate while preserving first appearance, and run in that final order.
• status: Print progress.md and stop.

When the parsed input resolves to multiple scripts (range, comma list, or mixed), follow the same "Continue or stop" rules from step 5 — report progress between scripts and stop early if any individual script takes a long time. Do NOT rush later scripts in the list to finish the batch.

2. Prerequisites check (Script 00)

If running script 00, or if this is the first script in a session:

1. Connect to nREPL via /nrepl-connect
2. Check if the system is running: (resolve 'user/app) and whether it's bound.
3. If not running, start it from the REPL:
   • (require '[cjbarre.grain-todo-list :as app])
   • (def app (app/start))
   • The app serves on http://localhost:8080/.
4. Seed any required test data (create + verify accounts and todos via tools/invoke-command!; see /verify-ui for the sign-up + verify-email flow).
5. Verify seed output / projections show the expected counts.

To restart cleanly, stop and start the Integrant system: (app/stop app) then (def app (app/start)).

If the system is already running and seeded (script 00 shows completed in progress.md), skip to step 3.

3. Execute the script

1. Read the script file: qa/scripts/{NN}-{name}.md
2. Read the execution rules: qa/scripts/EXECUTION-RULES.md
3. Log in as the role specified in the script header
4. Execute each TEST item sequentially:
   • For NAVIGATE: Use browser_navigate or browser_click, verify URL/page title
   • For READ: Use browser_snapshot and verify expected elements/text
   • For WRITE: Perform the action (fill form, click button), then verify the result
   • For GUARD: Attempt the blocked action, verify error/redirect
   • At SCREENSHOT markers: Use browser_take_screenshot with the specified filename
5. Track results: count passes, failures, and skips

4. Record results

After completing the script, append the results section to the script file:

---
## Results
**Date**: [today's date]
**Status**: PASS | PARTIAL | FAIL
**Pass**: X / Y
**Failures**:
- TEST X.Y: [description]
**Notes**: [anything relevant]

Then update qa/scripts/progress.md — change the row's Status, Pass, Fail, Skip, and Date columns.

5. Continue or stop

• If running a range or all: proceed to the next script.
• If the current script took a long time: stop and report. Do NOT rush the next script.
• Always prefer quality over quantity. One thoroughly-tested script is worth more than three skimmed scripts.

Key Tools

• Playwright MCP: browser_navigate, browser_snapshot, browser_click, browser_type, browser_fill_form, browser_select_option, browser_take_screenshot, browser_press_key, browser_wait_for
• nREPL MCP: mcp__nrepl__eval_form for data verification and seeding
• Bash: curl for webhook testing. For a clean restart, stop/start the system from the REPL: (app/stop app) then (def app (app/start))

Session Boundaries

Scripts are grouped into 5 sessions (see qa/scripts/RUN-ORDER.md). Each session is designed for one conversation. If running all, respect these boundaries — when you finish a session's scripts, report progress and suggest continuing in a new conversation to avoid context degradation.