cursor-qa

name	cursor-qa
description	Delegate QA and fast browser-harness E2E testing to Cursor Composer 2.5 Fast through the local cursor-agent tmux wrapper. Use when Codex should write a test brief, ask Cursor to exercise a UI or browser workflow, and receive a structured QA report with evidence, failures, reproduction notes, and retest status.

Cursor QA

Use cursor-agent to send fast QA work to Cursor Composer 2.5 Fast while Codex keeps implementation context focused.

Outcome

Goal: Turn a development change into a focused QA brief, run it through Cursor with browser-harness, and bring back a report Codex can act on.

Success means:

• Codex gives Cursor a bounded test brief with target URL, flows, expected behavior, and report fields.
• Cursor uses browser-harness for browser interaction, visible verification, screenshots or page state, and reproduction notes.
• Cursor returns a QA report with verdict, coverage, failures, evidence, and retest instructions.

Stop when: Cursor returns a report that lets Codex fix a concrete issue, request a retest, or record a passing QA result.

Standard Loop

Start a QA run:

cursor-agent start "<qa brief>" --dir /path/to/repo --force
cursor-agent await-turn <jobId>
cursor-agent capture <jobId> 220 --clean
cursor-agent status <jobId>

When Codex runs these commands, run them as approved/escalated shell commands. Cursor Agent reads macOS Keychain auth, and browser-harness needs localhost CDP access. A sandboxed Codex command can make agent status fail with SecItemCopyMatching and can make browser-harness mis-detect Chrome.

For browser-harness jobs, omit --sandbox or pass --sandbox disabled. cursor-agent automatically chooses Cursor Agent sandbox disabled for browser-harness QA when no explicit sandbox is provided. If a caller passes --sandbox enabled with browser-harness, the wrapper fails fast with a clear error instead of launching a silent QA job.

Retest after a fix:

cursor-agent send <jobId> "Retest the same brief against the updated app. Report only current failures and changed evidence."
cursor-agent await-turn <jobId>
cursor-agent capture <jobId> 220 --clean

List running or recent QA jobs:

cursor-agent jobs --json

Write The QA Brief

Build the prompt as a test contract. Name the destination, the exact surfaces to test, and the report schema.

Use this structure:

Goal: QA <feature/change> at <URL> with browser-harness.

Success means:
- <flow 1> reaches <expected state>
- <flow 2> handles <edge case>
- <visual/layout requirement> holds at <viewport>
- The report includes verdict, steps, evidence, failures, and reproduction notes

Stop when: The report covers every listed flow once and gives a final PASS or FAIL verdict.

Use browser-harness:
- Open a fresh tab with new_tab("<URL>")
- Verify visible state with screenshot(), page_info(), and focused DOM reads
- Click and type through the browser like a user
- Capture evidence after each meaningful action

Return this report:
RESULT: PASS | FAIL
TARGET:
COVERAGE:
EVIDENCE:
FAILURES:
REPRODUCTION:
RETEST NOTES:

Browser-Harness Expectations

cursor-agent injects browser-harness by default. The Cursor agent receives:

• The local Cursor plugin at ~/.cursor/plugins/local/browser-harness.
• The copied browser-harness skill.
• The canonical browser-harness usage doc and helper reference.

Ask Cursor to use browser-harness for visible browser work. Ask for screenshots or page state when the report depends on UI evidence.

QA Scope Examples

Smoke test a local app:

cursor-agent start "Goal: QA the onboarding flow at http://localhost:3000 with browser-harness.

Success means:
- The landing screen loads without console-visible blocking errors
- The primary CTA opens onboarding
- Required fields show validation when submitted empty
- A valid test profile reaches the final confirmation screen

Stop when: You return one PASS or FAIL report with evidence for each step.

Return RESULT, TARGET, COVERAGE, EVIDENCE, FAILURES, REPRODUCTION, RETEST NOTES." \
  --dir /path/to/repo --force

Retest a fixed failure:

cursor-agent send <jobId> "Retest the failed validation path. Use the same URL and browser-harness flow. Return PASS if the previous failure is gone, otherwise return FAIL with updated reproduction steps."

Report Triage

Read Cursor's report, then choose the next action:

• Fix implementation bugs when the report includes a reproducible failure.
• Ask Cursor for one focused retest when evidence is incomplete.
• Record PASS when the report covers the brief and no failures remain.
• Broaden QA only when the change surface is larger than the original brief.

Health Check

Run this when Cursor, tmux, model access, or browser-harness setup is suspect:

cursor-agent health

The health check verifies tmux, Cursor auth, composer-2.5-fast, browser-harness files, the Cursor plugin, and the browser-harness executable. If health reports a Keychain sandbox error, rerun the same command as an approved/escalated Codex shell command before dispatching QA.