内容
# Playwright MCP 服务器 v6
## 智能 Playwright + MCP + BDD 自动化框架生成器
一个生产就绪的基于 Java 的模型上下文协议（MCP）服务器，通过 Playwright Java 连接大型语言模型（LLM）和实时 Chromium 浏览器。
该框架记录真实的浏览器交互，分析用户意图，生成可维护的 BDD 自动化框架，支持智能回放和恢复，并为 AI 代理提供原子浏览器工具。
---
# 目录
1. 概述
2. 主要功能
3. 架构
4. 核心组件
5. 技术栈
6. 前提条件
7. 安装和设置
8. MCP 集成
9. 暴露的 MCP 工具
10. 智能等待引擎
11. 意图分析引擎
12. 智能 BDD 生成
13. 生成的框架结构
14. UiActions 抽象层
15. 定位策略
16. 并行回放支持
17. 故障恢复系统
18. 支持的浏览器操作
19. 环境变量
20. 构建和运行
21. 示例工作流程
22. 示例录制 JSON
23. 故障排除指南
24. 性能和设计决策
25. 安全考虑
26. 未来增强功能
27. 最佳实践
28. 常见问题
29. 许可证
---
# 概述
Playwright MCP 服务器是一个智能自动化编排层，使大型语言模型（LLM）能够：
* 启动和控制浏览器
* 记录用户交互
* 可靠地回放工作流程
* 生成企业级 BDD 框架
* 执行原子浏览器操作
* 分析原始浏览器事件为业务意图
* 自动创建可重用的页面对象模型
该框架针对以下方面进行了优化：
* AI 辅助 QA 自动化
* 自愈浏览器交互
* 意图驱动的 BDD 生成
* 框架无关的自动化设计
* 并行执行
* 企业自动化可扩展性
---
# 主要功能
## 浏览器记录引擎
* 记录点击、填充、导航、按键、上传、下拉和滚动
* 自动捕获语义定位器
* 支持有头和无头执行
* CSP 绕过支持
* 智能事件去重
* 基于会话的记录管理
## 智能等待引擎（v6）
在每个操作之前和之后自动同步：
* DOM 就绪检查
* 网络空闲检测
* 元素可见性验证
* 启用状态验证
* DOM 稳定逻辑
* 操作感知等待
## 意图分析器
将原始 DOM 事件转换为业务级意图：
| 原始事件 | 检测意图 |
| --------------------------------- | --------------- |
| 用户名 + 密码 + 登录点击 | 登录 |
| 搜索填充 + 回车 | 搜索 |
| 多个表单字段 + 提交 | 表单提交 |
| 金额 + 转账按钮 | 转账 |
| 上传 + 确认 | 上传流程 |
| 下拉 + 确认 | 选择流程 |
## 智能 BDD 生成器
自动生成：
* 特性文件
* 步骤定义
* 页面对象
* 运行器类
* UiActions 抽象层
* Playwright 实现层
* 场景大纲
* 数据驱动的示例
## 并行回放引擎
* ThreadLocal Playwright 会话
* 多线程回放
* 基于块的事件分发
* 隔离的浏览器上下文
* 并行执行支持
## 恢复和故障处理
* 故障时捕获截图
* 生成 HTML 转储
* 自动 DOM 重新同步
* URL 验证
* 重试引擎
* 智能恢复处理
## 框架抽象层
生成的框架使用：
```java
ui.click(locator);
ui.fill(locator, value);
ui.navigate(url);
```
这使得未来可以迁移到：
* Selenium
* Cypress
* WebDriverIO
* Appium
* 任意 UI 引擎
而无需更改页面对象。
---
# 架构
```text
┌─────────────────────────────────────────────────────────────┐
│ MCP HOST / LLM │
│ Claude / Cursor / Cline / 自定义 AI 代理 │
└──────────────────────┬──────────────────────────────────────┘
│
JSON-RPC over stdio
│
┌──────────────────────▼──────────────────────────────────────┐
│ Playwright MCP 服务器 │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ MCP 工具层 │ │
│ │ │ │
│ │ start_recording │ │
│ │ stop_recording │ │
│ │ playback_recording │ │
│ │ generate_playwright_bdd │ │
│ │ execute_atomic_action │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 意图分析引擎 │ │
│ │ │ │
│ │ 登录 │ │
│ │ 搜索 │ │
│ │ 表单提交 │ │
│ │ 转账 │ │
│ │ 原始操作 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 智能等待引擎 │ │
│ │ │ │
│ │ DOM 就绪 │ │
│ │ 网络空闲 │ │
│ │ 元素可见性 │ │
│ │ 启用状态 │ │
│ │ DOM 稳定 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ BDD 代码生成器 │ │
│ │ │ │
│ │ 特性文件 │ │
│ │ 步骤定义 │ │
│ │ 页面对象 │ │
│ │ 运行器 │ │
│ │ UiActions │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────┐
│ Playwright Java │
│ Chromium 浏览器 │
└─────────────────────────────────────────────────────────────┘
```
---
# 核心组件
## 1. PlaywrightMcpServer.java
主要编排引擎，负责：
* MCP 工具注册
* 浏览器生命周期管理
* 事件记录
* 回放执行
* 智能等待
* 重试处理
* 并行执行
* 故障恢复
* 会话管理
## 2. IntentAnalyzer.java
将低级浏览器事件转换为有意义的业务操作。
### 支持的意图类型
| 意图 | 描述 |
| ----------- | ---------------------------- |
| 登录 | 用户身份验证流程 |
| 搜索 | 搜索交互流程 |
| 转账 | 货币/数据传输流程 |
| 表单提交 | 通用表单提交 |
| 导航 | URL 导航 |
| 选择流程 | 下拉选择流程 |
| 上传流程 | 文件上传流程 |
| 原始操作 | 未匹配的单个操作 |
## 3. BddCodeGenerator.java
生成完整的自动化框架。
### 生成的工件
* 特性文件
* 步骤定义
* 页面对象
* 运行器类
* UiActions 接口
* Playwright 实现
* 数据驱动场景
* 断言
* 实用方法
---
# 技术栈
| 类别 | 技术 |
| ------------------ | ---------------------------- |
| 语言 | Java 17+ |
| 构建工具 | Maven |
| 浏览器自动化 | Playwright Java |
| BDD 框架 | Cucumber |
| MCP 协议 | 模型上下文协议 |
| JSON 处理 | Jackson |
| 报告 | Allure + Cucumber 报告 |
| 并行执行 | Java 执行器 + ThreadLocal |
| 浏览器 | Chromium |
| 日志 | java.util.logging |
---
# 前提条件
| 工具 | 版本 |
| ------- | ----------------------- |
| JDK | 17+ |
| Maven | 3.9+ |
| Node.js | 可选 |
| 操作系统 | Windows / Linux / macOS |
| 内存 | 推荐 8 GB |
---
# 安装和设置
## 1. 克隆仓库
```bash
git clone <仓库 URL>
cd playwright-mcp-server
```
## 2. 构建项目
```bash
mvn clean package -DskipTests
```
## 3. 安装 Playwright 浏览器
```bash
mvn exec:java@install-browsers
```
## 4. 验证构建
生成 JAR：
```text
target/playwright-mcp-server.jar
```
---
# MCP 集成
## Claude 桌面配置
### macOS
```text
~/Library/Application Support/Claude/claude_desktop_config.json
```
### Windows
```text
%APPDATA%\Claude\claude_desktop_config.json
```
### 示例配置
```json
{
"mcpServers": {
"playwright": {
"command": "java",
"args": [
"-jar",
"/绝对路径/to/playwright-mcp-server.jar"
]
}
}
}
```
配置后重启 Claude 桌面。
---
# 暴露的 MCP 工具
# 1. start_recording
启动 Chromium 并开始交互记录。
## 输入
```json
{
"url": "https://example.com",
"sessionName": "登录流程",
"headless": false
}
```
## 功能
* CSP 绕过
* JS 注入
* 浏览器生命周期管理
* 事件队列设置
* 会话元数据生成
---
# 2. stop_recording
停止记录并返回结构化 JSON。
## 输入
```json
{}
```
## 输出
* 原始浏览器事件
* 结构化意图
* 会话元数据
* 时间数据
* 记录统计
---
# 3. playback_recording
智能回放记录的事件。
## 输入
```json
{
"jsonRecording": "...",
"headless": true,
"parallel": false,
"threads": 1
}
```
## 功能
* 智能等待
* 重试引擎
* 恢复逻辑
* 并行执行
* 故障工件生成
---
# 4. generate_playwright_bdd
生成完整的 BDD 自动化框架。
## 输入
```json
{
"jsonRecording": "...",
"featureName": "用户登录",
"framework": "cucumber",
"tags": "@smoke @regression"
}
```
## 支持的框架
| 框架 | 运行器 |
| --------- | ------------ |
| cucumber | JUnit 5 |
| testng | TestNG |
| serenity | Serenity BDD |
## 生成的文件
| 文件 | 目的 |
| ------------------- | ------------------------- |
| 特性文件 | Gherkin 场景 |
| 步骤定义 | 步骤实现 |
| 页面对象 | UI 层 |
| 运行器 | 测试执行 |
| UiActions | 抽象层 |
| PlaywrightUiActions | Playwright 实现 |
---
# 5. execute_atomic_action
执行单个 Playwright 操作。
## 示例
```json
{
"action": "fill",
"selector": "placeholder:搜索",
"value": "Playwright"
}
```
## 支持的操作
| 操作 | 描述 |
| ------------- | ---------------------- |
| 导航 | 导航到 URL |
| 点击 | 点击元素 |
| 填充 | 填充输入 |
| 类型 | 输入文本 |
| 清除 | 清除字段 |
| 按压 | 按压键盘按键 |
| 悬停 | 悬停元素 |
| 选中 | 选中复选框 |
| 取消选中 | 取消选中复选框 |
| 选择选项 | 选择下拉选项 |
| 上传文件 | 上传文件 |
| 截图 | 捕获截图 |
| 获取文本 | 提取文本 |
| 是否可见 | 可见性验证 |
| 获取 HTML | 提取 HTML |
| 等待 | 显式等待 |
| 滚动 | 滚动页面 |
---
# 智能等待引擎
智能等待引擎自动稳定浏览器状态。
## 等待策略
| 操作 | 预等待 | 后等待 |
| ------------- | ----------------- | ------------------- |
| 点击 | 可见 | 加载 + 网络空闲 |
| 填充 | 可见 + 启用 | 稳定 DOM |
| 导航 | DOM 就绪 | 网络空闲 |
| 选择选项 | 可见 | 稳定 DOM |
| 选中 | 可见 | 稳定 DOM |
| 上传文件 | 已附加 | 稳定 DOM |
## 优势
* 减少脆弱测试
* 删除硬编码等待
* 稳定异步页面
* 提高回放可靠性
---
# 意图分析引擎
意图分析器将低级浏览器操作转换为业务工作流。
## 示例
### 原始事件
```text
填充用户名
填充密码
点击登录
```
### 生成的意图
```text
登录（用户名，密码）
```
### 生成的 Gherkin
```gherkin
当用户使用“john”和“<password>”登录时
```
---
# 智能 BDD 生成
生成器创建企业级自动化框架。
## 生成的特性示例
```gherkin
@smoke @regression
特性：用户登录
背景：
Given 浏览器已打开
场景：用户登录
当用户使用“john”和“<password>”登录
```
## 生成的页面对象示例
```java
public class 登录页面 {
private final UiActions ui;
private final String 用户名字段 = "#用户名";
private final String 密码字段 = "#密码";
public 登录页面 登录(String 用户名, String 密码) {
ui.fill(用户名字段, 用户名);
ui.fill(密码字段, 密码);
return this;
}
}
```
---
# 生成的框架结构
```text
generated-project/
│
├── pom.xml
│
├── src/
│ ├── main/
│ │ └── java/com/qa/
│ │ ├── actions/
│ │ │ ├── UiActions.java
│ │ │ └── PlaywrightUiActions.java
│ │ │
│ │ └── pages/
│ │ └── 用户登录页面.java
│ │
│ └── test/
│ ├── java/com/qa/
│ │ ├── runners/
│ │ │ └── 用户登录运行器.java
│ │ │
│ │ └── stepdefs/
│ │ └── 用户登录步骤.java
│ │
│ └── resources/
│ ├── features/
│ │ └── 用户登录.feature
│ │
│ └── TestData/
│ └── testdata.properties
```
---
# UiActions 抽象层
## 目的
将页面对象与 Playwright 解耦。
## 优势
* 框架独立性
* 轻松迁移
* 清洁架构
* 更好的可维护性
* 改进的可扩展性
## 示例
```java
public interface UiActions {
void click(String selector);
void fill(String selector, String value);
void navigate(String url);
}
```
---
# 定位策略
该框架优先使用弹性语义定位器。
## 优先级顺序
| 优先级 | 定位器 |
| -------- | ------------ |
| 1 | href |
| 2 | id |
| 3 | data-testid |
| 4 | 角色 |
| 5 | 占位符 |
| 6 | 标签 |
| 7 | 文本 |
| 8 | CSS |
| 9 | nth 备用 |
## 示例
```text
角色：按钮：登录
占位符：搜索
标签：电子邮件
testid：提交按钮
```
---
# 并行回放支持
## 功能
* 多线程执行
* 线程隔离浏览器会话
* 基于块的重放
* ThreadLocal Playwright 实例
## 示例
```json
{
"parallel": true,
"threads": 4
}
```
---
# 故障恢复系统
操作失败时，框架：
1. 捕获截图
2. 转储 HTML
3. 记录故障详情
4. 验证 URL
5. 尝试 DOM 重新同步
6. 在可能的情况下继续执行
## 故障工件目录
```text
./mcp-failures/
```
生成的工件：
```text
failure.png
failure.html
failure.log
```
---
# 环境变量
| 变量 | 默认值 | 目的 |
| --------------------- | -------------- | --------------------- |
| MCP_RETRY_MAX | 3 | 重试尝试 |
| MCP_TIMEOUT_MS | 30000 | 超时配置 |
| MCP_RETRY_DELAY_MS | 800 | 重试延迟 |
| MCP_MAX_STEP_DELAY_MS | 500 | 回放节奏 |
| MCP_FAILURE_DIR | ./mcp-failures | 故障工件 |
| MCP_LOG_LEVEL | INFO | 日志级别 |
---
# 构建和运行
## 打包项目
```bash
mvn clean package
```
## 运行服务器
```bash
java -jar target/playwright-mcp-server.jar
```
## 运行生成的框架
```bash
mvn test
```
## 运行特定标签
```bash
mvn test -Dcucumber.filter.tags="@smoke"
```
---
# 示例工作流程
## 步骤 1 — 开始记录
```json
{
"url": "https://example.com"
}
```
## 步骤 2 — 执行浏览器操作
* 登录
* 搜索
* 提交表单
* 上传文件
## 步骤 3 — 停止记录
```json
{}
```
## 步骤 4 — 生成框架
```json
{
"featureName": "用户登录"
}
```
## 步骤 5 — 执行测试
```bash
mvn test
```
---
示例录制 JSON
```json
{
"schemaVersion": "6.0.0",
"sessionName": "登录测试",
"status": "已完成",
"events": [
{
"actionType": "填充",
"selector": "#username",
"inputValue": "john"
},
{
"actionType": "点击",
"selector": "#login"
}
],
"intents": [
{
"intentType": "登录",
"description": "用户登录"
}
]
}
```
---
# 故障排除指南
| 问题 | 解决方案 |
| ---------------------------- | ----------------------------------- |
| 浏览器执行文件未找到 | 运行 Playwright 浏览器安装 |
| MCP 主机断开连接 | 确保日志仅输出到 STDERR |
| 未捕获事件 | 验证 CSP 绕过 |
| 播放失败 | 增加超时值 |
| 并行回放不稳定 | 减少线程数 |
| 元素未找到 | 验证选择器策略 |
| 播放不稳定 | 启用智能等待默认值 |
| 无头模式问题 | 在有头模式下运行 |
| 权限问题 | 验证操作系统浏览器权限 |
| Chromium 崩溃 | 增加系统内存 |
## 浏览器安装
```bash
mvn exec:java@install-browsers
```
## 调试日志
```bash
export MCP_LOG_LEVEL=DEBUG
```
---
# 性能与设计决策
| 设计 | 原因 |
| ----------------------- | ----------------------------------- |
| 线程局部 Playwright | 安全的并行执行 |
| 智能等待 | 减少易变的自动化 |
| 基于意图的生成 |的 BDD |
| Ui抽象 | 框架独立 |
| 重试引擎 靠性改进 |
|绕过 | 从受限应用中捕获事件 |
| 定位符 | 更好的选择器稳定性 |
| 结构 | 非破坏性重放 |
---
# 安全考虑
*启用 CSP 绕过以进行自动化录制
* 意图会屏蔽敏感密码
* 浏览器上下文是隔离的
* 失败的工件可能包含敏感信息
* 生成的框架不应提交机密
---
# 未来增强功能
计划中的改进:
* Selenium UiActions 实现
* Firefox 和 支持
* AI 驱动愈选择器
* 引擎
* API 测试集成
* 测试影响分析
* 云执行支持
* Docker 支持
*缩放
* CI/CD
* 报告仪表板
---
# 最佳实践
## 推荐
* 使用语义定位符 优先使用角色/测试 ID 选择器
* 保持版本受控
* 将机密存储在外部
* 谨慎运行并行执行
*数据使用场景大纲
##
* 硬编码等待
* XPath 选择器
*之间共享浏览器上下文
*中存储凭证
---
# 常见问题
## 是否支持无头执行？
支持。
## 生成的框架能否独立运行？
支持。生成的项目是独立的 Maven 自动化框架。
## 是否支持并行执行？
支持。
## 可以稍后插入 Selenium 吗？
支持。UiActions 抽象是专门为此设计的。
## 框架是否支持重试？
支持。回重试和恢复逻辑。
## 我可以生成数据驱动的框架吗？
支持。场景大纲生成支持。
---
# 许可证
本项目适用于教育、企业自动化和 AI 辅助测试用例。
请添加您首选的许可证：
* MIT
* Apache 2.0
* 专有企业许可证
---
# 最后的备注
Playwright MCP Server v6 被设计为一个 AI 原生的自动化框架生成平台。
它结合了* Playwright 浏览器自动化
* MCP 协议工具
* 意图分析
* 智能同步
* 企业
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器