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 許可證。歡迎貢獻代碼！請提交問題或拉取請求。