e2e-check

Run E2E tests or perform interactive browser-based verification using Playwright.

Mode Detection

Parse $ARGUMENTS to determine mode:

• Runner mode (default): Run the Playwright test suite via CLI
• Interactive mode: If --interactive or interactive appears in args, use Playwright MCP tools for manual browser walkthrough

Runner Mode

1. Detect project

From $ARGUMENTS or current working directory:

• Match project name from cwd (e.g., my-app if cwd contains my-app)
• Check CLAUDE.md in the project root for the configured dev port and test command
• No match: ask which project to target

2. Pre-flight check

Check if the dev server is running on the expected port (read from CLAUDE.md or the project manifest):

Use: bash -c "curl -s -o /dev/null -w '%{http_code}' http://localhost:{port}/ 2>/dev/null" or equivalent.

If the server is NOT running:

• Report: "Dev server not running on port {port}. Start it with your project's dev command (e.g. yarn dev/npm run dev, python manage.py runserver, bundle exec rails s, go run, etc.), then re-run /e2e-check."
• Do NOT auto-start the dev server. Stop here.

3. Run tests

Run the E2E test command from CLAUDE.md or the project manifest (e.g., yarn test:e2e or npm run test:e2e for JS, or pytest tests/e2e for Python).

If a test filter was provided (e.g., auth), resolve it to the spec file path:

• auth → tests/e2e/auth.spec.ts
• Full path → use as-is

4. Parse output

Extract from Playwright output:

• Total, passed, failed, skipped counts
• Duration
• On failure: spec file name, test name, error message

5. Report

E2E Test Results -- {project}
================================
Total: X | Passed: X | Failed: X | Skipped: X
Duration: Xs
Baseline: {expected from CLAUDE.md} tests

[If failures:]
FAILURES:
- {spec-file} > {test-name}: {error summary}

[If screenshots saved:]
Screenshots: test-results/{spec-file}/

6. On failure

• Check test-results/ directory for saved screenshots
• Analyze failure type: timeout? Element not found? Assertion mismatch? Network error?
• Suggest fix based on the failure pattern

Interactive Mode

Use Playwright MCP tools to manually verify a user journey in the browser.

1. Navigate

Use mcp__playwright__browser_navigate to open http://localhost:{port} (port from CLAUDE.md).

ALWAYS use localhost, NEVER 127.0.0.1 (cookie domain mismatch issues).

2. Default journey (if no specific flow in args)

1. Navigate to login page
2. Fill credentials using mcp__playwright__browser_fill_form (use dev test credentials from .env or .env.test)
3. Submit login form via mcp__playwright__browser_click
4. Wait for dashboard to load via mcp__playwright__browser_wait_for
5. Take snapshot via mcp__playwright__browser_snapshot to verify dashboard renders data (not empty state)
6. Navigate to a key page (e.g., main feature list, report list)
7. Verify data is present (not loading spinner, not error)
8. Take screenshot via mcp__playwright__browser_take_screenshot as evidence

3. Custom journey

If args specify a flow (e.g., --interactive reports), walk through that specific flow step by step using:

• mcp__playwright__browser_navigate for page navigation
• mcp__playwright__browser_snapshot to read current page state (DOM)
• mcp__playwright__browser_fill_form for form inputs
• mcp__playwright__browser_click for button/link clicks
• mcp__playwright__browser_select_option for dropdowns
• mcp__playwright__browser_wait_for for loading/transition states
• mcp__playwright__browser_take_screenshot for visual evidence

4. Report

Summarize:

• What pages were visited
• What was verified (data rendered, forms worked, navigation succeeded)
• Any issues found (errors, empty states, broken elements)
• Screenshot paths for evidence

Rules

• Always localhost, never 127.0.0.1, due to cookie domain issues
• Dev port: read from CLAUDE.md or the project manifest for the active project
• Package manager: check CLAUDE.md or detect from lockfile (yarn.lock → yarn, package-lock.json → npm) (non-Node stacks: detect the build/install tool from the manifest type, e.g. Gemfile.lock, poetry.lock, Cargo.lock, go.sum, etc.)
• Never auto-start dev servers: report and stop if not running
• E2E baselines: compare against baseline documented in CLAUDE.md