# End-to-End Tests for Any Web App (Playwright MCP)

> Let your AI open your app in a real browser, map the key flows and write reliable Playwright tests, then run them on every push.

- Category: Developer tools
- Version: 1.0
- Source: https://wonly.dhfm.in/builder-4392ac/e2e-tests-playwright-mcp/

## Overview

Most AI-built apps have no tests, so every new prompt can break something that worked. This plan adds end-to-end tests to an existing web app: the Playwright MCP lets your AI tool drive a real browser, explore your app, and write tests that check what users actually do.

Works with any stack that runs in a browser (Next.js, Vite, Laravel, WordPress…).

Before you start: an app you can run locally, Node.js 20+, and Claude Code or Cursor. About 45 minutes.

## Tech stack

- GitHub Actions
- Playwright
- TypeScript

## Build steps

### 1. Install Playwright

In your app folder run: npm init playwright@latest (choose TypeScript, tests folder "tests", and yes to the GitHub Actions workflow). Replace the generated playwright.config.ts with the one in this plan and set the dev command and port to match your app.

Prompt:

```text
Read playwright.config.ts and package.json. Make sure webServer.command and the URL match how this app starts in development. Run npx playwright test --list and fix any config error.
```

**Done when:** npx playwright test --list runs without errors.

### 2. Connect the Playwright MCP

Add the MCP config to your AI tool (Claude Code: claude mcp add playwright npx @playwright/mcp@latest). Add the testing rules to CLAUDE.md or AGENTS.md. Start your app with npm run dev.

Prompt:

```text
Use the Playwright MCP to open http://localhost:3000 (or my dev URL) and describe the main pages and navigation you can see.
```

**Done when:** A browser window opens and your AI describes your app correctly.

### 3. Map the critical flows

Decide what must never break. Usually: sign up, sign in, the main action (create/book/buy), and one settings change.

Prompt:

```text
Explore the app with the Playwright MCP and write tests/PLAN.md: the 5 most important user flows, each with steps, expected results and the test data needed. Do not write test code yet. Ask me if a flow needs a test account.
```

**Done when:** tests/PLAN.md lists 5 flows you agree with.

### 4. Write the first test

Start with the most important flow and make it rock solid before writing more.

Prompt:

```text
Write a Playwright test for flow 1 in tests/PLAN.md following the rules in CLAUDE.md (role/label locators, no fixed waits, own test data). Run it with npx playwright test and fix it until it passes 3 times in a row.
```

**Done when:** Flow 1 passes three runs in a row on desktop and mobile.

### 5. Cover the other flows

Same pattern for each flow: explore with the MCP, write, run, fix.

Prompt:

```text
Write tests for flows 2–5 from tests/PLAN.md, one file each. Reuse a sign-in helper (tests/helpers.ts) with credentials from TEST_USER_EMAIL and TEST_USER_PASSWORD env vars. Run the whole suite and fix failures.
```

**Done when:** npx playwright test passes for all 5 flows.

### 6. Run on every push

The GitHub Actions workflow from step 1 runs the tests on each push and pull request.

Prompt:

```text
Review .github/workflows/playwright.yml: install dependencies, install browsers, run tests, upload the HTML report as an artifact on failure. Add the TEST_USER_* values as GitHub secrets (tell me where) and any env vars the app needs to start.
```

**Done when:** A push to GitHub shows a green Playwright check.

### 7. Make tests part of every AI change

The real win: your AI runs the tests before saying it is done.

Prompt:

```text
Add to CLAUDE.md (or AGENTS.md): "Before finishing any change, run npx playwright test. If a test fails, fix the code, not the test, unless the test is wrong; explain which." Then break something small on purpose and show me the test catching it.
```

**Done when:** A deliberate bug is caught by a failing test.

## Assets

### Playwright MCP — Official Microsoft server: lets the AI control a browser.

Source: https://wonly.dhfm.in/builder-4392ac/e2e-tests-playwright-mcp/playwright-mcp/

Review this config before installing: it runs a command on your machine.

```json
{
    "mcpServers": {
        "playwright": {
            "command": "npx",
            "args": [
                "@playwright/mcp@latest"
            ]
        }
    }
}
```

### CLAUDE.md (testing rules) — Add these rules to your existing CLAUDE.md or AGENTS.md.

```
# CLAUDE.md — End-to-end tests with Playwright

## Goal
Reliable end-to-end tests for this app's most important user flows.

## Rules
- Use the Playwright MCP to open the running app and explore a flow before writing its test.
- Tests live in `tests/`. One file per flow, e.g. `tests/sign-up.spec.ts`.
- Locators: `getByRole`, `getByLabel`, `getByText` first. `data-testid` only when nothing else is stable.
- Never use fixed waits (`waitForTimeout`). Rely on auto-waiting and `expect(...).toBeVisible()`.
- Each test sets up its own data and does not depend on another test.
- Run `npx playwright test` after writing each file; fix failures before moving on.
- Never put real passwords or keys in tests. Use env vars (`TEST_USER_EMAIL`, `TEST_USER_PASSWORD`).
```

### playwright.config.ts — Desktop + mobile, auto-starts your dev server, traces on failure.

```
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  reporter: 'html',
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'mobile', use: { ...devices['Pixel 7'] } },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});
```

### Playwright — The test runner.

https://github.com/microsoft/playwright

### Playwright best practices

https://playwright.dev/docs/best-practices


## Build instructions by tool

### Claude Code

Open a terminal in an empty folder, run `claude`, then paste the prompt.

```text
Build the "End-to-End Tests for Any Web App (Playwright MCP)" app from the OwnlyPlans blueprint at https://wonly.dhfm.in/builder-4392ac/e2e-tests-playwright-mcp/.
Stack: GitHub Actions, Playwright, TypeScript.
Follow the plan's steps in order: Install Playwright → Connect the Playwright MCP → Map the critical flows → Write the first test → Cover the other flows → Run on every push → Make tests part of every AI change.
Download the full plan (Markdown) from the link above and keep it in the project root as PLAN.md.
Ask me before adding anything not in the plan. (Prepared for Claude Code.)
```

### Cursor

Open an empty folder in Cursor, start an Agent chat, then paste the prompt.

```text
Build the "End-to-End Tests for Any Web App (Playwright MCP)" app from the OwnlyPlans blueprint at https://wonly.dhfm.in/builder-4392ac/e2e-tests-playwright-mcp/.
Stack: GitHub Actions, Playwright, TypeScript.
Follow the plan's steps in order: Install Playwright → Connect the Playwright MCP → Map the critical flows → Write the first test → Cover the other flows → Run on every push → Make tests part of every AI change.
Download the full plan (Markdown) from the link above and keep it in the project root as PLAN.md.
Ask me before adding anything not in the plan. (Prepared for Cursor.)
```

### Lovable

Start a new Lovable project and paste the prompt as your first message.

```text
Build the "End-to-End Tests for Any Web App (Playwright MCP)" app from the OwnlyPlans blueprint at https://wonly.dhfm.in/builder-4392ac/e2e-tests-playwright-mcp/.
Stack: GitHub Actions, Playwright, TypeScript.
Follow the plan's steps in order: Install Playwright → Connect the Playwright MCP → Map the critical flows → Write the first test → Cover the other flows → Run on every push → Make tests part of every AI change.
Download the full plan (Markdown) from the link above and keep it in the project root as PLAN.md.
Ask me before adding anything not in the plan. (Prepared for Lovable.)
```

## Definition of done

- Every build step is complete and the app runs locally.
- The main user flow works end to end.
- Share your build on OwnlyPlans with a demo link, build time and tool.