# VibeShift 测试助手
## 基本信息
- Slug: `ilikepizza2-vibeshift`
- Source: modelscope
- Publisher: @Ilikepizza2/VibeShift
- Categories: testing-and-qa-tools / app-automation / code-execution
- Hosted: No
- License: Apache License 2.0
- Source URL: https://www.modelscope.cn/mcp/servers/@Ilikepizza2/VibeShift
## 简介
由AI驱动的代理，通过允许开发人员在其AI编码助手中介使用自然语言提示来记录、执行和发现测试，从而简化网页测试工作流程。
## MCP Server 详情

# VibeShift Web 测试器

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

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

**解决方案：** 该工具通过使您的 AI 编码助手能够执行以下操作来弥合这一差距：

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

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

# 演示（点击播放视频）
[![点击播放](https://img.youtube.com/vi/wCbCUCqjnXQ/maxresdefault.jpg)](https://youtu.be/wCbCUCqjnXQ)
[![完整开发过程](https://img.youtube.com/vi/D5yeIS-0Ui4/maxresdefault.jpg)](https://youtu.be/D5yeIS-0Ui4)

## 特性

*   **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`来爬取页面并建议测试步骤。
5.  **浏览器:** Playwright驱动实际的浏览器交互。
6.  **反馈:** 结果（成功/失败、文件路径、错误消息、发现的步骤）通过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](https://github.com/browser-use/browser-use/)**: DOM 上下文树的生成深受他们的启发，并进行了修改以适应静态/动态/视觉元素。特别感谢他们对开源的贡献。

## 贡献

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

## 许可证

本项目根据 [APACHE-2.0](LICENSE) 许可证发布。