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.
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.
Build it step by step
Sign in to tick steps off-
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.
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.
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.
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.
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.
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.
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.
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.
Files and links
-
Check it before you connect it. This server runs with your permissions:
npx @playwright/mcp@latestclaude mcp add-json playwright '{"command":"npx","args":["@playwright/mcp@latest"]}' -
-
-
-
Playwright best practices (opens in a new tab) playwright.dev
What people built
Show yoursNobody has shared a build yet. Yours could be the first.
Show what you built
Built this plan? Sign in to share your demo video, live app and screenshots.