Playwright Wizard MCP Server

🧙‍♂️ An intelligent Model Context Protocol (MCP) server that guides you through creating professional Playwright test suites with best practices built in.

Overview

Playwright Wizard MCP provides a structured, step-by-step approach to building comprehensive E2E test suites. Instead of starting from scratch or copying boilerplate, this MCP server guides you through industry best practices with intelligent prompts tailored to your application.

Features

• 🧙‍♂️ Step-by-step wizard workflow for creating comprehensive test suites
• 📚 Comprehensive prompts covering analysis, planning, setup, and implementation
• 🎯 Best practices for selectors, fixtures, and parallel execution
• 🔧 Optional enhancements for accessibility and API testing
• 📖 Reference documentation for advanced patterns
• 🌐 MCP Registry integration for easy discovery and installation

Prerequisites

• Node.js 18 or higher
• An MCP-compatible client:
  • GitHub Copilot in VS Code (with MCP support)
  • Claude Desktop
  • Cline (VS Code extension)
  • Any other MCP-compatible AI client

Installation

Quick Start (Recommended)

No installation required! Use npx to run the server on-demand:

{
  "mcpServers": {
    "playwright-wizard": {
      "command": "npx",
      "args": ["-y", "playwright-wizard-mcp"]
    }
  }
}

This approach automatically uses the latest version without managing local installations.

Global Installation

For faster startup and offline use:

npm install -g playwright-wizard-mcp

Then configure without npx:

{
  "mcpServers": {
    "playwright-wizard": {
      "command": "playwright-wizard-mcp"
    }
  }
}

From MCP Registry

Also available in the official MCP Registry for easy discovery.

Configuration

GitHub Copilot (VS Code)

1. Open your MCP config file:

   • macOS: ~/Library/Application Support/Code/User/mcp.json
   • Windows: %APPDATA%\Code\User\mcp.json

2. Add the server configuration:

{
  "servers": {
    "playwright-wizard": {
      "command": "npx",
      "args": ["-y", "playwright-wizard-mcp@latest"],
      "type": "stdio"
    }
  }
}

3. Restart VS Code or reload window (Cmd/Ctrl + Shift + P → "Developer: Reload Window")
4. Open GitHub Copilot Chat and verify tools are available

Claude Desktop

1. Open your config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "playwright-wizard": {
      "command": "npx",
      "args": ["-y", "playwright-wizard-mcp"]
    }
  }
}

3. Restart Claude Desktop
4. Verify installation by seeing the 🔨 tool icon when you open a new chat

Cline (VS Code)

1. Open VS Code
2. Go to Cline settings (Cmd/Ctrl + Shift + P → "Cline: Open MCP Settings")
3. Add the server configuration:

{
  "mcpServers": {
    "playwright-wizard": {
      "command": "npx",
      "args": ["-y", "playwright-wizard-mcp"]
    }
  }
}

4. Restart VS Code
5. Look for Playwright Wizard tools in Cline's available tools list

Available Tools

Playwright Wizard exposes 15 tools organized into three categories: core workflow, optional enhancements, and reference documentation.

Core Workflow (Complete in Order)

These 5 tools guide you through creating a complete, production-ready test suite:

Tool	Purpose	What It Creates	When to Use
analyze-app	Analyzes your application structure and tech stack	project-config.md, pages.md, selector-strategy.md	Start here - First step for any new test suite
generate-test-plan	Creates comprehensive test scenarios and acceptance criteria	test-plan.md with suites, flows, and edge cases	After analyzing the app
setup-infrastructure	Sets up Playwright config, fixtures, and folder structure	playwright.config.ts, fixtures, test helpers	After test plan is ready
generate-page-objects	Generates type-safe page object models with optimal selectors	Page object files in tests/pages/	After infrastructure is set up
implement-test-suite	Writes actual tests with assertions and error handling	Complete test files in tests/	Final step - implement all planned tests

Optional Enhancements

Add these capabilities after completing the core workflow:

Tool	Purpose	What It Adds	When to Use
setup-ci-cd	Adds GitHub Actions for automated testing	.github/workflows/playwright.yml	When you need CI/CD integration
add-accessibility	Integrates axe-core for WCAG 2.1 AA compliance	Accessibility test helpers and examples	For accessibility requirements
add-api-testing	Adds REST/GraphQL/tRPC API testing	API test utilities and examples	When testing backend APIs
advanced-optimization	Deep performance optimization and auth state reuse	Advanced patterns and configs	For complex apps with performance needs

Reference Documentation

Access these anytime for additional context and patterns:

Tool	Content	Use When
reference-core-principles	Core testing principles and quality standards	You need guidance on best practices
reference-workflow-overview	Complete workflow explanation and prompt relationships	You want to understand the big picture
reference-mcp-setup	MCP server setup and usage patterns	Having installation or configuration issues
reference-selector-strategies	Selector best practices and HTML quality scoring	Need help choosing the right selectors
reference-fixture-patterns	Playwright fixture patterns for parallel execution	Working with fixtures or state management
reference-data-storage-patterns	Test data storage patterns (ORM, JSON, MSW)	Need guidance on test data management

How to Use the Tools

Simply ask your AI assistant to use them:

"Use the analyze-app tool to help me understand my application"
"Run the generate-test-plan tool to create test scenarios"
"Use setup-infrastructure to configure Playwright"

The AI will call the appropriate tool, receive detailed instructions, and execute them automatically. You'll see the results (files created, analysis completed) without seeing the internal instructions.

