Playwright Agent MCP Starter

Production-ready starter for UI + API test automation with Playwright, TypeScript, Page Object Model, and AI-powered Claude Code agents via MCP.

---

Who It’s For

• Jr QA Engineers who want a clean, opinionated Playwright + TypeScript starting point
• Sr SDETs who want a batteries-included template with AI agent tooling and MCP integration
• Teams that want repeatable PR workflows — small scope, stable selectors, no flaky sleeps

---

What’s Included

• UI testing — Playwright Test with Page Object Model, custom fixtures, cross-browser (Chromium, Firefox, WebKit)
• API testing — Dedicated browser-free project for fast HTTP testing via Playwright request API
• Auth setup project — Runs once before UI tests, saves storageState so every test starts authenticated
• Test data factory — Generates unique users, addresses, products, orders with optional overrides
• Timeout constants — Named values (Timeouts.SHORT, .LONG, .NAVIGATION) instead of magic numbers
• 11 AI agents — Claude Code agents for test design, PR hygiene, security scanning, flake triage, coverage analysis, and more
• 2 MCP servers — @playwright/mcp (browser automation) + Playwright Test MCP (test runner)
• Docs library — QA conventions, prompt library, PR workflow, security sanitization, MCP setup

---

5-Minute Quickstart

# 1. Use this template (click "Use this template" on GitHub) — or clone directly
git clone https://github.com/ErkanBarin/playwright-agent-mcp-starter.git
cd playwright-agent-mcp-starter

# 2. Install dependencies
npm install

# 3. Set up environment
cp .env.example .env
# Edit .env → set BASE_URL to your app (defaults to http://localhost:3000)

# 4. Set up MCP (optional, for Claude Code / AI agent users)
cp .mcp.json.example .mcp.json
# MCP servers run via npx — no extra install needed

# 5. Install browsers + Playwright CLI
npx playwright install
npm install -g @playwright/cli@latest  # optional, for codegen/open/screenshot

# 6. Run one UI test (proof it works)
npx playwright test tests/ui/smoke.spec.ts --project=chromium

# 7. Run API tests (no browser launched — fast)
npx playwright test --project=api

# 8. See the HTML report
npm run report

Note: UI defaults to http://localhost:3000, API defaults to https://httpbin.org. All tests pass out of the box against these public URLs. Change them in .env to point to your application.

Windows users: This repo uses symlinks (.claude/agents and .claude/skills point to ai/). Run git config core.symlinks true before cloning, and enable Developer Mode in Windows Settings.

---

Repository Structure

├── ai/                  # Shared AI workspace (canonical location)
│   ├── agents/          # AI agent definitions (test design, PR hygiene, security, etc.)
│   ├── skills/          # Reusable prompt skills (MCP scout, prompt library)
│   ├── prompts/         # Prompt templates
│   └── knowledge/       # Domain knowledge and reference material
├── .claude/
│   ├── agents -> ai/agents   # Symlink — Claude Code reads from ai/
│   └── skills -> ai/skills   # Symlink — Claude Code reads from ai/
├── docs/
│   ├── QA_CONTEXT.md    # Scope, selectors, waits, PR slicing
│   ├── PROMPT_LIBRARY.md
│   ├── PR_WORKFLOW.md
│   ├── SECURITY_SANITIZATION.md
│   └── MCP_SETUP.md
├── pages/               # Page Object Models (base + login example)
├── tests/
│   ├── auth.setup.ts    # Auth setup (runs before UI projects)
│   ├── fixtures/        # Custom Playwright fixtures
│   ├── ui/              # UI test specs (smoke.spec.ts)
│   └── api/             # API test specs (health.spec.ts)
├── utils/
│   ├── index.ts         # Barrel — import everything from '../utils'
│   ├── timeouts.ts      # Named timeout constants (SHORT, MEDIUM, LONG, etc.)
│   ├── data-factory.ts  # Test data generators (user, product, order, etc.)
│   ├── api-helpers.ts   # API response assertion helpers
│   └── env.ts           # Typed environment variable access
├── .mcp.json.example    # MCP server config template
├── playwright.config.ts
└── package.json

---

Scripts

---

Project Architecture

The config defines 5 projects that run in a specific order:

setup → chromium, firefox, webkit (parallel)
                                        api (independent, no browser)

• setup — Authenticates once, saves browser state to .auth/state.json
• chromium/firefox/webkit — UI tests that load the saved auth state (no login per test)
• api — Runs against tests/api/ with no browser — pure HTTP requests

Auth state is cached between runs — if cookies are still valid, login is skipped (~96ms instead of ~1.7s). State is stored in .auth/ (outside test-results/) so Playwright doesn’t wipe it.

Utilities (barrel import)

All utils re-export from utils/index.ts — one import for everything:

import { Timeouts, TestData, assertStatus, getBaseUrl } from '../utils';

Timeouts

await page.click(selector, { timeout: Timeouts.SHORT });   // 3s
await expect(locator).toBeVisible({ timeout: Timeouts.MEDIUM }); // 5s
await page.goto(url, { timeout: Timeouts.NAVIGATION });    // 15s

Test Data Factory

Generate unique, realistic test data with optional overrides:

import { TestData } from '../utils';

const user = TestData.user();                        // random user
const admin = TestData.user({ role: 'admin' });      // override role
const product = TestData.product({ price: 9.99 });   // override price
const order = TestData.order();                      // random order
const email = TestData.email('signup');               // [email protected]

---

AI Workspace

All AI resources live in the ai/ directory — a shared workspace for Claude Code, GitHub Copilot, and other AI tools. Claude Code reads agents and skills via symlinks (.claude/agents → ai/agents, .claude/skills → ai/skills).

Conventions for all AI tools are defined in AGENTS.md at the repo root. GitHub Copilot reads .github/copilot-instructions.md which points back to AGENTS.md.

Agents

12 agents are included to accelerate QA workflows:

Copy-Paste Prompts

Design UI tests for the login page following POM pattern. Check existing
page objects first, then create missing ones. Tag all tests @ui @smoke.

Scan this repo for hardcoded secrets, API keys, tokens, and internal URLs.
Report findings with file paths and line numbers.

Analyze test coverage gaps. Map page objects and API endpoints to existing
tests. Show what's untested and prioritize by risk.

See docs/PROMPT_LIBRARY.md for the full prompt library.

---

MCP Setup

Two MCP servers connect Claude Code to your browser and test runner:

cp .mcp.json.example .mcp.json

See docs/MCP_SETUP.md for prerequisites, VS Code extensions, and a sanity check walkthrough.

---

CI

This repo includes a GitHub Actions workflow that runs all Playwright tests on every push and PR to main.

It works out of the box — no configuration needed.

See .github/workflows/playwright.yml for the workflow definition.

---

Documentation

• AGENTS.md — AI agent conventions and project standards
• MCP Setup — MCP server configuration and sanity check
• QA Context & Conventions — scope, selectors, waits, PR slicing
• Prompt Library — copy-paste prompts for agents
• PR Workflow — standard PR flow
• Security Sanitization — pre-publish checklist

---

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT