E2e

Prerequisites

1. Playwright MCP server configured in .mcp.json. If missing, add manually:

   claude mcp add playwright -- npx @playwright/mcp@latest
   

   Then restart Claude Code for the MCP server to load.

2. Agent definitions exist at .claude/agents/e2e-scenario-analyzer.md and .claude/agents/playwright-e2e-tester.md

Execution Flow

Step 1: Verify MCP & Install Browsers

Check that Playwright MCP tools are available. If not, inform the user to add the MCP server and restart Claude Code.

Install browsers if needed:

# Initialize package.json if it doesn't exist
if [ ! -f package.json ]; then
  npm init -y
fi

# Install Playwright if needed
if ! npx playwright --version 2>/dev/null; then
  npm install -D @playwright/test
fi

# Install Chromium
npx playwright install chromium

Step 2: Start App Servers

Use non-standard ports to avoid conflicts with dev servers:

• TEST_BACKEND_PORT (default: 3231)
• TEST_FRONTEND_PORT (default: 5231)

Auto-detect the project stack and start servers:

Node.js (detected by package.json):

export TEST_BACKEND_PORT=${TEST_BACKEND_PORT:-3231}
export TEST_FRONTEND_PORT=${TEST_FRONTEND_PORT:-5231}

PORT=$TEST_BACKEND_PORT npm run start &
BACKEND_PID=$!

npm run dev -- --port $TEST_FRONTEND_PORT &
FRONTEND_PID=$!

Python / FastAPI (detected by requirements.txt, pyproject.toml):

uvicorn main.app:app --host 0.0.0.0 --port $TEST_BACKEND_PORT &
BACKEND_PID=$!

Python / Django (detected by manage.py):

python manage.py runserver 0.0.0.0:$TEST_BACKEND_PORT &
BACKEND_PID=$!

Go (detected by go.mod):

PORT=$TEST_BACKEND_PORT go run . &
BACKEND_PID=$!

Java / Spring Boot (detected by pom.xml or build.gradle):

SERVER_PORT=$TEST_BACKEND_PORT mvn spring-boot:run &
BACKEND_PID=$!

Health check:

sleep 3
curl -s http://localhost:${TEST_BACKEND_PORT}/health > /dev/null \
  || curl -s http://localhost:${TEST_BACKEND_PORT}/api/health > /dev/null \
  || curl -s http://localhost:${TEST_BACKEND_PORT}/ > /dev/null

Step 2.5: Create playwright.config.ts (if missing)

If playwright.config.ts does not exist at the project root, create one:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  timeout: 30000,
  retries: 1,
  use: {
    baseURL: `http://localhost:${process.env.TEST_FRONTEND_PORT || 5231}`,
    headless: true,
    screenshot: 'only-on-failure',
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { browserName: 'chromium' },
    },
  ],
  reporter: [['list']],
});

A starter config is also available at templates/playwright.config.ts.

Step 3: Spawn Scenario Analyzer Subagent

Spawn the Scenario Analyzer to explore the live application and document test scenarios.

Use the Task tool with the following parameters:

• subagent_type: "e2e-scenario-analyzer"
• description: "Analyze app for E2E scenarios"
• prompt:

You are the E2E Scenario Analyzer. Your task is to analyze the live
application and create comprehensive E2E test scenario documentation.

Context:
- Frontend URL: http://localhost:{TEST_FRONTEND_PORT}
- Backend URL: http://localhost:{TEST_BACKEND_PORT}
- Output Directory: tests/e2e/scenarios/

Instructions:
1. Read your agent definition at: .claude/agents/e2e-scenario-analyzer.md
2. Follow ALL instructions in the agent definition
3. Navigate to the live application using browser_navigate
4. Use browser_snapshot on each page to capture DOM structure
5. Use browser_click, browser_type, browser_fill_form to explore user flows
6. Document all discovered scenarios in tests/e2e/scenarios/<feature>.md
7. Create tests/e2e/scenarios/e2e-journeys.md for cross-feature flows
8. Create tests/e2e/scenarios/cross-cutting.md for shared concerns

IMPORTANT:
- Use Playwright MCP tools (browser_navigate, browser_snapshot, browser_click, etc.)
  to interact with the live application
- Do NOT output tool calls as text. USE the tools directly.
- Every scenario doc must include: priority, preconditions, steps, expected results

Begin by reading your agent definition at .claude/agents/e2e-scenario-analyzer.md

Wait for completion, then verify scenario docs exist in tests/e2e/scenarios/.

Step 4: Spawn E2E Tester Subagent

Spawn the E2E Tester to write, execute, and self-heal Playwright tests based on the scenario docs.

Use the Task tool with the following parameters:

• subagent_type: "playwright-e2e-tester"
• description: "Write and execute E2E tests"
• prompt:

You are the Playwright E2E Tester. Your task is to create, execute, and
validate E2E tests using Playwright MCP for the live application.

Context:
- Frontend URL: http://localhost:{TEST_FRONTEND_PORT}
- Backend URL: http://localhost:{TEST_BACKEND_PORT}
- Scenario Docs: tests/e2e/scenarios/ (created by Scenario Analyzer)
- Test Output Directory: tests/e2e/
- Max Healing Attempts: 3

Instructions:
1. Read your agent definition at: .claude/agents/playwright-e2e-tester.md
2. Follow ALL instructions in the agent definition
3. Read scenario docs from tests/e2e/scenarios/
4. Write Playwright test files in tests/e2e/:
   - Use browser_snapshot to verify selectors before writing tests
   - Use data-testid selectors where available, fallback to semantic selectors
   - Use Page Object Model for complex multi-page flows
   - Cover all critical workflows from the scenarios
5. Execute tests: Run `npx playwright test` via Bash
6. On failure (up to 3 attempts per test):
   - Use browser_navigate + browser_snapshot to re-inspect the failing page
   - Use browser_take_screenshot to capture the failure state
   - Fix selectors or test logic based on current DOM structure
   - Re-run `npx playwright test`
7. Report results summary when done

IMPORTANT:
- Use Playwright MCP tools for browser interaction (selector discovery, debugging)
- Use Bash tool for test execution (npx playwright test)
- Do NOT output tool calls as text. USE the tools directly.
- Distinguish between healable failures (selectors, timing) and environment failures (backend down)

Begin by reading your agent definition at .claude/agents/playwright-e2e-tester.md

Wait for completion.

Step 5: Verify and Cleanup

1. Verify: Check that test files exist in tests/e2e/ and review the subagent's reported results
2. Cleanup servers (only if you started them in Step 2):

kill $FRONTEND_PID $BACKEND_PID 2>/dev/null || true
sleep 2

3. Report results to the user with pass/fail summary

Success Criteria

• Playwright MCP server configured and responding
• Browsers installed (npx playwright install chromium)
• Scenario Analyzer subagent spawned and completed (scenario docs in tests/e2e/scenarios/)
• E2E Tester subagent spawned and completed (test files in tests/e2e/)
• All E2E tests pass (or environment failures documented)
• No flaky tests detected
• Test servers started and stopped cleanly
• Results reported to the user