execute-qa

name

execute-qa

description

Validates feature implementation against PRD, Tech Spec, and Tasks through E2E testing with Playwright MCP at both desktop and mobile-web viewports, accessibility verification (WCAG 2.2), and visual analysis. Documents all bugs found with screenshot evidence and generates a comprehensive QA report. Use when the user asks to run QA, validate a feature, or test implementation completeness. Do not use for code review, bug fixing, or task implementation.

QA Execution

Procedures

Step 1: Documentation Analysis (Mandatory)

1. Read the PRD at ./tasks/prd-[feature-slug]/prd.md and extract ALL numbered functional requirements.
2. Read the Tech Spec at ./tasks/prd-[feature-slug]/techspec.md and verify implemented technical decisions.
3. Read Tasks at ./tasks/prd-[feature-slug]/tasks.md and verify completion status of each task.
4. Create a verification checklist based on the requirements.
5. Do NOT skip this step — understanding requirements is fundamental for QA.

Step 2: Environment Preparation (Mandatory)

1. Verify the application is running on localhost.
2. Use browser_navigate from Playwright MCP to access the application.
3. Confirm the page loaded correctly with browser_snapshot.

Step 3: E2E Tests with Playwright MCP — Desktop Web (Mandatory)

1. Read references/playwright-tools.md for the available tools reference.
2. Start in the desktop viewport (default: browser_resize to 1280×800 unless the project specifies otherwise).
3. For each functional requirement from the PRD: a. Navigate to the feature. b. Execute the expected flow. c. Verify the result. d. Capture screenshot evidence with a qa-… filename prefix. e. Mark as PASSED or FAILED.
4. Always use browser_snapshot before interacting to understand current page state.
5. Check browser console for JavaScript errors with browser_console_messages.
6. Verify API calls with browser_network_requests.

Step 4: E2E Tests with Playwright MCP — Mobile Web (Mandatory)

This step is mandatory for every QA run unless the PRD/techspec explicitly scopes the feature to desktop-only. Mobile web is a first-class target — never skip it because "the desktop pass already worked".

1. Resize the viewport to a mobile width with browser_resize. Default to 390×844 (iPhone 14 Pro). If the PRD names a specific device, match it.
2. Reload (browser_navigate to the same URL) so the app remounts at the new viewport — some responsive components only branch at mount.
3. Re-run every functional requirement from Step 3 at this viewport: a. Verify the layout does not overflow, clip, or hide controls. b. Verify primary actions (CTAs, dialogs, toasts, forms) are reachable and tappable. c. Test gesture interactions with real pointer events, not just keyboard fallbacks. For swipe/drag/long-press, dispatch PointerEvent (pointerdown → pointermove × N → pointerup) with pointerType: 'touch' via browser_evaluate, or use browser_drag when both endpoints are visible. d. Verify modals/sheets/toasts render inside the mobile viewport (no off-screen content) and that there is no horizontal scroll. e. Capture at least one screenshot per major screen at mobile width with a qa-mobile-… filename prefix.
4. Document any layout/gesture/interaction bug that only reproduces at the mobile viewport with a [mobile-only] tag in bugs.md.
5. Optionally run a second pass at a tablet width (768×1024) if the feature has explicit tablet considerations or a known breakpoint there.

Step 5: Accessibility Verification (Mandatory)

1. Verify for each screen/component, on both desktop and mobile viewports:
   • Keyboard navigation works (Tab, Enter, Escape).
   • Interactive elements have descriptive labels.
   • Images have appropriate alt text.
   • Color contrast is adequate.
   • Forms have labels associated to inputs.
   • Error messages are clear and accessible.
   • Touch target size is at least 24×24 CSS px (WCAG 2.2 AA — 2.5.8 Target Size Minimum).
   • Modals/dialogs trap focus, default focus to the safe action, and dismiss on Escape.
2. Use browser_press_key to test keyboard navigation.
3. Use browser_snapshot to verify labels and semantic structure.
4. Follow WCAG 2.2 standard (AA unless the project specifies otherwise).

Step 6: Visual Verification (Mandatory)

1. Capture screenshots of main screens with browser_take_screenshot at both desktop (1280×800) and mobile (390×844) viewports. Use filename prefixes qa- and qa-mobile- respectively to keep the evidence sorted.
2. Verify layouts in different states (empty, with data, error).
3. Document visual inconsistencies found, marking any that are mobile-only.
4. Confirm there is no horizontal scroll at the mobile viewport unless intentional.

Step 7: Bug Documentation

1. For each bug found, document with:
   • Bug ID, Description, Severity (High/Medium/Low), Viewport (desktop / mobile / both), Screenshot.
2. Tag mobile-only regressions with [mobile-only] in the description.
3. Save bugs to ./tasks/prd-[feature-slug]/bugs.md.
4. If a blocking bug is found, document and report immediately.

Step 8: Generate QA Report (Mandatory)

1. Read the report template at assets/qa-report-template.md.
2. Fill in all sections with actual results, including a dedicated subsection for the mobile-web pass.
3. Set status to APPROVED only when ALL PRD requirements are verified and functioning on both desktop and mobile-web viewports.

Error Handling

• If the application is not running, instruct the user to start it with bun run dev before retrying.
• If Playwright MCP is unavailable, report the error and suggest running E2E tests manually with bun run test:e2e.
• If a blocking bug prevents testing subsequent features, document it and continue with testable areas.
• If browser_resize is unavailable, fall back to launching a second navigation with the device-emulation URL flags exposed by the project, and note the workaround in the report.