技术文档摘要

UI-Probe：用纯英文测试任何网站

⚠️ 重要提示：需要 LLM API 密钥

UI-Probe 使用 AI 智能理解网页和表单。需要 OpenAI 或 Anthropic 的 API 密钥。

• 费用：每次测试约 $0.01-0.10，具体取决于复杂度
• 备用模式：设置 UI_PROBE_FALLBACK_MODE=true 可以使用基本的 Playwright 功能而不使用 LLM
• 获取 API 密钥：
  • OpenAI: https://platform.openai.com/api-keys
  • Anthropic: https://console.anthropic.com/

没有有效的 API 密钥时，操作会失败并显示清晰的错误信息。

面临的问题

网站测试是破碎的。你编写了数百行代码，但当开发者将按钮类从 btn-primary 更改为 button-primary 时，你的代码就会失效。你的测试失败不是因为应用程序有问题，而是因为有人移动了一个 div 或重命名了一个 ID。

解决方案

UI-Probe 是一个助手优先、Claude/MCP 原生的 Web 应用测试器。

UI-Probe 让你可以通过描述你想做的事情来测试网站，无需编写代码或选择器。只需像告诉一个人一样描述即可。

⚡ 不是第一个，但有不同之处

工具如 Testim、Mabl 和 Rainforest QA 已经将无代码/AI 测试推向市场。它们很强大，但通常面向企业、锁定在 SaaS 中，并且针对 QA 工程师。

UI-Probe 走的是另一条路：

• 助手优先 → 在 Claude 内部原生运行。你只需要与你的助手交谈并观看它工作。
• 默认纯英文 → 没有脚本，没有录制器。只需告诉它你想测试什么。
• 初学者友好 → PM、设计师和非开发人员可以立即使用。
• 开源 + 轻量级 → 克隆、运行、修改。没有供应商锁定。
• 从测试到执行 → 今天：检查你的 Web 流程。明天：实际运行它们。

从测试到执行

UI-Probe 并不局限于测试。就像你说：

• “✅ 测试用户是否可以注册”

……你也可以这样说：

• “✅ 实际上为我注册一个账户”
• “✅ 从商店购买一件蓝色衬衫”
• “✅ 从 sandwich.com 下单一份火腿加芥末三明治并配送”

所以，从一个QA 辅助工具开始，它可以成为你的个人 Web 代理——能够测试、重复甚至为你执行实际任务。

UI Probe 不仅仅是测试——它是使 Web 简化的通用意图层。

UI-Probe 的不同之处

🚀 状态化测试编排器 vs 脚本生成器

与标准 Playwright MCP 工具不同，后者为每个测试创建一个新的 JavaScript 文件，UI-Probe 是一个持久的智能测试服务器，维护上下文并从交互中学习。

标准 Playwright MCP：

• 为每个测试创建一个新的 .js 文件
• 测试之间没有记忆
• 你写：await page.click('#submit')
• 每次启动新的浏览器
• 手动管理选择器

UI-Probe：

• 单个持久服务器管理所有测试
• 维护浏览器上下文和状态
• 你说：“作为新用户注册”
• 智能表单理解
• 旅程记录和回放

🧠 内置 AI 动力智能

• 🤖 LLM 策略引擎（需要 API 密钥）- 使用 GPT-4/Claude 来理解 UI 上下文和意图
• 🤖 工作流分解器（需要 API 密钥）- 自动将“订购披萨”分解成逻辑步骤
• 🤖 适应性执行器（需要 API 密钥）- 当页面行为异常时调整策略
• 🤖 错误增强器（需要 API 密钥）- 提供智能、可操作的错误消息
• 🤖 表单推理引擎（需要 API 密钥）- 自动理解表单结构、验证规则并生成适当的测试数据

📼 旅程记录与回放系统

提供标准 Playwright 工具无法提供的完整旅程管理：

• ✅ 记录一次，永久回放（在备用模式下有效）- 捕获复杂的流程并回放
• 🤖 旅程验证（需要 API 密钥）- 确保记录的旅程仍然有效
• 🤖 旅程分析（需要 API 密钥）- 识别模式和改进
• 🤖 旅程发现（需要 API 密钥）- 自动发现新的测试路径
• 🤖 智能选择器生成（需要 API 密钥）- 创建能够抵御 UI 变化的选择器

🎯 自然语言目标执行

// 标准 Playwright 方法 - 你需要编写代码：
const { chromium } = require('playwright');
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('http://example.com');
await page.fill('#email', 'test@example.com');
await page.fill('#password', 'password123');
await page.click('button[type="submit"]');

// UI-Probe 方法 - 只需描述你的目标：
run_flow({ goal: "作为新用户注册" })

📊 其他独特功能

• ✅ 内置测试游乐场（在备用模式下有效）- 包含测试页面，可以在部署到项目之前尝试
• ✅ 实时监控（在备用模式下有效）- 观看测试运行并获得实时反馈
• ✅ Claude 原生（在备用模式下有效）- 特别设计用于 Claude Code CLI，而不是改造
• 🤖 实际适用于非开发人员（需要 API 密钥）- PM、设计师、QA 可以立即使用
• ✅ 开源（在备用模式下有效）- 没有供应商锁定，按需定制
• 🤖 语义 AI 解析（需要 API 密钥）- 智能混合使用 Playwright 的语义选择器，仅在必要时才使用 LLM 智能
• 🤖 无需编程（需要 API 密钥）- 与原始 Playwright MCP 不同，Claude 必须编写测试脚本，而 UI-Probe 立即生效，无需任何编程
• ✅ 确定性的 JSON 响应（在备用模式下有效）- 每个动作返回结构化的 JSON，支持条件逻辑和自动化：

{
  "success": true,
  "data": {
    "clicked": true,
    "selector": "button:has-text(\"提交表单\")",
    "currentUrl": "http://localhost:8083/test/forms",
    "pageTitle": "表单测试 - UI-Probe"
  }
}

这意味着你可以构建智能工作流：

# 如果表单提交失败，则尝试备用流程
if response.success == false:
  导航到 backup_url
  使用不同的数据重试

# 而不是这个噩梦：
await driver.findElement(By.xpath("//div[@id='login-form']//input[@name='email']")).sendKeys("test@example.com");
await driver.findElement(By.css(".btn-submit.primary")).click();

# 你可以使用自然语言：
"测试注册表单"

# 或者当你需要精确时使用明确命令：
填写表单 {"email": "test@example.com"}
点击按钮 "注册"

完全初学者指南

从未编写过代码？太好了！UI-Probe 就是为了你设计的：

1. 安装它（一次性设置，5分钟）
2. 用纯英文告诉它要测试什么
3. 获得清晰的结果 - "✅ 账户已创建" 或 "❌ 注册按钮被隐藏"

非开发者的示例

想每天测试你网站上的联系表单吗？只需键入：

# 在 Claude 中，你可以自然地表达：
"测试主页上的联系表单"

# Claude 会根据上下文找出 URL，或者你可以明确指定：
填写表单 "https://mysite.com/contact" {"message": "测试！"}

就是这样。不需要编程。

对于开发人员

UI-Probe 给你：

• 自我修复的测试 - 自动适应 UI 变更
• 减少 80% 的代码 - 一行代替几十行
• AI 动力智能 - 使用 GPT-4/Claude 来理解页面
• 清晰的错误消息 - "按钮被 cookie 声明横幅隐藏" 而不是 "ElementNotInteractableException"

快速入门（5分钟）

🎯 TL;DR - 快速运行

npx mcp-ui-probe setup                                                      # 1. 安装浏览器（一次性）
echo "OPENAI_API_KEY=sk-..." > .env                                        # 2. 添加 API 密钥（推荐但非必需）
curl -sSL https://raw.githubusercontent.com/Hulupeep/mcp-ui-probe/main/scripts/claude-setup.sh | bash  # 3. 连接到 Claude
claude                                                                       # 4. 开始使用！

先决条件

• Node.js 18+ （下载 - 只需点击“下一步”完成安装程序）
• Claude Code CLI 或任何终端
• OpenAI 或 Anthropic API 密钥（智能功能所需，见成本估算部分）

系统要求

• 操作系统：Windows、macOS 或 Linux
• Node.js：版本 18 或更高
• 磁盘空间：~500MB 用于 Playwright 浏览器（一次性下载）
• 内存：最低 2GB，建议 4GB

方案 1：使用 npx（最简单 - 适用于所有环境！）

第一步：初始设置（仅需一次）

# 安装 Web 测试所需的 Playwright 浏览器（约 500MB，耗时 2-3 分钟）
npx mcp-ui-probe setup

第二步：配置 LLM 提供商（智能功能所需）

UI-Probe 需要 API 密钥来进行智能表单理解和工作流执行：

# 在当前目录创建一个 .env 文件
echo "OPENAI_API_KEY=your-key-here" > .env
# 或对于 Anthropic
echo "ANTHROPIC_API_KEY=your-key-here" > .env

# 可选：启用备用模式以使用基本的 Playwright 功能而不使用 LLM
echo "UI_PROBE_FALLBACK_MODE=true" >> .env

重要：没有有效的 API 密钥，智能功能将无法工作：

• 🤖 表单字段推断和理解
• 🤖 自然语言工作流分解
• 🤖 智能错误消息增强
• 🤖 适应性元素检测

见下方的成本估算部分了解 API 使用成本。

第三步：连接到 Claude Code CLI

为什么需要这额外一步？ Claude Code CLI 本身找不到 npx，因为它没有访问你的 shell 的 PATH。你需要告诉 Claude 在你的计算机上 npx 的确切位置。

选项 A：自动设置（最简单 - 它会为你做一切）：

# 此脚本会：
# 1. 查找 npx 在你的计算机上的安装位置
# 2. 使用正确的路径将 UI-Probe 添加到 Claude
# 3. 验证一切配置正确
curl -sSL https://raw.githubusercontent.com/Hulupeep/mcp-ui-probe/main/scripts/claude-setup.sh | bash

运行此脚本后，只需重新启动 Claude，UI-Probe 就可以使用了！

选项 B：手动设置（如果自动设置不起作用）：

第 1 步：查找你的 npx 路径

# 在 macOS/Linux 上：
which npx
# 示例输出：/usr/local/bin/npx 或 ~/.nvm/versions/node/v20.11.0/bin/npx

# 在 Windows 上：
where npx
# 示例输出：C:\Program Files\nodejs\npx.cmd

第 2 步：使用完整路径添加到 Claude

# 使用你在第 1 步中的路径：
claude mcp add ui-probe "/full/path/to/npx" "mcp-ui-probe@latest" "start"

# 实际示例：
# 标准 Node.js：
claude mcp add ui-probe "/usr/local/bin/npx" "mcp-ui-probe@latest" "start"

# 使用 NVM：
claude mcp add ui-probe "$HOME/.nvm/versions/node/v22.11.0/bin/npx" "mcp-ui-probe@latest" "start"

# Windows：
claude mcp add ui-probe "C:\Program Files\nodejs\npx.cmd" "mcp-ui-probe@latest" "start"

第四步：在 Claude 中开始使用 UI-Probe！

# 启动 Claude Code CLI
claude

# UI-Probe 工具现在可用！试试：
# - 导航到网站
# - 分析页面元素
# - 填写并提交表单
# - 运行完整的测试流程

第五步：（可选）尝试测试游乐场

想在测试自己的站点之前看看 UI-Probe 的效果吗？

# 启动内置的测试服务器，包含示例表单
npx mcp-ui-probe test-server   # 在 http://localhost:8081/test 运行
npx mcp-ui-probe test-server --port 3000   # 如果 8081 被占用，使用自定义端口

# 在浏览器中访问 http://localhost:8081/test 查看游乐场
# 然后在 Claude 中尝试：run_flow "作为新用户注册" "http://localhost:8081/test"

方案 2：从源码安装

# 克隆它（这会下载代码）
git clone https://github.com/Hulupeep/mcp-ui-probe.git
cd mcp-ui-probe

# 安装它（这会设置一切）
npm install

# 关键步骤：安装浏览器（一次性，耗时 2-3 分钟）
npx playwright install

# 添加到 Claude：
claude mcp add ui-probe "node" "/path/to/mcp-ui-probe/dist/index.js"

开始测试！

# 在 Claude 中，只需描述你想要的：
"测试用户是否可以在 example.com 注册"

# 或者具体一点：
run_flow "前往 https://example.com/signup 并创建一个账户"

UI-Probe 在 Claude 中的工作原理

自然语言（默认 - 直接说正常的话！）

UI-Probe 理解你想做什么：

# 只需描述你想要的 - UI-Probe 会弄清楚：
"测试用户是否可以在 example.com 注册"
"检查结账流程是否正常"
"用测试数据填写联系表单"
"点击提交按钮"

明确命令（当你需要精确控制时）

有时你需要具体说明要做什么：

# 使用明确命令进行精确控制：
导航 "https://staging.myapp.com/login"           # 跳转到确切的 URL
填写表单 "https://myapp.com/contact" {"message": "测试"}  # 填写特定字段
点击按钮 "提交订单"                          # 点击确切的按钮文本
验证元素 "div.success" "可见"               # 检查特定元素

最佳实践：先使用自然语言。如果 UI-Probe 需要澄清或你需要精确控制，切换到明确命令。

常见任务

测试登录表单

# 自然语言（建议从这里开始）：
"测试用户是否可以在 myapp.com 登录"
"检查登录流程"

# 明确命令（为了精确控制）：
导航 "https://myapp.com/login"
填写表单 {"email": "test@example.com", "password": "password123"}
点击按钮 "登录"
验证页面 {"expectedContent": ["仪表板", "欢迎"]}

测试购买

# 自然语言：
"从 shop.com 购买一件蓝色衬衫"
"测试结账流程，使用测试信用卡"

# 明确命令：
导航 "https://shop.com"
点击按钮 "衬衫"
点击按钮 "蓝色棉质T恤"
点击按钮 "加入购物车"
填写表单 {"card": "4111111111111111", "exp": "12/25", "cvv": "123"}
点击按钮 "完成订单"

测试表单验证

# 测试错误数据会发生什么：
填写表单 "https://myapp.com/signup" {"email": "not-an-email"}
# UI-Probe 告诉你："❌ 出现了电子邮件验证错误"

检查是否存在某物

验证元素 "https://myapp.com" "免费送货" "可见"
# 返回："✅ 页面上找到了 '免费送货'"

UI-Probe 的不同之处

传统测试工具

• 编写带有特定选择器的代码
• 当 UI 改变时测试会失败
• 加密的错误消息
• 需要编程知识
• 数百行代码

UI-Probe

• 用纯英文描述
• 当 UI 改变时自我修复
• 清晰的人类友好的错误
• 不需要编程
• 一行代码就搞定

现实世界示例

电子商务网站

# 完整的购买流程
"购买网站上最便宜的笔记本电脑"

# UI-Probe 自动：
# - 找到商店
# - 搜索笔记本电脑
# - 按价格排序
# - 加入