Playwright MCP - 代理项目

该项目结合了Playwright与MCP（模型上下文协议）以实现Web系统的自动化测试。

🚀 配置

预备条件

• Node.js 18+
• npm 或 yarn

安装

# 安装依赖
npm install

# 安装Playwright浏览器
npm run install:browsers

# 设置环境变量
cp .env.example .env
# 编辑.env文件并填写您的凭证

🔐 环境变量配置

1. 复制示例文件：

cp .env.example .env

2. 编辑.env文件并填写您的凭证：

# 当前环境（HML或PROD）
ENVIRONMENT=HML

# 各环境的URL
NEMESYS_URL_HML=
NEMESYS_URL_PROD=

# HML环境凭证
NEMESYS_USER_HML=你的HML用户名
NEMESYS_PASSWORD_HML=你的HML密码

# PROD环境凭证
NEMESYS_USER_PROD=你的PROD用户名
NEMESYS_PASSWORD_PROD=你的PROD密码

3. ⚠️ 重要：

• .env文件在.gitignore中，不会被提交到仓库
• 这可以保护您的敏感凭证
• 使用.env.example作为模板

4. 切换环境：

# 在.env文件中编辑ENVIRONMENT
ENVIRONMENT=HML  # 或PROD

# 或通过命令行设置
ENVIRONMENT=PROD npm test

🧪 执行测试

可用命令

# 执行所有测试
npm test

# 执行带有界面的测试
npm run test:ui

# 执行调试模式的测试
npm run test:debug

# 执行带有可见浏览器的测试
npm run test:headed

# 查看测试报告
npm run test:report

# 启动MCP服务器
npm run mcp:start

# 探索Angular网站并执行安全测试
npm run mcp:explore

# 根据探索生成测试
npm run mcp:generate

# 完整流程：探索+生成+执行测试
npm run mcp:run

# 执行基于指令的BDD测试
npm run mcp:bdd

# 测试地理定位配置
npm run test:geolocation

# 同时运行MCP和测试界面
npm run dev

特定测试

# 仅执行身份验证测试
npx playwright test tests/nemesys-auth.spec.js

# 仅执行MCP测试
npx playwright test tests/nemesys-mcp.spec.js

# 仅执行BDD和MCP测试
npx playwright test tests/nemesys-bdd-mcp.spec.js

# 仅执行自动生成的测试
npx playwright test tests/auto-generated-tests.spec.js

# 在特定环境中执行
NODE_ENV=prod npx playwright test

📁 项目结构

playwright-mcp/
├── config.js                 # 项目配置
├── global-setup.js           # 测试全局设置
├── mcp-server.js             # MCP服务器
├── playwright.config.js      # Playwright配置
├── package.json              # 依赖和脚本
├── tests/                    # 测试
│   ├── nemesys-auth.spec.js      # 身份验证测试
│   ├── nemesys-mcp.spec.js       # MCP测试
│   ├── nemesys-bdd-mcp.spec.js   # BDD和MCP测试
│   └── auto-generated-tests.spec.js # 自动生成的测试
├── screenshots/              # 测试截图
├── test-results/             # 测试报告
└── README.md                 # 此文件

🌍 地理定位配置

项目包括特定配置以模拟巴西用户并绕过NEMESYS的地理位置限制：

• 坐标：圣保罗(-23.5505, -46.6333)
• 时区：America/Sao_Paulo
• 语言：pt-BR
• User Agent：巴西Chrome Windows
• 权限：启用地理定位

地理定位测试

npm run test:geolocation

此命令检查配置是否有效，并确认登录字段是否可用。

🤖 自动化测试生成MCP

MCP系统现在包括一个自动场景生成器，它：

🔍 自动站点分析

• 自动探索NEMESYS网站
• 识别表单、按钮、链接和输入字段
• 映射导航结构
• 生成详细的分析报告

🧪 生成测试场景

