Manual Frontend QA

Manual Frontend QA

Overview

Guide the human partner through manual verification with step-by-step instructions they execute in a browser. You provide the checklist, expected outcomes, and answerable questions — the partner does the clicking.

Core principle: You are a QA instructor, not a tester. Violating the letter is violating the spirit.

When to Use

• Partner explicitly asks for manual QA, hand-testing, or "can you verify this works?"
• Automated testing isn't worth the setup effort (one-off check, prototype, quick fix)
• The environment lacks Playwright, Cypress, or Selenium
• Partner says "just check it manually" or "don't write tests for this"
• Proactive: You completed a frontend change you cannot verify yourself (no browser access, complex visual layout) — offer manual QA before moving on

When NOT to Use

• Pure backend/data/logic change with no visible UI — use systematic-debugging instead
• Automated tests already cover the change — run those
• Partner explicitly asked for automated tests — use the appropriate testing tool
• You cannot describe expected behavior concretely — clarify requirements first

Process

Never use Playwright, Cypress, Selenium, or Chrome DevTools scripting during manual QA.

Proactive offering

Before offering manual QA, judge whether it's genuinely needed. Offer only when:

• You cannot verify yourself — you lack browser access, can't run Playwright/Cypress/Selenium, or can't see the visual output (layout, animations, hover states).
• The UI is too complex — multi-step interaction flow, behavior varies by screen size or browser, or visual correctness is hard to judge from code alone.

If you can verify the change yourself (e.g., you have Playwright, or it's a simple code-level check), do that instead. Don't offload work the partner doesn't need to do.

Otherwise: "Done — want manual QA steps to verify this?" Offer at the point where the task is done but before you start new work.

1. Start with what you know

Provide instructions for everything you can infer. Do not wait for perfect information.

Good: "Here are the QA steps. I assumed the form is at /login — if different, let me know." Bad: "Where is the login form?" (stops and waits — partner hasn't seen any instructions yet)

2. Scope missing pieces alongside instructions

If you need a fact (URL, component name, expected behavior), ask one targeted question — but alongside the instructions, not before them. Information-gathering about facts is fine:

• "What URL should I give you steps for?"
• "Is this React, Vue, or plain HTML?"
• "Should the error clear on blur or only on correction?"

3. Provide step-by-step instructions

Each step must be executable (partner knows exactly what to click), measurable (concrete expected outcome), and ordered (builds on previous steps). Include edge cases the partner won't think of: long input, special characters, rapid clicks, browser back button, Enter key behavior.

4. Ask answerable verification questions

Prefer questions with clear answers. The partner shouldn't need paragraphs to describe what they see.

Good: "After submitting with an empty email field, do you see an error next to the email input? (yes/no)" Good: "Which describes the button after submit? A) Disabled B) Disappeared C) Still enabled D) Other (describe briefly)" Bad: "What happens when you submit the form?" (vague — partner doesn't know what to look for)

5. Analyze feedback, decide next step

• All checks pass → Summarize what was verified. QA complete.
• Some checks fail → Debug that failure first (DOM inspection, console check). Do not start a new QA cycle.
• Behavior unclear → Ask for specific evidence (screenshot, error text, console output).

Gathering Evidence on Failures

Rationalization Prevention

Red Flags — STOP

Automation: thinking about Playwright/Cypress/Selenium, writing test code, asking partner to install testing libraries, considering "just this once" exceptions.

Paralysis: asking a third clarification question before any QA steps, thinking "I need to understand the whole system first," searching the codebase when manual QA was requested, rewriting the same step trying to make it perfect.

Incomplete: steps that assume the partner knows what to look for, no edge cases, no expected outcomes stated, vague verification questions ("what happens?"), no clear "QA complete" signal.

All of these mean: give the partner executable instructions now.

Quick Reference

Common Mistakes