Live Test

--- name: live-test description: > Live browser testing for web applications using Playwright CLI. Covers visual review, functional testing, console/network debugging, auto-fix UI issues, and responsive testing at 3 breakpoints. triggers: - "test this page" - "check the UI" - "test responsive" - "run a live test" - "test localhost" - "browser test" - "visual review" - "test my app" - "functional test" - "live test" - "test the page" - "test the site" - "check responsive" - "visual test" tags: - testing - browser - playwright - responsive - visual - ui - live matching: fuzzy --- # Live Test - Web Application Testing ## How It Works Playwright CLI runs via Bash commands. Snapshots save to .playwright-cli/ as compact YAML files. Screenshots save as PNG. The agent reads only what it needs — no bloated accessibility trees in context. ## IMPORTANT: Command Sequence You MUST call `playwright-cli open` before any other command. All commands operate on the browser opened by `open`. If you get "browser is not open", run `open` first. ## Cleanup Rule (CRITICAL) All screenshots and snapshots are temporary artifacts for analysis only. After the test run completes (end of Phase 8), delete ALL generated files: ```bash rm -f /tmp/playwright-test-*.png rm -rf .playwright-cli/ ``` Never leave test artifacts on disk. The final report captures all findings in text — the image files are only needed during analysis. ## Quick Reference ``` # Browser lifecycle playwright-cli open [url] launch browser (optionally navigate to url) playwright-cli open [url] --headed launch in headed mode (visible window) playwright-cli close close browser # Navigation playwright-cli goto <url> navigate to a url playwright-cli go-back go back playwright-cli go-forward go forward playwright-cli reload reload page # Interaction playwright-cli snapshot get element refs as YAML playwright-cli screenshot [ref] capture current state (or specific element) playwright-cli click <ref> click element by ref playwright-cli fill <ref> <text> fill input field playwright-cli type <text> type text into focused element playwright-cli select <ref> <val> select dropdown option playwright-cli hover <ref> hover over element playwright-cli press <key> press keyboard key playwright-cli check <ref> check checkbox/radio playwright-cli uncheck <ref> uncheck checkbox/radio # Viewport playwright-cli resize <w> <h> resize browser window # DevTools playwright-cli console [min-level] read console messages (levels: log, warning, error) playwright-cli network list network requests # Tabs playwright-cli tab-list list all tabs playwright-cli tab-new [url] open new tab playwright-cli tab-select <index> switch to tab playwright-cli tab-close [index] close tab # Storage / Auth playwright-cli state-save [filename] save cookies + localStorage + sessionStorage playwright-cli state-load <filename> load saved state playwright-cli cookie-list list cookies playwright-cli localstorage-list list localStorage playwright-cli sessionstorage-list list sessionStorage # Save playwright-cli pdf save page as PDF ``` ## Workflow (8 Phases) ### Phase 1: Target Detection - If URL provided: use it directly - If no URL: run `git diff --name-only HEAD~3` - Filter for page files: `src/app/**/page.tsx`, `app/**/page.tsx` - Map file paths to URLs: - Strip route groups like `(dashboard)`, `(auth)` - Default base: http://localhost:3000 - If multiple pages changed, test each sequentially ### Phase 2: Browser Setup & Authentication **Step 1 — Derive project name and session path:** ```bash PROJECT=$(basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)) SESSION_FILE="$HOME/.claude/playwright-sessions/${PROJECT}.json" ``` **Step 2 — Open browser with or without saved session:** If session file exists: ```bash playwright-cli open --headed playwright-cli state-load "$SESSION_FILE" playwright-cli goto <url> ``` If no session file: ```bash playwright-cli open <url> --headed ``` **Step 3 — Check if auth is needed:** ```bash playwright-cli snapshot ``` - Look for: login forms, "Sign in" buttons, `/login` or `/auth` in URL - If page loads normally (dashboard, app content) → auth is valid, continue **Step 4 — If login is needed (no session or expired):** - Tell the user: "This page requires login. Please log in manually in the browser window. Tell me when you're done." - Wait for user confirmation - After user confirms, save the session: ```bash mkdir -p "$HOME/.claude/playwright-sessions" playwright-cli state-save "$SESSION_FILE" ``` - Confirm: "Session saved for ${PROJECT}. Future tests will auto-login." **Step 5 — Take initial snapshot** to understand page structure: ```bash playwright-cli snapshot ``` **Session file location:** `~/.claude/playwright-sessions/<project-name>.json` - One file per project, reused across test runs - Contains cookies + localStorage + sessionStorage - Never committed to git (lives in ~/.claude/) - To force re-login: delete the file or pass `--reauth` argument ### Phase 3: Visual Review ```bash playwright-cli screenshot --filename=/tmp/playwright-test-visual-review.png ``` - Read screenshot and analyze for: - Layout problems (misaligned elements, broken grids) - Spacing inconsistencies - Color/contrast issues - Typography problems - Missing states (loading, error, empty) ### Phase 4: Functional Testing ```bash playwright-cli snapshot ``` - Read YAML snapshot to identify interactive elements - Test buttons, links, forms using refs: ```bash playwright-cli click <ref> playwright-cli fill <ref> "test input" ``` - Check console errors: ```bash playwright-cli console error ``` - Check network failures: ```bash playwright-cli network ``` ### Phase 5: Debug Issues - Console errors → diagnose and fix: - React hydration → fix server/client mismatch - API failures → verify endpoints - Missing env vars → check .env.local - Network failures: - 404 → check route exists - 500 → fix API code - CORS → check Next.js config ### Phase 6: UI Improvements (Auto-Apply) - Auto-fix issues found in Phase 3: - Spacing adjustments - Color consistency - Button styling - Typography fixes - After each fix, reload and re-screenshot to verify: ```bash playwright-cli reload playwright-cli screenshot --filename=/tmp/playwright-test-after-fix.png ``` ### Phase 7: Responsive Testing Test at three breakpoints: ```bash # Mobile playwright-cli resize 393 852 playwright-cli screenshot --filename=/tmp/playwright-test-mobile.png # Tablet playwright-cli resize 768 1024 playwright-cli screenshot --filename=/tmp/playwright-test-tablet.png # Desktop playwright-cli resize 1440 900 playwright-cli screenshot --filename=/tmp/playwright-test-desktop.png ``` - Check: touch targets, text readability, no horizontal scroll, layout adapts, no awkward breakpoints ### Phase 8: Final Report & Cleanup Structured summary of all findings: - Pages tested - Issues found & fixed - UI improvements applied - Console/network errors - Responsive status (mobile/tablet/desktop pass/fail) **Cleanup (mandatory):** Delete all temporary test artifacts: ```bash rm -f /tmp/playwright-test-*.png rm -rf .playwright-cli/ ``` Leave browser open for manual review. ## Session Management Session files are stored at `~/.claude/playwright-sessions/<project-name>.json`. They capture cookies, localStorage, and sessionStorage — covering both cookie-based auth (traditional sessions) and token-based auth (JWTs in localStorage). ### Commands ```bash # Save current browser state (after manual login) playwright-cli state-save ~/.claude/playwright-sessions/my-project.json # Load saved state into browser (browser must be open first) playwright-cli state-load ~/.claude/playwright-sessions/my-project.json # Inspect what's stored playwright-cli cookie-list playwright-cli localstorage-list playwright-cli sessionstorage-list ``` ### Force Re-login If auth is stale or user wants to switch accounts: ```bash rm ~/.claude/playwright-sessions/<project-name>.json ``` Then run `/test` again — it will prompt for manual login. ### Multiple Environments For projects with staging vs production: ```bash playwright-cli state-save ~/.claude/playwright-sessions/my-project-staging.json playwright-cli state-save ~/.claude/playwright-sessions/my-project-prod.json ``` ## Fallback If Playwright CLI is not installed, do NOT fall back to Chrome MCP tools. Instead, tell the user: "Playwright CLI is not installed. Install it with: `npm install -g @playwright/cli@latest`" and stop.