Playwright Wizard MCP

🚀 Playwright Wizard MCP Server

🧙‍♂️ Playwright Wizard MCP Server 是一个智能的模型上下文协议（MCP）服务器，它能引导你按照最佳实践创建专业的 Playwright 测试套件。

🚀 快速开始

Playwright Wizard MCP 为构建全面的端到端（E2E）测试套件提供了一种结构化、循序渐进的方法。无需从头开始或复制样板代码，这个 MCP 服务器会通过针对你应用程序量身定制的智能提示，引导你遵循行业最佳实践。

✨ 主要特性

• 🧙‍♂️ 循序渐进的向导式工作流：用于创建全面的测试套件。
• 📚 全面的提示信息：涵盖分析、规划、设置和实施等环节。
• 🎯 最佳实践指导：涉及选择器、测试夹具和并行执行等方面。
• 🔧 可选的功能增强：用于辅助功能和 API 测试。
• 📖 参考文档支持：提供高级模式的参考资料。
• 🌐 MCP 注册表集成：便于发现和安装。

📦 安装指南

快速开始（推荐）

无需安装！使用 npx 按需运行服务器：

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

这种方式会自动使用最新版本，无需管理本地安装。

全局安装

若要实现更快的启动速度和离线使用，可以进行全局安装：

npm install -g playwright-wizard-mcp

然后在不使用 npx 的情况下进行配置：

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

从 MCP 注册表安装

该项目也可在官方 MCP 注册表 中找到，方便发现和安装。

📚 详细文档

配置说明

GitHub Copilot（VS Code）

1. 打开你的 MCP 配置文件：
   • macOS：~/Library/Application Support/Code/User/mcp.json
   • Windows：%APPDATA%\Code\User\mcp.json
2. 添加服务器配置：

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

3. 重启 VS Code 或重新加载窗口（Cmd/Ctrl + Shift + P → "Developer: Reload Window"）
4. 打开 GitHub Copilot 聊天窗口，验证工具是否可用

Claude Desktop

1. 打开你的配置文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 添加服务器配置：

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

3. 重启 Claude Desktop
4. 打开新聊天窗口时，通过查看 🔨 工具图标来验证安装是否成功

Cline（VS Code）

1. 打开 VS Code
2. 进入 Cline 设置（Cmd/Ctrl + Shift + P → "Cline: Open MCP Settings"）
3. 添加服务器配置：

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

4. 重启 VS Code
5. 在 Cline 的可用工具列表中查找 Playwright Wizard 工具

可用工具

Playwright Wizard 提供了 15 种工具，分为核心工作流、可选增强功能和参考文档三类。

核心工作流（按顺序完成）

这 5 种工具将引导你创建一个完整的、可用于生产环境的测试套件：

可选增强功能

在完成核心工作流后，可以添加以下功能：

参考文档

可随时访问这些文档以获取更多上下文和模式：

工具使用方法

只需要求你的 AI 助手使用这些工具即可：

"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"

AI 将调用相应的工具，接收详细的指令并自动执行。你将看到结果（创建的文件、完成的分析），而无需查看内部指令。

开始使用

首次设置（5 分钟）

1. 安装并配置 MCP 服务器（请参阅上面的 配置说明）
2. 重启你的 AI 客户端（Claude Desktop 或 VS Code）
3. 验证安装：打开新的聊天窗口，查看是否有 🔨 工具图标

创建第一个测试套件（30 - 60 分钟）

以下是典型的工作流程： 步骤 1：分析你的应用程序

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."

步骤 2：生成测试计划

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."

步骤 3：设置基础设施

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!"

步骤 4：生成页面对象

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."

步骤 5：实现测试套件

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"

创建内容

向导会在你的项目中创建一个完整的测试基础设施：

your-app/
├── .playwright-wizard-mcp/     # 工作流文档
│   ├── project-config.md       # 技术栈分析
│   ├── pages.md                # 页面清单
│   ├── selector-strategy.md    # 选择器方法
│   └── test-plan.md            # 测试场景
├── tests/
│   ├── pages/                  # 页面对象模型
│   │   ├── LoginPage.ts
│   │   ├── DashboardPage.ts
│   │   └── ProfilePage.ts
│   ├── fixtures/               # 自定义测试夹具
│   │   └── authFixture.ts
│   ├── helpers/                # 测试实用工具
│   │   └── testHelpers.ts
│   ├── auth.spec.ts           # 测试文件
│   ├── dashboard.spec.ts
│   └── profile.spec.ts
└── playwright.config.ts        # Playwright 配置

后续步骤

完成核心工作流后，可以考虑以下操作：

• 添加 CI/CD："Set up GitHub Actions for automated testing"
• 添加辅助功能测试："Add axe-core accessibility testing"
• 添加 API 测试："Help me test my REST API alongside UI tests"
• 优化性能："Show me advanced optimization patterns"

工作原理

当你请求 Copilot 帮助进行 Playwright 测试时：

1. 你："Help me analyze my app for testing"
2. Copilot：调用 analyze-app 工具
3. 工具：向 Copilot 返回详细指令
4. Copilot：执行指令（检测技术栈、浏览页面、创建文件）
5. 你看到："✅ Analysis complete! Created project-config.md, pages.md..."

你看到的是结果，而不是指令。 这些工具为 Copilot 提供了专家级的指令，Copilot 会自动执行这些指令。

示例工作流

# 在你的应用项目中，向 Copilot 发出请求：
"Help me set up Playwright testing for this app"

# Copilot 将执行以下操作：
# 1. 调用 analyze-app → 检测技术栈、浏览页面
# 2. 调用 generate-test-plan → 创建测试场景
# 3. 调用 setup-infrastructure → 创建配置和测试夹具
# 4. 调用 generate-page-objects → 创建页面对象模型
# 5. 调用 implement-test-suite → 编写实际测试代码

所有工作流文档文件都将创建在项目根目录下的 .playwright-wizard-mcp/ 文件夹中：

• project-config.md - 检测到的技术栈
• pages.md - 带有 DOM 质量评分的页面分析
• selector-strategy.md - 每个页面的选择器方法
• test-plan.md - 带有进度跟踪的测试套件

注意： .playwright-wizard-mcp/ 文件夹仅用于工作流跟踪。你可能需要将其添加到 .gitignore 中。

其他工具

• get-architecture - 获取提示架构文档

🔧 技术细节

要求

• Node.js >= 18
• 兼容 MCP 的客户端（GitHub Copilot、Claude Desktop、Cline 等）

开发

# 克隆仓库
git clone https://github.com/oguzc/playwright-wizard-mcp.git
cd playwright-wizard-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 在开发模式下运行
npm run dev

📄 许可证

本项目采用 MIT 许可证。欢迎贡献代码！请提交问题或拉取请求。