Getting Started

First-Time Setup (5 minutes)

1. Install and configure the MCP server (see Configuration above)
2. Restart your AI client (Claude Desktop or VS Code)
3. Verify installation: Open a new chat and look for the 🔨 tool icon

Creating Your First Test Suite (30-60 minutes)

Here's what a typical workflow looks like:

Step 1: Analyze Your Application

You: "Help me analyze my React app for Playwright testing"

AI: *Calls analyze-app tool*
    - Detects React, TypeScript, Vite from package.json
    - Browses key pages (/, /login, /dashboard)
    - Evaluates DOM quality and accessibility
    - Creates .playwright-wizard-mcp/ folder with analysis files

AI: "✅ Analysis complete! Your app uses React + TypeScript with Vite.
     I found 5 key pages. HTML quality is good (score: 8/10).
     Created project-config.md, pages.md, and selector-strategy.md."

Step 2: Generate Test Plan

You: "Create a test plan based on the analysis"

AI: *Calls generate-test-plan tool*
    - Creates comprehensive test scenarios
    - Defines user flows and edge cases
    - Specifies acceptance criteria
    - Adds test data requirements

AI: "✅ Test plan created! I've defined 4 test suites:
     - Authentication (5 scenarios)
     - Dashboard (7 scenarios)
     - User Profile (4 scenarios)
     - Settings (3 scenarios)
     See test-plan.md for details."

Step 3: Set Up Infrastructure

You: "Set up the Playwright infrastructure"

AI: *Calls setup-infrastructure tool*
    - Creates playwright.config.ts with optimal settings
    - Sets up fixtures for parallel execution
    - Creates folder structure (tests/, pages/, fixtures/)
    - Adds test helpers and utilities

AI: "✅ Infrastructure ready!
     - Created playwright.config.ts (3 browsers, parallel mode)
     - Set up custom fixtures for test isolation
     - Organized folder structure
     Ready for page objects!"

Step 4: Generate Page Objects

You: "Generate page object models"

AI: *Calls generate-page-objects tool*
    - Creates type-safe page objects
    - Uses optimal selectors (getByRole, getByLabel)
    - Adds TypeScript types
    - Implements reusable methods

AI: "✅ Page objects created!
     - tests/pages/LoginPage.ts
     - tests/pages/DashboardPage.ts
     - tests/pages/ProfilePage.ts
     All use accessible selectors and TypeScript."

Step 5: Implement Tests

You: "Implement the test suite"

AI: *Calls implement-test-suite tool*
    - Writes complete test files
    - Adds proper assertions and error handling
    - Verifies parallel execution
    - Optimizes performance

AI: "✅ Test suite complete!
     - Created 19 tests across 4 suites
     - All tests pass ✓
     - Average execution: 12s (parallel)
     - 100% of tests use page objects
     Run: npx playwright test"

What Gets Created

The wizard creates a complete test infrastructure in your project:

your-app/
├── .playwright-wizard-mcp/     # Workflow documentation
│   ├── project-config.md       # Tech stack analysis
│   ├── pages.md                # Page inventory
│   ├── selector-strategy.md    # Selector approach
│   └── test-plan.md            # Test scenarios
├── tests/
│   ├── pages/                  # Page object models
│   │   ├── LoginPage.ts
│   │   ├── DashboardPage.ts
│   │   └── ProfilePage.ts
│   ├── fixtures/               # Custom fixtures
│   │   └── authFixture.ts
│   ├── helpers/                # Test utilities
│   │   └── testHelpers.ts
│   ├── auth.spec.ts           # Test files
│   ├── dashboard.spec.ts
│   └── profile.spec.ts
└── playwright.config.ts        # Playwright configuration

Next Steps

After completing the core workflow, consider:

• Add CI/CD: "Set up GitHub Actions for automated testing"
• Add accessibility testing: "Add axe-core accessibility testing"
• Add API testing: "Help me test my REST API alongside UI tests"
• Optimize performance: "Show me advanced optimization patterns"

How It Works

When you ask Copilot to help with Playwright testing:

1. You: "Help me analyze my app for testing"
2. Copilot: Calls the analyze-app tool
3. Tool: Returns detailed instructions to Copilot
4. Copilot: Executes the instructions (detects stack, browses pages, creates files)
5. You see: "✅ Analysis complete! Created project-config.md, pages.md..."

You see results, not prompts. The tools provide Copilot with expert-level instructions that it follows automatically.

Example Workflow

# In your app project, ask Copilot:
"Help me set up Playwright testing for this app"

# Copilot will:
# 1. Call analyze-app → detect stack, browse pages
# 2. Call generate-test-plan → create test scenarios
# 3. Call setup-infrastructure → create config and fixtures
# 4. Call generate-page-objects → create page models
# 5. Call implement-test-suite → write actual tests

All workflow documentation files are created in .playwright-wizard-mcp/ folder in your project root:

• project-config.md - Detected tech stack
• pages.md - Page analysis with DOM quality scores
• selector-strategy.md - Selector approach per page
• test-plan.md - Test suites with progress tracking

Note: The .playwright-wizard-mcp/ folder is for workflow tracking only. You may want to add it to .gitignore.

Tools

• get-architecture - Get the prompt architecture documentation

Requirements

• Node.js >= 18
• MCP-compatible client (GitHub Copilot, Claude Desktop, Cline, etc.)

Development

# Clone the repository
git clone https://github.com/oguzc/playwright-wizard-mcp.git
cd playwright-wizard-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT