playwright-generate-mcp

一个企业级的模型上下文协议（MCP）服务器，使 AI 编码助手（Cursor、Claude Desktop、Antigravity、Roo Code 等）能够生成、评分、运行并自动修复健壮、可维护且抗不稳定的 Playwright E2E 测试。

它强制实施领域驱动的页面对象模型（POM）架构，提供跨文件质量评分，提取丰富的单轮失败诊断，并遵循严格的Web 优先的反不稳定规则。

✨ 核心功能

• 🏗️ 领域驱动 POM 架构：在声明式 Spec、页面对象、自定义 Fixtures 和动态数据工厂之间强制执行关注点分离。

• 🔍 跨文件 POM 质量评分：score_test_quality 和 run_playwright_test 会自动遍历导入依赖关系（.spec.ts $\rightarrow$ .fixture.ts $\rightarrow$ *.page.ts / *.component.ts），对所有相关文件中的定位器和反模式进行评分。

• ⚡ 单轮丰富诊断：当测试失败时，run_playwright_test 会在单轮内立即返回确切的文件及行号位置、错误类别、失败前最后 3–5 个操作步骤、浏览器控制台日志、失败的 HTTP 请求（4xx/5xx）以及截图路径。

• 🛡️ 严格的反不稳定规则：检测并不鼓励随意的 sleep（waitForTimeout、setTimeout）、未 await 的操作、networkidle 依赖和手动文本提取，转而推荐 Web 优先的自动重试断言。

• 🧭 无状态根目录自动发现：自动遍历父目录以发现 playwright.config.{ts,js,mjs,cjs,mts,cts}，无需手动配置路径。

• 💬 自适应交互式确认：在应用测试修复之前，支持交互式 UI 弹窗（ask_question、vscode_askQuestions）或格式化的编号列表。

Related MCP server: Limetest MCP Server

📁 架构标准

该 MCP 引导 AI 智能体按照清晰的领域驱动层级结构来组织测试：

tests/e2e/
├── domain/                      # Grouped by business features
│   └── {feature}/
│       ├── pages/               # Page Objects / Component Objects
│       │   └── {step}.page.ts
│       └── {feature}.fixture.ts # Custom Fixture injecting Page Objects & Data
├── factory/                     # Dynamic test data builders
│   └── {entity}.factory.ts      # Unique data per run (timestamp / Faker)
└── specs/                       # Declarative, readable test specs
    └── {feature}.spec.ts

核心设计规则

1. 严格分离：*.spec.ts 文件中不得出现原始定位器或直接 DOM 操作。所有 UI 交互都位于页面/组件对象中。

2. 自定义 Fixtures：使用 test.extend<Fixtures>() 注入页面对象和测试数据，而不是在 spec 中手动实例化 new Page()。

3. 动态数据工厂：每次运行生成唯一的测试数据，以防止测试重跑时发生数据库唯一约束冲突。

4. 语义化定位器：优先使用 getByRole > getByLabel / getByPlaceholder > getByText > getByTestId。严格禁止深层嵌套的 CSS（div > div > span）。

5. 标签约定：

   • @smoke：关键快乐路径。

   • @regression：全面的用户流程。

   • @ui：使用 page.route() 拦截并模拟 API 响应的纯 UI/前端测试。

   • @integration：针对真实后端 API 进行验证的测试。

🛠️ MCP 工具

📋 MCP 提示词

• playwright_e2e_workflow：完整的端到端提示词，指导 AI 智能体掌握领域驱动 POM 架构、代码生成顺序（步骤 A 到步骤 E）、严格的反不稳定编写规则、单轮诊断以及安全的修复工作流。

🚀 安装与设置

1. 从源码构建

git clone https://github.com/your-username/playwright-generate-mcp.git
cd playwright-generate-mcp
npm install
npm run build

2. 配置 MCP 客户端

将服务器添加到你的 MCP 配置文件中（例如 claude_desktop_config.json、Cursor Settings 或 Antigravity MCP 设置）：

{
  "mcpServers": {
    "playwright-generate": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-generate-mcp/dist/index.js"]
    }
  }
}

或者当发布到 NPM 时：

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

🧑💻 开发

npm run dev     # tsx watch mode
npm run build   # Compile TypeScript to dist/
npm start       # Run compiled MCP server

📄 许可证

MIT