Vibe Test — Browser Testing Agent

vibe-testing

面向 AI 编码 Agent、了解代码的浏览器测试工具。

产品网站 · npm · MCP Registry · Smithery · 隐私 · 发布状态

已收录于 Awesome MCP Servers。下载徽章显示 npm 的累计软件包下载量；npx 获取软件包也计入总量。

vibe-testing 会读取你的代码库，让测试使用实际路由和字段名称；它会在真实的 Playwright 浏览器中运行测试，记住出错之处，并告诉你最近一次更改修复了什么或导致了哪些回归。它可以作为 MCP 服务，为你的编辑器（Claude Code、Cursor、Windsurf、VS Code Copilot、Roo Code）提供 14 个测试工具；也可以作为独立的命令行工具。

该代码库同时是一个带有 release-qa 技能的 Agent Plugin。兼容的 Agent 可同时使用测试工具和高级 QA 工作流，完成覆盖率检查、证据收集、回归检查，并给出明确的发布结论。

cd /path/to/your/project
npx vibe-testing@latest init

然后打开编辑器并输入：

“扫描这个代码库，并针对 http://localhost:3000 进行测试”

---

了解代码的测试有何优势

Playwright MCP 让 Agent 拥有了操作能力。vibe-testing 则提供测试工作流：从代码派生测试场景、跨运行记忆，以及报告。无状态的浏览器工具做不到以下两件事：

1. 运行两次，就能知道你破坏了什么。 每次运行都会写入 .vibe/run-snapshot.json，并与上次运行进行比较。每次扫描都会写入 .vibe/route-manifest.json，并对比路由变化。第二次运行会显示回归和修复，而不是堆出一大串结果：

Changes since last run
  Fixed:      /login
  Regression: /checkout
  New:        /admin/users

同一份差异也会通过 run_full_test 和 run_converge 上的 snapshot_diff，以及 scan_codebase 上的 route_changes 传递给编辑器，让 Agent 无需任何人翻阅报告，就能指出“提交该代码后结账功能出错了”。不稳定的路由、可用的选择器和测得的超时时间也会在不同运行之间保留下来。

2. 工具内部不会调用 LLM。 通过启发式方法验证通过或失败：URL 变化、Toast 检测、API 错误。由编辑器中的模型决定测试什么；vibe-testing 负责浏览和检查。无需 API 密钥，也不会产生超出你已有编辑器订阅费用的单次运行成本。

---

目录

• 工作原理
• MCP 设置（针对各编辑器）
• MCP 工具参考
• 推荐工作流
• init 命令
• CLI 命令
• VIBE.md，项目指南
• 配置（vibe.config.json）
• 支持的框架
• 记忆与回归检测
• 常见问题

---

工作原理

npx vibe-testing@latest init
        |
Registers 14 MCP tools in your editor
        |
You ask: "Test the checkout flow"
        |
AI calls: scan_codebase -> get_context("checkout") -> login -> explore_page -> execute_scenario -> generate_report
        |
HTML report opens in browser with screenshots of every step

无需编写测试用例。AI 会读取你的源代码，了解实际字段名称和路由，打开浏览器并测试所有内容，然后告诉你哪些地方出了问题。

init 还会：

• 检测你安装了哪些 AI 编辑器
• 在全局编辑器配置（~/.claude/settings.json、~/.cursor/mcp.json 等）中注册 vibe-test，让工具在每个项目、每个会话中都可用
• 创建项目级 MCP 配置和 AI 指令文件
• 自动检测应用的 URL（读取 .env、vite.config 和框架默认值）
• 创建 VIBE.md（编辑并填写测试凭据）和 vibe.config.json
• 安装匹配的 Playwright Chromium 版本

---

MCP 设置

Agent 插件

如果你的 Agent 支持 Agent Plugins 标准，请将此仓库安装为插件。它包含可移植的 release-qa 技能，并会启动已发布的 npm MCP 服务，无需 API 密钥。

• Cursor：将 https://github.com/AishwaryShrivastav/vibe-testing 作为 Agent 插件提交或安装。

• Claude Code：

  claude plugin marketplace add AishwaryShrivastav/vibe-testing
  claude plugin install vibe-testing@vibe-testing
  

• 其他兼容的 Agent：加载包含 plugin.json、skills/ 和 mcp.json 的仓库根目录。

对于不支持插件的编辑器，仍可使用下面的直接 MCP 和 CLI 设置方法。

MCPB bundle

Claude Desktop 和其他 MCPB 主机可以安装一个本地 bundle。请从此仓库构建并验证：

npm ci
npm run build:mcpb

生成的文件位于 artifacts/vibe-testing-<version>.mcpb。有关 bundle 内容、验证步骤、Smithery 交接以及一次性 Playwright Chromium 前置要求，请参阅 MCPB 分发指南。

选项 1：自动设置（推荐）

npx vibe-testing@latest init

检测并配置所有已安装的编辑器。完成。

选项 2：按编辑器手动设置

Claude Code

添加到 ~/.claude/settings.json（全局设置，适用于每个项目）：

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

或者添加到项目根目录中的 .mcp.json（仅限项目级设置）：

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）：

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

VS Code（GitHub Copilot）

添加到项目中的 .vscode/mcp.json：

{
  "servers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

Roo Code / Cline

添加到 .roo/mcp.json：

{
  "mcpServers": {
    "vibe-test": {
      "command": "npx",
      "args": ["-y", "vibe-testing@latest", "--mcp"]
    }
  }
}

从本地构建（开发）

{
  "mcpServers": {
    "vibe-test": {
      "command": "node",
      "args": ["/path/to/vibe-testing/dist/mcp-server.js"]
    }
  }
}

---

MCP 工具参考

设置完成后，你的 AI 编辑器可使用 14 个工具：

工具	调用时机	返回内容
configure	在新项目中从这里开始。检测框架、服务和身份验证	结构化设置结果和幂等的项目文件
scan_codebase	始终首先调用。读取源代码，查找路由、表单、测试和缺失项	路由、表单、覆盖率映射、生成的场景，以及自上次扫描以来的 route_changes
get_context	编写测试步骤前调用。返回某项功能的源文件	包含实际字段名称和选择器的真实源代码
login	应用需要身份验证时调用	登录后的截图、令牌状态、观察到的 API 调用
scan_page_elements	查看页面上的所有交互元素	包含选择器的元素列表和页面截图
explore_page	进行全面的“所有功能是否正常？”测试	交互结果、API 调用、错误和截图
execute_scenario	运行指定的测试步骤	逐步日志和截图
get_coverage	查看覆盖率映射和未经测试的路由	覆盖率条目、缺失项、可用场景
suggest_tests	探索后查找覆盖率缺口	已排序、可直接运行且包含步骤的场景
take_screenshot	快速进行视觉验证	任意 URL 的截图
generate_report	生成 HTML 报告（自动打开）	报告路径和摘要
run_full_test	一键执行：扫描、运行、探索并生成报告	完整结果，以及与上次运行相比的 snapshot_diff
run_converge	反复测试，直到达到阈值	所有轮次的摘要，以及与上次运行相比的 snapshot_diff
cleanup	关闭浏览器并释放资源	-

工具输入

scan_codebase

{
  "codebase_path": "/path/to/project",
  "url": "http://localhost:3000",
  "mode": "deep"
}

get_context

{ "feature": "login" }
{ "feature": "/checkout" }
{ "feature": "user profile form" }

login

{
  "email": "[email protected]",
  "password": "TestPass123!",
  "login_url": "/login"
}

scan_page_elements / explore_page

{
  "route": "/dashboard",
  "authenticated": true
}

execute_scenario

{
  "scenario": {
    "id": "create-item",
    "name": "Create a new item",
    "route": "/items",
    "steps": [
      { "action": "navigate", "url": "/items", "description": "Open items page" },
      { "action": "click", "selector": "text=Add Item", "description": "Open create form" },
      { "action": "fill", "selector": "[name='title']", "value": "Test Item", "description": "Fill title" },
      { "action": "fill", "selector": "[name='description']", "value": "Test description", "description": "Fill description" },
      { "action": "click", "selector": "button[type='submit']", "description": "Submit form" }
    ],
    "expected_outcome": "New item appears in the list",
    "requires_auth": true
  }
}

步骤操作：navigate、fill、click、select、wait、assert、upload

CLI 和 MCP 使用相同的场景运行器。assert 步骤会评估提供的每个条件：

• selector：目标必须可见。支持 CSS、text=、label= 和 placeholder=；命名定位器会进行精确匹配。
• value：可见文本必须包含此字符串；如果未提供选择器，则检查所选元素或页面正文。
• url：当前 URL 必须与此绝对 URL 完全一致，或与根据配置的基础 URL解析后的路径完全一致，包括查询参数和片段。

例如：

{ "action": "assert", "selector": "#confirmation", "value": "Saved", "url": "/settings", "timeout": 5000, "description": "Check saved settings" }

这些检查会等待最多一个步骤超时时间（每项检查默认 15000 ms）。断言失败会停止场景，记录失败步骤和原因，并返回 status: "fail"；MCP 也会设置 isError: true。在现有的身份验证和表单 API 检查之后，显式条件会作为判定依据。description 和 expected_outcome 中的描述性文本不是可执行断言。 如果没有 selector、value 或 url，assert 只会检查页面健康状况：正文中至少有 10 个可见字符，且没有非空的可见错误指示器。此兼容性检查无法证明所描述的业务结果。

upload 需要文件输入框的 selector，并且 value 中必须包含非空文件路径。相对路径以代码库根目录为基准解析。支持隐藏的文件输入框。如果文件不存在、路径指向目录、目标不存在或目标不是文件输入框，则返回 status: "error"。此操作使用 Playwright 选择一个文件；请添加对生成的 UI 的断言，以验证应用端处理情况。它不会自动操作原生文件选择器对话框。

场景必须至少包含一个步骤。未知操作会导致错误。

take_screenshot

{ "url": "/settings", "authenticated": true, "full_page": false }

run_full_test

{ "url": "http://localhost:3000", "codebase_path": "/path/to/project", "mode": "deep" }

run_converge

{
  "url": "http://localhost:3000",
  "max_followup_rounds": 4,
  "target_pass_rate": 0.92,
  "max_high_severity_gaps": 2
}

---

推荐工作流

完整测试会话

告诉你的 AI 编辑器：

Scan this codebase and test it against http://localhost:3000.
Log in with [email protected] / pass123. Explore the dashboard and
settings pages, run the suggested tests, and generate a report.

AI 将会：

1. scan_codebase，了解路由、表单和现有测试
2. get_context("login")，读取实际的登录表单源代码
3. login，在真实浏览器中进行身份验证
4. explore_page("/dashboard")，点击所有内容并观察哪些地方出错
5. explore_page("/settings")，执行相同操作
6. suggest_tests，查找覆盖缺口
7. execute_scenario x N，运行有针对性的测试流程
8. generate_report，HTML 报告会自动打开
9. cleanup，关闭浏览器

测试特定功能

Test the checkout flow using vibe-test. Get context for checkout,
then run the full purchase flow with card number 4242424242424242.

AI 将会：

1. scan_codebase（如果尚未执行）
2. get_context("checkout")，读取 CheckoutForm.tsx、api/orders/route.ts 等内容
3. login
4. execute_scenario，根据源代码填写实际表单字段
5. generate_report

验证 Bug 修复

I fixed the login redirect bug. Use vibe-test to confirm it's working.

AI 将会：

1. login，测试登录流程
2. take_screenshot，以可视化方式确认登录后的状态
3. 汇报观察结果

查找故障

Explore every page and tell me what's broken.

AI 将在每个路由上运行 explore_page，收集 API 错误、损坏的元素和失败的交互；随后运行 suggest_tests，并将故障项标记为高优先级。

---

init 命令

npx vibe-testing@latest init [options]

创建的文件：

文件	位置	用途
.mcp.json	项目根目录	Claude Code MCP 配置（项目级）
~/.claude/settings.json	全局	Claude Code MCP 配置（所有项目）
.cursor/mcp.json	项目根目录	Cursor MCP 配置
~/.cursor/mcp.json	全局	Cursor MCP 配置（所有项目）
.cursor/rules/vibe-test.mdc	项目	Cursor 规则，alwaysApply: true
.windsurfrules	项目	Windsurf 指令
~/.codeium/windsurf/mcp_config.json	全局	Windsurf MCP 配置（所有项目）
.vscode/mcp.json	项目	VS Code Copilot MCP 配置
.github/copilot-instructions.md	项目	GitHub Copilot 指令
.roo/mcp.json	项目	Roo Code MCP 配置
CLAUDE.md	项目	Claude Code 会话指令
AGENTS.md	项目	通用 Agent 指令（Codex、Devin、Zed）
VIBE.md	项目	测试指南，使用你的凭据进行编辑
vibe.config.json	项目	配置，URL 会根据你的项目自动检测

选项：

npx vibe-testing@latest init                     # auto-detect editors, register globally + project
npx vibe-testing@latest init --no-global         # project-level only, skip global registration
npx vibe-testing@latest init --skip-browser-install
npx vibe-testing@latest init --editor cursor     # only configure Cursor
npx vibe-testing@latest init --editor claude-code windsurf

初始化后，编辑 VIBE.md，填写你的登录 URL 和测试凭据。

---

CLI 命令

# Set up in current project
npx vibe-testing@latest init

# Install or repair the matching browser build
npx vibe-testing@latest install-browser

# Run tests against a URL
npx vibe-testing@latest run http://localhost:3000
npx vibe-testing@latest run https://staging.myapp.com --mode deep
npx vibe-testing@latest run http://localhost:3000 --codebase /path/to/project --scope /login /dashboard

# Iterative testing until coverage thresholds
npx vibe-testing@latest converge http://localhost:3000
npx vibe-testing@latest converge http://localhost:3000 --max-rounds 6 --target-pass-rate 0.95

# Open last report in browser
npx vibe-testing@latest report

# Reset memory and screenshots for a clean run
npx vibe-testing@latest reset

run 选项

选项	默认值	描述
--mode fast|deep	deep	fast：快速扫描。deep：完整提取功能并进行探索
--no-headed	-	以无头模式运行浏览器（默认：可见）
--codebase <path>	cwd	项目根目录路径
--scope <routes...>	all	仅测试指定路由
-c <path>	vibe.config.json	配置文件路径

当未发现任何场景或执行批次为空时，run 和 converge 会以非零退出码失败。 在这些情况下，MCP run_full_test 和 run_converge 会返回 isError: true。空运行不会写入成功的运行快照，也不会替换之前的报告。

converge 选项

选项	默认值	描述
--max-rounds <n>	4	基线测试后的最大后续轮数
--target-pass-rate <r>	0.92	通过率达到此值（0-1）时停止
--max-gaps <n>	2	关键问题加重要问题的数量降至此值时停止

---

VIBE.md，项目指南

在项目根目录中创建 VIBE.md。vibe-testing 会在每次运行时自动读取它。

## Login URL
/login

## Test Credentials
- Email: [email protected]
- Password: TestPass123!

## Never Automate
- delete account
- cancel subscription
- [data-testid="danger-zone"]
- .billing-section

## Known Flaky
- /notifications (WebSocket dependent, skip or expect retry)
- /live-feed

## Notes
- Admin panel at /admin, use [email protected] / adminpass
- Dashboard data loads async, wait for [data-loaded="true"]
- Profile page: click "Edit Profile" before form fields appear

完整模板请参阅 VIBE.example.md。

---

配置

vibe.config.json

由 init 自动创建，并自动检测 URL。可按需编辑：

{
  "url": "http://localhost:3000",
  "mode": "deep",
  "auth": {
    "strategy": "credentials",
    "login_url": "/login",
    "credentials": {
      "email": "[email protected]",
      "password": "TestPass123!"
    }
  },
  "never_interact": [
    "delete account",
    "cancel subscription",
    "[data-testid='danger-zone']"
  ],
  "scope": {
    "include": ["/**"],
    "exclude": ["/admin/**", "/api/**"],
    "max_routes": 30,
    "seed_routes": ["/live/dev-mode-a-now"]
  },
  "browser": {
    "headed": true,
    "slowMo": 40,
    "timeout": 30000
  }
}

键	描述
url	应用 URL，可以是本地主机或暂存环境。由 init 自动检测。
mode	fast（启发式扫描）或 deep（完整提取并探索）
auth.strategy	credentials（表单登录）、basic（HTTP Basic Auth）或 skip
auth.login_url	为非标准路径指定明确的登录路由，以免关键词匹配遗漏
auth.credentials	登录凭据，用于登录和生成场景，并会在多次运行间持久保存
never_interact	探索时要跳过的文本模式或 CSS 选择器
scope.include	要包含的路由模式；默认值 /** 会包含 / 和所有嵌套路由。* 仅匹配一个路径段；末尾的 /** 会包含子树根路由及其所有后代。其他字符均按字面匹配。
scope.exclude	要从测试中排除的路由模式
scope.max_routes	每次运行测试的路由数量上限
scope.seed_routes	解析器无法枚举的动态路由段对应的具体 URL（例如，/live/[slug] 会变成 /live/dev-mode-a-now）。每个种子路由都会继承其动态父路由的 requires_auth 和源文件。
browser.headed	true = 显示浏览器。CLI 默认值为 true，MCP 服务默认值为 false（无头模式），以免弹出窗口干扰编辑器会话。
browser.slowMo	操作之间的毫秒数（便于调试）
routes	auto（默认值）会从代码库发现路由。config 仅使用配置中明确列出的路由。

---

支持的框架

框架	路由	API 端点	表单
Next.js App Router	是	是	是
Next.js Pages Router	是	是	是
Next.js（src/ 变体）	是	是	是
React SPA (react-router)	是	-	是
Vue + Vite (vue-router)	是	-	是
Nuxt	是	是	是
SvelteKit	是	是	是
Express / Fastify	-	是	是
Monorepos (Turborepo, pnpm, Lerna)	是	是	是

还会读取现有测试文件来构建覆盖率映射：Jest、Vitest、Playwright 和 Cypress 测试套件都会被解析。

---

记忆与回归检测

vibe-testing 会在多次运行中不断学习，并将状态存储在 .vibe/ 中：

• 有效选择器：记住 [name='email'] 在 /login 上有效，并在下次运行时使用
• 路由耗时：根据测得的加载时间调整超时
• 身份验证凭据：首次登录后保存，并自动重复使用
• 不稳定路由：追踪失败率较高的路由，并将其标记为重试
• 跳过路由：对持续出错（需要 URL 参数）的路由自动跳过
• 路由清单（.vibe/route-manifest.json）：每次扫描都会与上次扫描进行差异比较；新增和移除的路由会作为 scan_codebase 结果中的 route_changes 显示，以便 AI 立即覆盖这些路由
• 运行快照（.vibe/run-snapshot.json）：每次运行都会记录各路由的通过/失败情况，并与上次运行进行差异比较；snapshot_diff 会标记 newly_passing（修复）、newly_failing（回归）、still_failing，以及新增和移除的路由

{
  "snapshot_diff": {
    "newly_passing": ["/login"],
    "newly_failing": ["/checkout"],
    "still_failing": [],
    "new_routes": ["/admin/users"],
    "removed_routes": []
  }
}

run_converge 返回相同结构，因此在编辑器中进行迭代运行时，可以突出显示刚刚导致的问题。

运行 npx vibe-testing@latest reset 即可重置并重新开始。

---

会话示例

当你让编辑器“测试登录流程”时，它会这样操作：

User: "Test the login flow"

AI calls:
  scan_codebase({ codebase_path: ".", url: "http://localhost:3000" })
    -> Finds /login route, LoginForm component, POST /api/auth/login endpoint
    -> Returns 8 generated test scenarios

  get_context({ feature: "login" })
    -> Returns src/app/login/page.tsx (has name="email", name="password" fields)
    -> Returns src/app/api/auth/login/route.ts (POST handler, returns { token })
    -> AI now knows the real selectors: [name='email'], [name='password']

  login({ email: "[email protected]", password: "pass123" })
    -> Opens Chromium, fills the form, clicks submit
    -> Returns: { success: true, final_url: "/dashboard", tokens_found: 2 }
    -> Returns screenshot of post-login dashboard

  execute_scenario({ scenario: { name: "Login with invalid password", ... } })
    -> Returns screenshot showing error state

  generate_report()
    -> Writes .vibe/report.html, opens in browser

AI reports: "Login works. Invalid password shows an error. All 3 login scenarios passed."

---

常见问题

vibe-testing 内部会使用大模型吗？ 不会。它使用启发式验证（URL 变化、Toast 检测、API 错误）。编辑器中的模型是大脑：它会查看屏幕截图，并决定接下来要测试什么。运行测试无需支付 API 费用。

explore_page 和 execute_scenario 有什么区别？ explore_page 覆盖范围较广：它会点击找到的每个按钮和输入框，并报告结果。execute_scenario 则更精确：你提供具体步骤，它会严格按步骤执行。使用 explore_page 查找页面上的内容，然后使用 execute_scenario 测试特定流程。

get_context 有什么用？ 它会返回某项功能的实际源代码，让 AI 知道应使用 [name='email']，而不是猜测 #email-input。为特定功能编写测试步骤前，请务必先调用它。

它能处理带客户端路由的 SPA 吗？ 可以。Playwright 会在真实浏览器中导航，因此客户端路由（React Router、Vue Router 等）都能正常运行。

它能处理登录／身份验证吗？ 可以。login 工具会在真实浏览器中填写凭据，从 localStorage／cookies 中捕获身份验证令牌，并保持会话有效，以便进行身份验证测试。凭据会保存在 .vibe/memory/ 中，并自动重复使用。

它会点击“删除账户”或其他具有破坏性的按钮吗？ 不会。在 vibe.config.json 或 VIBE.md 中设置 never_interact，即可将危险操作加入阻止列表。探索过程中，任何文本或选择器匹配的按钮都会被跳过。

不使用 AI 编辑器也能用吗？ 可以。vibe-test run https://your-app.com 可独立运行。它会扫描、生成场景、执行测试并生成 HTML 报告，无需编辑器。

如何测试预发布环境？ 在 vibe.config.json 中将 url 设为预发布环境的 URL，或将其作为 CLI 参数传入：npx vibe-testing@latest run https://staging.myapp.com。

它支持单体仓库吗？ 支持。init 会检测 Turborepo/pnpm/yarn 工作区，并自动找到前端应用。

---

要求

• Node.js >= 20（测试套件使用 vitest 4.x，需要 Node 20+）
• Playwright Chromium。init 会安装匹配的构建版本。若要直接安装或修复：

  npx vibe-testing@latest install-browser
  

run 和 converge 会在扫描项目之前检查浏览器，并在浏览器缺失时打印相同的恢复命令。

Docker

为偏好基于容器的 MCP 服务的环境提供了 Node 20 + Chromium 镜像：

docker build -t vibe-test .
# wire into your editor's MCP config:
# { "command": "docker", "args": ["run", "--rm", "-i", "vibe-test"] }

---

贡献

git clone https://github.com/AishwaryShrivastav/vibe-testing.git
cd vibe-testing
npm install
npx playwright install chromium
npm run build   # tsc -> dist/
npm run dev     # run CLI without building
npm run mcp     # run MCP server without building
npm test        # unit and isolated integration tests
VIBE_REAL_BROWSER=1 npm test  # also run real Chromium CLI/MCP regressions

版本历史请参阅 CHANGELOG.md。Bug 报告和功能请求：GitHub issues。

---

链接

• npm：https://www.npmjs.com/package/vibe-testing
• GitHub：https://github.com/AishwaryShrivastav/vibe-testing
• Issues：https://github.com/AishwaryShrivastav/vibe-testing/issues
• 官方 MCP 注册表：以 io.github.AishwaryShrivastav/vibe-testing 列于 https://registry.modelcontextprotocol.io
• 
• Model Context Protocol
• Playwright