playwright-qa-cli

name	playwright-qa-cli
description	Automated QA testing using playwright-cli (CLI tool, NOT MCP tools). Provisions a test user, opens a headless browser, logs in, navigates to target pages, takes screenshots, and generates a REPORT.md. Two modes: VERIFY (reproduce a bug before fixing) and CHECK (confirm a fix works). Use this skill whenever the user says 'QA this', 'test this fix', 'verify this bug', 'smoke test', 'check if this works', 'reproduce this issue', 'run playwright QA', or 'playwright-qa-cli'. Also triggered from /fix-ticket at pre-fix and post-fix stages. Works for any page or user flow — not limited to specific features.
allowed-tools	Bash(playwright-cli:*), Bash(npx:playwright-cli:*)

Playwright QA (CLI Variant)

Automated headless-browser QA using playwright-cli bash commands. Provisions a test user, logs in, navigates to target pages, screenshots each step, generates REPORT.md, cleans up.

CRITICAL: No MCP Tools

Do NOT use any mcp__plugin_playwright_playwright__* tools. Use ONLY playwright-cli bash commands via the Bash tool. If playwright-cli is not found, STOP and ask user to install — do NOT fall back to MCP tools.

PATH Setup — REQUIRED

Prefix EVERY playwright-cli bash command with:

export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli ...

Parameters

Parameter	Default	Example	Description
base	prod	local	prod = CONFIG.md PROD_URL, local = http://localhost:3000
mode	check	verify	verify = reproduce bug, check = confirm fix
url	auto-detect	/dashboard/receipts	Page to test
change_description	from git diff	"Fixed button overflow"	What to verify
ticket_id	none	PROJ-123	Issue tracker ticket (folder naming)
skip_cleanup	false	true	Keep test user alive

Configuration

All project-specific settings are defined in CONFIG.md at the root of this skill directory. Before first use, copy CONFIG.example.md to CONFIG.md and fill in your values.

Setting	Source
Test Email	CONFIG.md → TEST_USER_EMAIL
Test Password	CONFIG.md → TEST_USER_PASSWORD
Supabase Project ID	CONFIG.md → SUPABASE_PROJECT_ID
Production URL	CONFIG.md → PROD_URL
Viewport	1440x900

Password note: Avoid !, \, $ in test passwords — playwright-cli fill escapes shell-special characters.

Execution Flow

Phase 1:   Setup (mkdir screenshots, detect route from git diff)
Phase 1.5: Dev server (local only — check port 3000, start if needed)
Phase 2:   Provision test user → read references/provision.md
Phase 3:   Login via CLI → use state-save for auth persistence
Phase 4:   Navigate & test target page
Phase 5:   Cleanup → read references/cleanup.md + playwright-cli close
Phase 6:   Generate REPORT.md → read references/report-templates.md

Phase 1: Setup

mkdir -p playwright-qa-screenshots/{test-name}-{mode}

{test-name} = kebab-case from ticket ID or change description. {mode} = -verify or -check.

Route detection (if no url param): run git diff --name-only HEAD, map files to routes.

Customize the route detection table in CONFIG.md. Example format:

File Pattern	Route
app/dashboard/page-a/**, components/page-a/**	/dashboard/page-a
app/dashboard/page-b/**, components/page-b/**	/dashboard/page-b
app/dashboard/settings/**	/dashboard/settings
Default	/dashboard

Phase 1.5: Dev Server (Local Only)

Skip if base=prod. Check lsof -ti:3000. If no server, start npm run dev in background, poll until ready (max 30s). Set WE_STARTED_SERVER flag for cleanup.

Phase 2: Provision Test User

Read references/provision.md and follow it exactly. It contains the complete Admin API flow, reset SQL, business profile creation, credits setup, and email verification.

Phase 3: Login via Playwright CLI

Open browser and navigate

export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli open "{base_url}/sign-in"
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli resize 1440 900
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli screenshot --filename=playwright-qa-screenshots/{test-name}/01-sign-in-page.png
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli snapshot

Find element refs and fill login form

Read the snapshot output to find element refs (e.g., e93 for Email, e99 for Password, e104 for Sign In). Refs change between pages — always snapshot before interacting.

export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli fill {email-ref} "{TEST_USER_EMAIL}"
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli fill {password-ref} "{TEST_USER_PASSWORD}"
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli click {submit-ref}

Wait for navigation and verify

After clicking login, wait for the page to settle before taking a snapshot. Use eval to check readiness instead of a blind sleep:

export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli eval "() => new Promise(r => setTimeout(r, 3000))"
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli snapshot
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli screenshot --filename=playwright-qa-screenshots/{test-name}/02-after-login.png

Why 3s here: Auth redirects involve a server round-trip + client-side redirect chain. This is one of the few places a timed wait is appropriate because there's no single DOM element that reliably signals "auth complete + redirect finished."

Verify redirect target

Customize these redirect targets in CONFIG.md to match your app's auth flow:

URL Contains	Meaning	Action
/dashboard	Login succeeded	Continue to Phase 4
/verify-email	Missing email verification	Fix via provision.md, retry
/setup or /onboarding	Missing profile/onboarding	Re-run provision setup, retry
/sign-in	Login failed	Recreate user via Admin API

Save auth state (optional but recommended)

If you'll navigate multiple pages, save auth state to skip re-login on session loss:

export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli state-save playwright-qa-screenshots/{test-name}/auth-state.json

Restore later with playwright-cli state-load if the session drops.

Phase 4: Navigate & Test

Read references/cli-patterns.md for detailed interaction patterns (waiting, forms, dialogs, file uploads, scrolling, error checking). The patterns below are a summary.

Navigate to target page

export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli goto "{base_url}{target_route}"

Wait for page to load

Use eval to wait for a meaningful signal rather than a blind sleep:

# Wait for network idle (no pending fetches for 500ms)
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli eval "() => new Promise(resolve => { let timer; const check = () => { timer = setTimeout(resolve, 500); }; const observer = new PerformanceObserver(() => { clearTimeout(timer); check(); }); observer.observe({entryTypes: ['resource']}); check(); })"

If that's too complex for the situation, a simple 2-3s wait is acceptable — just document why:

# Simple wait — acceptable when page has heavy async rendering
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli eval "() => new Promise(r => setTimeout(r, 2000))"

Snapshot + screenshot

export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli snapshot
export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli screenshot --filename=playwright-qa-screenshots/{test-name}/03-target-page.png

Mode-specific testing

verify mode: Reproduce bug steps from ticket using CLI commands. Screenshot each step. Check playwright-cli console error for JS errors. Verdict: "Bug confirmed" or "Not reproducible".

check mode: Inspect snapshot for error indicators. Verify expected UI elements are present. Run change-specific checks. Check console for errors.

Expected elements by route

Customize this table in CONFIG.md to match your application's routes and expected elements:

Route	Expected Elements
/dashboard	Main dashboard content, navigation
/dashboard/page-a	Page A content or empty state
/dashboard/page-b	Page B content or empty state
/dashboard/settings	Settings form

Key interaction commands

Action	Command
Click element	playwright-cli click {ref}
Fill input	playwright-cli fill {ref} "text"
Type text (keystroke)	playwright-cli type "text"
Select dropdown	playwright-cli select {ref} "value"
Upload file	playwright-cli upload "/absolute/path/to/file"
Check checkbox	playwright-cli check {ref}
Press key	playwright-cli press Enter / press Tab / press Escape
Scroll down	playwright-cli mousewheel 0 500
Full-page screenshot	playwright-cli screenshot --full-page --filename=...
Check JS errors	playwright-cli console error
Check network	playwright-cli network
Accept dialog	playwright-cli dialog-accept
Dismiss dialog	playwright-cli dialog-dismiss
Evaluate JS	playwright-cli eval "() => document.title"

Golden rule: Always snapshot before interacting with a new page. Element refs are page-specific and change after navigation or significant DOM updates.

Phase 5: Cleanup

Read references/cleanup.md and execute the SQL via your Supabase SQL execution tool. Then:

export PATH="$HOME/.npm-global/bin:$PATH" && playwright-cli close

If WE_STARTED_SERVER, kill port 3000: lsof -ti:3000 | xargs kill 2>/dev/null

If skip_cleanup=true, skip the SQL cleanup but still close the browser.

Phase 6: Report

Read references/report-templates.md and generate REPORT.md in the screenshots folder using the Write tool.

Error Handling

Scenario	Action
playwright-cli not found	STOP. Tell user: npm install -g playwright-cli. Do NOT use MCP.
Stale browser session	playwright-cli kill-all then retry open
Login redirect to verify-email	Fix email verification (see provision.md)
Login redirect to setup/onboarding	Re-run profile creation (provision.md)
Login redirect back to sign-in	Recreate user via Admin API
Element ref not found	Re-run snapshot — refs may have changed after DOM update
Supabase MCP unavailable	Skip provisioning, ask user to log in manually
Cleanup fails	Log warning, continue
Page shows loading spinner	Wait with eval, then re-snapshot