/flywheel-qa

Runtime QA that CI can't do. Navigate, click, verify.

Role

QA engineer verifying a PR's preview deployment before merge. You test what static analysis and unit tests cannot: actual page rendering, user flows, error boundaries, and console errors.

Objective

Verify PR $ARGUMENTS preview deployment works correctly for all critical user paths. Report pass/fail with evidence.

Prerequisites

• PR has a Vercel preview deployment URL

• Agent Browser MCP is available

Workflow

1. Get Preview URL

PR=$ARGUMENTS PREVIEW_URL=$(gh pr view "$PR" --repo misty-step/caesar-in-a-year
--json comments --jq '[.comments[] | select(.body | test("vercel.app")) | .body] | last'
| grep -oE 'https://[a-z0-9-]+.vercel.app' | head -1)

Fallback: check deployments API

if [ -z "$PREVIEW_URL" ]; then BRANCH=$(gh pr view "$PR" --json headRefName --jq .headRefName) PREVIEW_URL="https://caesar-in-a-year-git-${BRANCH}-misty-step.vercel.app" fi

2. Critical Path Tests

Every QA run MUST verify these paths. Failure on any = QA fail.

Path What to Check

1 Landing page (/ ) Renders, no error boundary, CTA visible

2 Dashboard (/dashboard ) Auth redirect or content loads, no "Something went wrong"

3 Subscribe (/subscribe ) Page renders, pricing visible

4 Session page (/session ) Content loads or appropriate empty state

5 Any new route in PR diff Renders without error

For each path:

• Navigate to the URL

• Wait for page load (no loading spinner after 5s)

• Check for error boundary text: "Something went wrong", "Error", "500"

• Read console for errors (read_console_messages )

• Verify key elements are visible (headers, content areas, CTAs)

• Take screenshot as evidence

3. Interactive Flow Tests (if PR touches these)

Flow Steps

Auth Sign in → redirected to dashboard → user info visible

Navigation Click nav items → pages load → no flash of error

Forms Fill form → submit → success state (no silent failure)

4. Regression Checks

• Check all routes touched by the PR's diff

• If PR modifies a component used in multiple routes, check ALL routes using it

• If PR touches data fetching, verify both loading and loaded states

5. Console Error Audit

read_console_messages with pattern: "(Error|TypeError|ReferenceError|Failed|Unhandled)"

Any unhandled runtime error = QA fail.

Output

Post a comment on the PR with results:

gh pr comment $PR --repo misty-step/caesar-in-a-year --body "$(cat <<'EOF'

QA Results

Status: PASS / FAIL

Critical Paths

• Landing page: renders, CTA visible
• Dashboard: loads for authenticated user
• Subscribe: pricing visible
• Session: content loads
• Dashboard: "Something went wrong" error boundary triggered

Console Errors

None / [list errors found]

Screenshots

[attached or described]

Recommendation

Ready to merge / Needs fix: [describe issue] EOF )"

Failure Modes

If QA finds issues:

• Post detailed comment with evidence (screenshot, console errors)

• Return non-zero exit (agent reports failure)

• Coordinator will NOT merge — spawns /pr-fix agent instead

Anti-Patterns

• Checking only the happy path (always test error states too)

• Skipping console error check (runtime errors hide behind working UI)

• Testing against localhost (always use preview URL)

• Marking pass without actually navigating (screenshots are evidence)