• 导航：测试链接和页面间的导航
• 表单：测试表单的填充和提交
• 按钮：测试按钮交互
• 输入字段：测试字段验证
• 响应性：测试不同屏幕分辨率

🚀 执行测试

• 连续测试：按顺序执行所有场景
• 独立测试：每个测试单独打开和关闭浏览器
• 自动截图：捕获每一步的证据
• 详细报告：生成包含结果的JSON报告

🎯 高级全面探索

🔍 高级MCP探索器

• 全面映射：登录后探索网站的所有功能
• 菜单分析：测试所有菜单和导航链接
• 表单验证：使用随机的巴西数据测试表单
• 消息检测：识别成功、错误和警告消息
• 模态分析：检测并测试模态框和弹出窗口
• 随机数据：使用真实的巴西数据（CPF、电话、地址）

⚡ 针对Angular的安全探索

🔍 优化的MCP探索器

• Angular检测：自动识别Angular网站
• 侧边栏菜单：专门探索Angular侧边栏菜单
• SPA导航：测试单页应用的导航
• Angular表单：测试反应式和模板驱动的表单
• Angular路由：检测并测试Angular路由
• 组件：识别Angular组件
• 等待Angular：等待Angular框架完全加载
• HTML/XML报告：为Azure DevOps生成报告
• BDD系统：执行基于自然语言指令的测试
• Azure管道：在HML和PROD上执行测试并生成综合报告

🧪 测试场景

• 侧边栏菜单导航：测试所有侧边栏菜单项
• Angular表单：测试由菜单打开的表单
• 子菜单：测试子菜单导航
• Angular消息：测试Angular的消息和通知
• Angular路由：测试Angular路由导航

🧪 全面生成的场景

• 完整导航：测试所有菜单和链接
• 表单验证：使用有效和无效的数据测试
• 必填字段：测试必填字段验证
• 系统消息：测试消息显示
• 模态和弹出窗口：测试模态框和弹出窗口的打开和关闭
• 响应性：在四种不同的分辨率下测试

📊 真实测试数据

• 姓名：常见的巴西名字
• 电子邮件：有效的巴西电子邮件
• 电话：巴西电话号码
• CPF：用于测试的有效CPF
• 地址：巴西地址
• 公司：巴西公司的名称

🔍 MCP功能

MCP服务器提供以下工具：

• navigate_to_url：导航到指定的URL
• click_element：点击页面上的元素
• fill_input：填充输入字段
• get_page_content：获取当前页面的内容
• take_screenshot：对页面进行截图
• wait_for_element：等待元素出现在页面上

🎯 实现的测试

1. 身份验证测试 (nemesys-auth.spec.js)

• ✅ 使用有效凭证登录
• ✅ 测试无效凭证
• ✅ 登录后的导航
• ✅ 验证仪表盘元素

2. MCP测试 (nemesys-mcp.spec.js)

• ✅ 通过MCP命令自动化
• ✅ 测试特定功能
• ✅ 生成测试报告
• ✅ 自动截图

3. BDD和MCP测试 (nemesys-bdd-mcp.spec.js)

• ✅ 组织良好且灵活的BDD场景
• ✅ 可重用的MCP命令
• ✅ 10个预定义的测试场景
• ✅ 辅助函数用于登录和导航
• ✅ 表单、按钮、表格和响应性的测试
• ✅ 必填字段验证
• ✅ 消息和通知的测试
• ✅ 模态框和弹出窗口的测试

4. 自动生成的测试 (auto-generated-tests.spec.js)

• ✅ 针对Angular网站的特定探索
• ✅ Angular侧边栏菜单测试
• ✅ 单页应用(SPA)导航测试
• ✅ Angular表单测试
• ✅ Angular子菜单测试
• ✅ Angular消息测试
• ✅ Angular路由测试
• ✅ 等待Angular框架加载

🎭 行为驱动开发(BDD)系统

📋 BDD指令

