VibeShift Web 测试器

该项目提供了一个由 AI 驱动的代理，旨在简化网页测试工作流程，特别是对于使用像 GitHub Copilot、Cursor、Roo Code 等 AI 编码助手的开发者。它通过 MCP（机器命令协议） 直接集成到这些助手中，允许您使用自然语言提示来自动化测试录制、执行和发现。

问题： 在使用 AI 助手生成代码后手动测试网页应用程序既耗时又容易出错。此外，AI 驱动的代码更改可能会无意中在之前正常工作的功能中引入回归。

解决方案： 该工具通过使您的 AI 编码助手能够：

1. 录制新的测试流程： 用自然语言描述用户旅程，代理将在 AI 指导下与浏览器（使用 Playwright）交互以生成可重现的测试脚本（JSON 格式）。
2. 执行现有测试： 运行先前记录的测试脚本来进行回归测试，确保新代码更改没有破坏现有的功能。
3. 发现潜在的测试步骤： 爬取网站，分析页面的视觉效果和 DOM 结构，并让大型语言模型 (LLM) 建议不同页面的相关测试步骤。

这创建了一个更紧密的反馈循环，自动化了测试过程，使得 AI 助手（以及开发者）可以快速识别并修复问题或回归。

演示（点击播放视频）

特性

• MCP 集成： 无缝集成 Cursor/Windsurf/GitHub Copilot/Roo Code
• AI 辅助测试录制： 从自然语言描述生成基于 Playwright 的测试脚本（自动模式下）。
• 确定性测试执行： 使用 Playwright 可靠地运行已记录的 JSON 测试文件。
• AI 驱动的测试发现： 爬取网站，并利用任何 LLM（符合 openai 格式）为发现的页面建议测试步骤。
• 回归测试： 轻松运行现有测试套件以捕获回归。
• 自动化反馈循环： 执行结果（包括失败情况、截图、控制台日志）被返回，直接向 AI 助手提供反馈。
• 自我修复： 如果代码发生变化，现有测试会自我修复。无需手动更新。
• UI 测试： 支持 Playwright 不直接支持的 UI 测试。例如，“检查文本是否在 div 中溢出”。
• 视觉回归测试： 使用传统的 pixelmatch 和视觉 LLM 方法。

工作原理

+-------------+ +-----------------+ +---------------------+ +-----------------+ +---------+ | 用户 | ----> | AI 编码代理 | ----> | MCP 服务器 | ----> | Web 测试代理 | ----> | 浏览器 | | （开发者） | | （如 Copilot） | | （mcp_server.py） | | （agent/executor）| | （Playwright）| +-------------+ +-----------------+ +---------------------+ +-----------------+ +---------+ ^ | | | |--------------------------------------------------+----------------------------+---------------------+ [测试结果 / 反馈]

1. 用户： 向其 AI 编码助手发出指令（例如，“为登录流程录制一个测试”，“运行回归测试 test_login.json”）。
2. AI 编码代理： 识别意图并通过 MCP 调用 MCP 服务器 提供的相应工具。
3. MCP 服务器： 将请求路由到相应的函数 (record_test_flow, run_regression_test, discover_test_flows, list_recorded_tests)。
4. Web 测试代理：* 录制: WebAgent（在自动模式下）与LLM交互以规划步骤，通过BrowserController（Playwright）控制浏览器，处理HTML/视觉信息，并将生成的测试步骤保存到output/目录下的JSON文件中。

• 执行: TestExecutor加载指定的JSON测试文件，使用BrowserController根据记录的步骤与浏览器进行交互，并捕获结果、截图和控制台日志。
• 发现: CrawlerAgent使用BrowserController和LLMClient来爬取页面并建议测试步骤。

1. 浏览器: Playwright驱动实际的浏览器交互。
2. 反馈: 结果（成功/失败、文件路径、错误消息、发现的步骤）通过MCP服务器返回给AI编码助手，然后由其呈现给用户。

开始使用

前提条件

• Python 3.10+
• 访问任何LLM（在我的测试中，gemini 2.0 flash免费版效果最佳）
• 安装了MCP (pip install mcp[cli])
• 安装了Playwright浏览器 (playwright install)

安装

1. 克隆仓库: bash git clone <repository-url> cd <repository-name>

2. 创建虚拟环境（推荐）: bash python -m venv venv source venv/bin/activate # Linux/macOS

   venvScriptsactivate # Windows

3. 安装依赖: bash pip install -r requirements.txt

4. 安装Playwright浏览器: bash playwright install --with-deps # 安装浏览器及其操作系统依赖

配置

1. 将项目根目录中的.env.example重命名为.env文件。

2. 添加您的LLM API密钥及其他必要信息： dotenv

   .env

   LLM_API_KEY="YOUR_LLM_API_KEY"

   • 将YOUR_LLM_API_KEY替换为您的实际密钥。

添加MCP服务器

将以下内容添加到您的MCP配置中： json { "mcpServers": { "Web-QA":{ "command": "uv", "args": ["--directory","path/to/cloned_repo", "run", "mcp_server.py"] } } }

在与您的AI编码助手交互时，请保持此服务器运行。

使用方法

通过支持MCP的AI编码助手使用自然语言与代理进行交互。

示例：

• 录制测试:

  "录制一个测试：访问https://practicetestautomation.com/practice-test-login/，在用户名字段输入student，在密码字段输入Password123，点击提交按钮，并验证文本Congratulations student是否可见。"

  • (代理将自动执行这些操作并将test_....json文件保存到output/目录中)

• 执行测试:

  "运行回归测试output/test_practice_test_login_20231105_103000.json"

  • (代理将执行指定文件中的步骤，并报告PASS/FAIL状态以及错误和详细信息。)

• 发现测试步骤:

  "从https://practicetestautomation.com/practice/开始发现潜在的测试步骤。"

  • (代理将爬取站点，分析页面，并为每个页面返回建议的测试步骤。)

• 列出已录制的测试:

  "列出可用的已录制网页测试。"

  • (代理将返回output/目录中找到的.json文件列表。)

输出：

• 已录制的测试: 作为JSON文件保存在output/目录中（有关格式，请参阅test_schema.md）。
• 执行结果: 作为总结运行情况的JSON对象返回（状态、错误、证据路径）。完整的结果也保存到output/execution_result_....json。
• 发现结果: 作为包含发现的URL和建议步骤的JSON对象返回。完整的结果保存到output/discovery_results_....json。

灵感来源* Browser Use: DOM 上下文树的生成大量借鉴了他们的工作，并进行了修改以适应静态/动态/视觉元素。特别感谢他们对开源社区的贡献。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解如何开始、报告问题以及提交拉取请求的详细信息。

许可证

本项目根据 APACHE-2.0 许可证发布。