项目简介

VibeCheck 是一个基于 Model Context Protocol (MCP) 构建的 AI 驱动的网页测试代理。它旨在通过与 AI 编码助手（如 GitHub Copilot, Cursor 等）集成，使用自然语言命令自动化执行网页测试的记录、执行和发现任务，提高开发者的测试效率。

主要功能点

与AI编码助手集成 (MCP)：通过标准的MCP协议，你的AI助手可以直接调用 VibeCheck 的测试功能。
AI辅助测试录制：根据自然语言描述，AI会自动操作浏览器（使用 Playwright）录制测试步骤并生成可重复执行的测试脚本（JSON格式）。
确定性测试执行：可靠地运行之前录制的JSON测试脚本，用于回归测试。
AI驱动的测试发现：爬取网站，分析页面内容，并由大型语言模型 (LLM) 建议潜在的测试步骤。
自动化反馈：将测试执行结果（包括成功/失败状态、截图、日志等）反馈给AI助手。
自愈能力：在测试执行过程中，如果遇到因元素选择器变化导致的失败，AI可以尝试自动修复测试步骤。
支持UI测试：支持Playwright原生不支持的UI断言，例如检查文本是否溢出等。

安装步骤

克隆仓库：

git clone <repository-url> # 将 <repository-url> 替换为 VibeCheck 仓库的实际 URL
cd VibeCheck # 进入克隆的仓库目录

创建并激活Python虚拟环境（推荐）：

python -m venv venv
source venv/bin/activate # Linux/macOS 用户
# venv\Scripts\activate # Windows 用户

安装项目依赖：

pip install -r requirements.txt

安装 Playwright 浏览器：

playwright install --with-deps # 安装必要的浏览器和操作系统依赖

配置 LLM API Key

在项目根目录将 '.env.example' 文件重命名为 '.env'。

编辑 '.env' 文件，添加你的 LLM API Key：

# .env
LLM_API_KEY="YOUR_LLM_API_KEY"
# 可以根据需要配置其他LLM参数，例如 LLM_BASE_URL, LLM_MODEL 等

将 'YOUR_LLM_API_KEY' 替换为你的实际API Key。

MCP 服务器配置（供MCP客户端使用）

你需要将以下配置信息添加到你的 MCP 客户端（如 AI 编码助手）的 MCP 配置中。具体的配置方式请参考你的 MCP 客户端文档。

这是一个示例 MCP 配置段，用于告诉客户端如何启动并连接到 VibeCheck 的 MCP 服务器：

{
  "mcpServers": {
    "Web-QA":{ // 服务器在客户端中显示的名称，你可以自定义
      "command": "uv", // 用于启动VibeCheck服务器的命令，根据你的Python环境管理器可能需要改为 "python", "pipenv", "poetry" 等
      "args": [ // 传递给启动命令的参数
        "--directory",
        "path/to/cloned_repo", // **重要：将此路径替换为你克隆 VibeCheck 仓库的实际文件系统路径**
        "run",
        "mcp_server.py" // 启动 VibeCheck 的 MCP 服务器主文件
      ]
    }
  }
}

将此配置添加到你的MCP客户端配置文件后，你的客户端就可以通过 'Web-QA' 这个名称来识别和连接到 VibeCheck 服务器，并调用其提供的功能。请确保在客户端尝试连接时，VibeCheck 服务器进程正在运行（通过上述 'command' 和 'args' 配置启动）。

基本使用方法

通过配置好 MCP 服务器的 AI 编码助手与 VibeCheck 代理进行交互。使用自然语言向你的 AI 助手发出指令，例如：

录制测试：

"Record a test: go to https://practicetestautomation.com/practice-test-login/, type 'student' into the username field, type 'Password123' into the password field, click the submit button, and verify the text 'Congratulations student' is visible." (AI助手会调用 VibeCheck 代理执行录制，并将测试脚本保存到 'output/' 目录下)
执行测试：

"Run the regression test 'output/test_practice_test_login_20231105_103000.json'" (AI助手会调用 VibeCheck 代理执行指定的测试文件，并将执行结果（PASS/FAIL）反馈给你)
发现测试步骤：

"Discover potential test steps starting from https://practicetestautomation.com/practice/" (AI助手会调用 VibeCheck 代理爬取网站并建议测试步骤)
列出已录制测试：

"List the available recorded web tests." (AI助手会调用 VibeCheck 代理列出 'output/' 目录下的测试文件)

关键词