<!-- Design decisions: - Dynamic routing model: each action uses the best skill (Phase 1.2 routing tree) - Auth protocol: prompt-always — NEVER guess credentials (absolute constraint) - playwright-cli preferred for DOM interaction — generates PW code as side-effect - agent-browser preferred for auth flows — session persistence support - Role-based locators mandatory (getByRole, getByLabel) — not CSS selectors - Script for Playwright execution — deterministic, not LLM judgment -->

QA Manual Testing & E2E Code Generation

Orchestrates browser skills to act like a human tester: navigate, interact, verify, and report.

When to Use

Trigger: "test this flow", "QA this page", "generate E2E tests", "test login flow", "manual testing", "write Playwright tests for"

Explicit:

• /mk:qa-manual tasks/plans/260315-auth-flow.md --report → manual QA report
• /mk:qa-manual tasks/plans/260315-checkout.md --generate → Playwright .spec.ts
• /mk:qa-manual https://app.example.com → explore and test from URL
• /mk:qa-manual [spec] → auto-detect use case from spec content

Workflow Integration

Operates in Phase 4 (Review) for QA reports or Phase 3 (Build) for E2E code generation.

Skill Routing

Each action uses the best browser skill:

Action	Skill	Why
DOM interaction (click, fill, type)	mk:playwright-cli	Generates Playwright code as side-effect
Navigation + page load	mk:playwright-cli	goto + wait, code output
Visual verification (screenshot)	mk:agent-browser	Annotated snapshots
Auth flow (login, session, MFA)	mk:agent-browser	Session persistence, auth import
Execute Playwright test	Script: npx playwright test	Deterministic

Authentication Protocol

On auth encounter (login page, MFA, 401/403):

1. STOP current flow immediately
2. Show user:

   ⚠️ Authentication required at: [current URL]
   mk:qa-manual needs credentials to continue.
   Please provide:
   - Username/email: ___________
   - Password: ___________
   Type 'skip' to skip this flow or 'abort' to stop testing.
   

3. WAIT for user input — do NOT proceed without it
4. On credentials → fill form using mk:playwright-cli, continue flow
5. On 'skip' → mark flow SKIPPED, move to next
6. On 'abort' → end session, output partial report

NEVER: Guess credentials. Use hardcoded test credentials. Proceed past auth without input. Store credentials in any file.

Process

See references/qa-process.md for detailed Use Case A and Use Case B processes.

Use Case A — Manual QA: Load spec → extract flows → navigate each → verify outcomes → report

Use Case B — E2E Code Gen: Run Use Case A → record interactions → generate .spec.ts with role-based locators

Output Format

See references/output-templates.md for full templates.

QA Report → structured pass/fail per flow with evidence Playwright Code → production-ready .spec.ts using getByRole, getByLabel, getByText

Scripts

Script	Purpose	Invocation
scripts/run-playwright.sh	Execute generated .spec.ts	After E2E code generation

References

Reference	When to load	Content
qa-process.md	Steps 1-4	Detailed Use Case A + B processes
output-templates.md	Step output	QA report + Playwright code templates

Failure Handling

Failure	Detection	Recovery	Message
Auth encountered	URL/form patterns	Auth protocol above	"⚠️ Authentication required..."
Page load timeout	30s timeout	Retry ×2 then report	"Page load timed out at [URL]"
Element not found	Selector fails	Re-snapshot, try alternate	"Element not found, re-scanning..."
Spec not found	File missing	Ask user	"Spec file not found. Provide path or URL."
Playwright exec fails	Non-zero exit	Show error + fix hints	"Test failed: [error]. Fix: [hint]"

Gotchas

• Testing against stale deployment: Running E2E tests against yesterday's build → Verify deployment version matches expected before starting test run
• Credentials hardcoded in generated spec files: Auto-generated .spec.ts contains login credentials → Always use environment variables for credentials; never inline in test code