MCP系统支持基于自然语言指令的测试执行：

# 执行BDD测试
npm run mcp:bdd

📝 指令格式

指令定义在bdd-instructions.txt文件中：

# 导航
CLICK: .sidebar-menu-item:Users
CLICK: .submenu-item:Register User
WAIT: 2000

# 表单
FILL: input[name="name"]:João Silva
FILL: input[name="email"]:joao@email.com
SELECT: select[name="role"]:Administrator
CLICK: button[type="submit"]

# 验证
VERIFY: .success-message:User registered successfully
VERIFY: .error-message
VERIFY: input[name="email"]:invalid

# 截图
SCREENSHOT: user-registered.png

🎯 支持的操作

• CLICK：点击元素
• FILL：填充字段
• SELECT：选择选项
• CHECK：勾选/取消勾选复选框
• VERIFY：验证状态或文本
• NAVIGATE：导航到URL
• REFRESH：刷新页面
• BACK/FORWARD：浏览器导航
• WAIT：等待特定时间
• WAIT_FOR：等待元素出现/消失
• SCREENSHOT：截取屏幕

🚀 Azure DevOps管道

📋 管道配置

管道配置在一个文件中：

• azure-pipelines.yml：完整的管道，执行所有测试

🎯 完整管道：

• ✅ 变量已配置在文件中
• ✅ 无需在Azure DevOps中配置变量
• ✅ 在单一管道中执行所有测试：
  • HML测试
  • PROD测试（仅限main分支）
• ✅ 综合报告所有测试
• ✅ 立即生效无需额外配置

📋 管道步骤：

1. 构建：安装依赖并准备环境
2. HML测试：在测试环境中执行测试
3. PROD测试：在生产环境中执行测试（仅限main分支）
4. 报告：整合所有报告

🎯 管道步骤

• ✅ 构建和准备：安装Node.js、Playwright和依赖
• ✅ HML测试：探索和测试测试环境
• ✅ PROD测试：在生产环境中执行测试（仅限main分支）
• ✅ 综合报告：生成HTML和XML报告
• ✅ 工件：提供下载报告

📊 Azure中的报告

• HTML：交互式的视觉报告
• XML：Azure DevOps兼容的JUnit报告
• 截图：测试的视觉证据
• 指标：通过/失败场景的图表
• 下载：所有报告均可下载

📊 报告

测试生成多种格式的报告：

• HTML：交互式的视觉报告
• JSON：结构化的数据分析
• JUnit：CI/CD兼容
• 截图：自动截图

🔧 高级配置

超时

• 操作：30秒
• 导航：30秒
• 元素：10秒

支持的浏览器

• Chrome/Chromium
• Firefox
• Safari/WebKit
• Edge
• 移动版Chrome
• 移动版Safari

执行模式

• 无头模式：后台执行
• 有头模式：带界面执行
• 调试模式：调试模式
• UI模式：交互式界面

🚨 故障排除

常见问题

1. 连接错误

   • 检查NEMESYS的URL是否可访问
   • 确认config.js中的凭证

2. 登录字段不可用

   • 执行npm run test:geolocation以检查地理定位
   • 确认地理定位配置正确
   • 网站可能更改了位置验证

3. 找不到元素

   • 测试使用多个选择器以提高兼容性
   • 检查页面结构是否有变化

4. 测试超时

   • 在playwright.config.js中增加超时时间
   • 检查连接速度

日志和调试

# 以详细日志执行
DEBUG=pw:api npm test

# 以调试模式执行
npm run test:debug

📝 贡献

要添加新的测试：

1. 在tests/目录下创建新文件
2. 使用*.spec.js命名规则
3. 导入config.js中的配置
4. 遵循现有的命名规范

📄 许可

MIT许可 - 详情参见LICENSE文件。

🆘 支持

对于疑问或问题：

1. 检查错误日志
2. 查阅Playwright文档
3. 检查NEMESYS配置
4. 联系开发团队