UI-Probe：用最通俗易懂的语言测试任何网站
重要提示：需要大型语言模型（LLM）API密钥
UI-Probe 利用人工智能智能理解网页和表单。 需要OpenAI或Anthropic的API密钥.
- 成本根据测试的复杂性，每项测试费用约为0.01-0.10美元
- 备用模式设置
UI_PROBE_FALLBACK_MODE=true对于不包含LLM（大型语言模型）的基本Playwright功能 - 获取API密钥：
- OpenAI: https://platform.openai.com/api-keys（中文可表述为：“OpenAI：https://platform.openai.com/api-keys”） - Anthropic（公司）: https://console.anthropic.com/
没有有效的API密钥，操作将会失败并显示明确的错误信息。
问题
网站测试出现了故障。你写了数百行代码，但开发人员一修改按钮类，代码就崩溃了 btn-primary 到；向；对于 button-primary你的测试失败并不是因为应用程序出错了，而是因为有人移动了一个div或者更改了一个ID的名称。
解决方案
UI-Probe 翻译为中文是“用户界面探针”或“界面探测工具” 是 一 个 首先，作为Claude/MCP原生的网页应用测试员。
UI-Probe 允许您通过用简单的英语描述想要执行的操作来测试网站。无需代码，无需选择器，只需像告诉人类一样描述即可。
⚡ 不是首次，但观点独特
诸如……之类的工具 Testim（人名，音译可能因语境而异，此处为一种常见翻译方式）， Mabl，以及 雨林问答（系统/平台） 已经将无代码/AI测试推向市场。它们功能强大，但往往 企业导向、SaaS绑定、专为QA工程师优化。
UI-Probe 采取了一条不同的路径：
- 助手优先 → 通过MCP在Claude中原生运行。你只需与你的助手交谈，然后看着它工作。
- 默认使用简洁明了的英语 → 不需要脚本，也不需要录音器。只需告诉它你想测试什么。
- 适合初学者 产品经理、设计师以及非开发人员可以立即使用它。
- 开源 + 轻量级 → 克隆、运行、破解。无供应商锁定。
- 从测试 → 到实施 今天：检查你的网页流程。明天：实际运行它们。
从测试 → 到实施
UI-Probe的功能不仅限于测试。就像您会说：
- “✅ 测试用户是否能注册”
……你也可以这样说：
- “✅ 实际上请帮我注册一个账户”
- “✅ 在商店里买一件蓝色衬衫”
- “✅ 在sandwich.com上为我订一个火腿+芥末三明治，并送过来”
所以，起初只是一个 质量保证助手 也可以成为你的 个人网络代理 ——能够为你进行测试、重复操作，甚至执行实际任务。
UI Probe不仅仅是测试——它是一种 面向网络的通用意图层 简化处理。
UI-Probe 的独特之处何在
🚀（火箭/飞速上升） 有状态测试编排器与脚本生成器
与标准的Playwright MCP工具（为每个测试创建一个新的JavaScript文件）不同，UI-Probe是一种 持久、智能的测试服务器 该系统能够保持上下文并在交互中学习。
标准Playwright MCP（注：MCP可能代表某种特定的配置、模式或认证，但在此上下文中未给出具体含义，因此直接保留原样）：
- 为每个测试创建一个新的.js文件
- 测试之间无记忆功能
- 你写道：
await page.click('#submit') - 每次启动时都使用新的浏览器
- 手动选择器管理
UI-Probe（用户界面探针）
- 单一持久服务器管理所有测试
- 保持浏览器上下文和状态
- 你说：“注册成为新用户”
- 智能表单理解
- 行程记录与回放
🧠 这个符号通常被用来代表“大脑”或“思考”，在中文中可以翻译为“大脑”或“思考”。不过，由于它是一个表情符号，有时也可能被用作一种简短的表达或梗，具体含义可能需要根据上下文来判断。 内置AI驱动智能
- 🤖 大型语言模型（LLM）策略引擎 （需要API密钥）- 使用GPT-4/Claude来理解用户界面上下文和意图
- 🤖 工作流分解器 （需要API密钥）- 自动将“订购披萨”分解为逻辑步骤
- 自适应执行器 （需要API密钥）- 当页面行为异常时调整策略
- 🤖 错误增强器 （需要API密钥）- 提供智能、可操作的错误信息
- 🤖 表单推理引擎 （需要API密钥）- 自动理解表单结构、验证规则，并生成相应的测试数据
📼 代表录像带或视频录像机的符号。 行程记录与回放系统
提供标准Playwright工具所不具备的完整旅程管理功能：
- ✅ 一次录制，永久回放 （在回退模式下工作）- 捕获复杂工作流程并重新播放
- 🤖 旅程验证 （需要API密钥）- 确保记录的行程保持有效
- 🤖 旅程分析 （需要API密钥）- 识别模式并进行改进
- 🤖 探索之旅 （需要API密钥）- 自动发现新的测试路径
- 🤖 智能选择器生成 （需要API密钥）- 创建能够抵御UI变化的健壮选择器
🎯（目标） 自然语言目标执行
// Standard Playwright approach - you write the code:
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 approach - just describe your goal:
run_flow({ goal: "Sign up as a new user" })📊（表格） 额外的独特功能
- ✅ 内置测试平台 （在回退模式下工作）- 包含测试页面，可在部署到您的项目之前进行尝试
- ✅ 实时监控 （在回退模式下工作）- 观察测试运行并实时获取反馈
- ✅ 原生Claude （在回退模式下工作）- 专为Claude Code CLI设计，非改装适配
- 🤖 实际上对非开发者也有效 （需要API密钥）- 项目经理、设计师、质量保证人员可立即使用
- ✅ 开源 （在回退模式下工作）- 无供应商锁定，按需定制
- 语义人工智能解决方案 （需要API密钥）- 智能混合工具，首先使用Playwright的语义选择器，仅在必要时回退到大型语言模型（LLM）智能
- 🤖 无需编码 （需要API密钥）- 与Claude必须编写测试脚本的原始Playwright MCP不同，UI-Probe无需任何编程即可立即工作
- ✅ 确定性的JSON响应 （在回退模式下工作）- 每个操作都会返回结构化的JSON，支持条件逻辑和自动化：
{
"success": true,
"data": {
"clicked": true,
"selector": "button:has-text(\"Submit Form\")",
"currentUrl": "http://localhost:8083/test/forms",
"pageTitle": "Forms Testing - UI-Probe"
}
}这意味着您可以构建智能工作流：
# If form submission fails, try alternative flow
if response.success == false:
navigate to backup_url
retry with different_data# Instead of this nightmare:
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();
# You can use natural language:
"Test the signup form"
# Or explicit commands when you need precision:
fill_form {"email": "test@example.com"}
click_button "Sign Up"适合完全初学者
从没写过代码吗？太好了！ UI-Probe 是为您量身打造的：
- 安装它 （一次性设置，5分钟）
- 告诉它要测试什么 用平实的英语（或：用通俗易懂的英语）
- 获得明确的结果 - “✅ 账户已创建”或“❌ 注册按钮被隐藏”
非开发者的示例
想每天测试你的网站联系表单吗？只需输入：
# In Claude, you can be natural:
"Test the contact form on my homepage"
# Claude figures out the URL from context, or you can be explicit:
fill_form "https://mysite.com/contact" {"message": "Testing!"}就这样。无需编程。
对于开发者
UI-Probe 提供给您：
- 自愈合测试 - 当用户界面（UI）变化时自动适应
- 代码减少了80% - 一条生产线，而非数十条
- 人工智能驱动的智能 - 使用GPT-4/Claude来理解页面内容
- 清晰的错误信息 - “按钮被cookie横幅遮挡” vs “元素不可交互异常”
快速入门（5分钟）
🎯 长文短说 - 快速上手
npx mcp-ui-probe setup # 1. Install browsers (one-time)
echo "OPENAI_API_KEY=sk-..." > .env # 2. Add API key (optional but recommended)
curl -sSL https://raw.githubusercontent.com/Hulupeep/mcp-ui-probe/main/scripts/claude-setup.sh | bash # 3. Connect to Claude
claude # 4. Start using!先决条件
- Node.js 18+（下载 - 只需点击安装程序中的“下一步”即可
- Claude CLI代码或任何终端
- OpenAI或Anthropic API密钥 （智能功能所需，请参阅下方的成本估算）
系统要求
- 操作系统（Operating System，简称OS）Windows、macOS 或 Linux
- Node.js版本18或更高版本
- 磁盘空间Playwright 浏览器的下载大小约为 500MB（一次性下载）
- RAM（随机存取存储器）最小2GB，建议4GB
选项1：使用 npx（最简单 - 任何地方都可用！）
步骤1：初始设置（仅一次）
# Install Playwright browsers needed for web testing (~500MB, takes 2-3 minutes)
npx mcp-ui-probe setup步骤2：配置大型语言模型（LLM）提供商（智能功能必需）
UI-Probe需要API密钥来进行智能表单理解和工作流执行：
# Create a .env file in your current directory
echo "OPENAI_API_KEY=your-key-here" > .env
# OR for Anthropic
echo "ANTHROPIC_API_KEY=your-key-here" > .env
# Optional: Enable fallback mode for basic Playwright functionality without LLM
echo "UI_PROBE_FALLBACK_MODE=true" >> .env重要提示： 没有有效的API密钥，智能功能将无法使用：
- 🤖 表单字段推断与理解
- 🤖 自然语言工作流程分解
- 🤖 智能错误信息增强
- 🤖 自适应元素检测
看 成本估算 以下是API使用费用的相关部分。
步骤3：连接到Claude Code CLI
为什么要多这一步？ Claude CLI 代码找不到 npx 它本身无法做到，因为它无法访问你shell的PATH环境变量。你需要告诉Claude在你的电脑上npx的确切位置。
选项A：自动设置（最简单 - 为您完成所有操作）：
# This script will:
# 1. Find where npx is installed on your computer
# 2. Add UI-Probe to Claude with the correct path
# 3. Verify everything is configured properly
curl -sSL https://raw.githubusercontent.com/Hulupeep/mcp-ui-probe/main/scripts/claude-setup.sh | bash运行此程序后，只需重启Claude，UI-Probe即可使用！
选项B：手动设置（如果自动设置不起作用）：
步骤1：找到你的npx路径
# On macOS/Linux:
which npx
# Example output: /usr/local/bin/npx or ~/.nvm/versions/node/v20.11.0/bin/npx
# On Windows:
where npx
# Example output: C:\Program Files\nodejs\npx.cmd步骤2：向Claude添加完整路径
# Use YOUR path from Step 1:
claude mcp add ui-probe "/full/path/to/npx" "mcp-ui-probe@latest" "start"
# Real examples:
# Standard Node:
claude mcp add ui-probe "/usr/local/bin/npx" "mcp-ui-probe@latest" "start"
# Using 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"步骤4：在Claude中开始使用UI-Probe！
# Start Claude Code CLI
claude
# UI-Probe tools are now available! Try:
# - Navigate to websites
# - Analyze page elements
# - Fill and submit forms
# - Run complete test flows步骤5：（可选）尝试测试游乐场
想在测试自己的网站之前先看看UI-Probe的实际操作吗？
# Start the built-in test server with example forms
npx mcp-ui-probe test-server # Runs on http://localhost:8081/test
npx mcp-ui-probe test-server --port 3000 # Use custom port if 8081 is busy
# Visit http://localhost:8081/test in your browser to see the playground
# Then in Claude, try: run_flow "Sign up as new user" "http://localhost:8081/test"选项2：从源代码安装
# Clone it (this downloads the code)
git clone https://github.com/Hulupeep/mcp-ui-probe.git
cd mcp-ui-probe
# Install it (this sets everything up)
npm install
# CRITICAL: Install browsers (one-time, takes 2-3 minutes)
npx playwright install
# Add to Claude:
claude mcp add ui-probe "node" "/path/to/mcp-ui-probe/dist/index.js"开始测试！
# In Claude, just describe what you want:
"Test if users can sign up on example.com"
# Or be specific:
run_flow "Go to https://example.com/signup and create an account"UI-Probe在Claude中的工作原理
自然语言（默认 - 正常交谈即可！）
UI-Probe 理解您的意图：
# Just describe what you want - UI-Probe figures it out:
"Test if users can sign up on example.com"
"Check if the checkout process works"
"Fill out the contact form with test data"
"Click the submit button"明确指令（当您需要精确控制时）
有时候，你需要明确具体该做什么：
# Use explicit commands for precise control:
navigate "https://staging.myapp.com/login" # Go to exact URL
fill_form "https://myapp.com/contact" {"message": "Test"} # Fill specific fields
click_button "Submit Order" # Click exact button text
assert_element "div.success" "visible" # Check specific element最佳实践： 从自然语言开始。如果UI-Probe需要澄清或您需要精确控制，请切换到明确的命令。
常见任务
测试登录表单
# Natural language (recommended to start):
"Test if users can log in to myapp.com"
"Check the login flow"
# Explicit commands (for precise control):
navigate "https://myapp.com/login"
fill_form {"email": "test@example.com", "password": "password123"}
click_button "Sign In"
verify_page {"expectedContent": ["Dashboard", "Welcome"]}测试购买
# Natural language:
"Buy a blue shirt from shop.com"
"Test the checkout process with a test credit card"
# Explicit commands:
navigate "https://shop.com"
click_button "Shirts"
click_button "Blue Cotton Tee"
click_button "Add to Cart"
fill_form {"card": "4111111111111111", "exp": "12/25", "cvv": "123"}
click_button "Complete Order"测试表单验证
# Test what happens with bad data:
fill_form "https://myapp.com/signup" {"email": "not-an-email"}
# UI-Probe tells you: "❌ Email validation error appeared"检查某物是否存在
assert_element "https://myapp.com" "Free shipping" "visible"
# Returns: "✅ Found 'Free shipping' on page"UI-Probe的独特之处何在
传统测试工具
- 使用特定选择器编写代码
- 当用户界面发生变化时，测试会失败
- 隐晦的错误信息
- 需要编程知识
- 数百行代码
UI-Probe（中文可译为“用户界面探测器”或根据具体上下文简化为“界面探测工具”等）
- 用简单的英语描述
- 用户界面变化时的自我修复
- 清晰、人性化的错误提示
- 无需编程
- 一行代码搞定一切
现实世界中的例子
电子商务网站
# Complete purchase flow
"Buy the cheapest laptop on the site"
# UI-Probe automatically:
# - Finds the shop
# - Searches for laptops
# - Sorts by price
# - Adds to cart
# - Fills checkout
# - Completes purchaseSaaS应用
# Test free trial signup
"Sign up for a free trial with a company email"
# UI-Probe:
# - Navigates to signup
# - Detects it's a business form
# - Fills company fields
# - Uses appropriate test data
# - Verifies trial activated银行应用程序
# Test money transfer
"Transfer $50 from checking to savings"
# UI-Probe:
# - Logs in securely
# - Navigates to transfers
# - Fills amount
# - Selects accounts
# - Confirms transfer🏗️ 架构概述
UI-Probe 被构建为一个智能的、有状态的测试编排器，而不仅仅是一个简单的脚本运行器：
┌─────────────────────────────────────────────────────────┐
│ Claude Code CLI │
│ (Natural Language) │
└────────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ MCP Server (Persistent) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Intelligent Components │ │
│ │ • LLM Strategy Engine (GPT-4/Claude) │ │
│ │ • Workflow Decomposer │ │
│ │ • Adaptive Executor │ │
│ │ • Form Inference Engine │ │
│ │ • Error Enhancer │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Journey System │ │
│ │ • Journey Recorder & Player │ │
│ │ • Journey Validator & Analyzer │ │
│ │ • Journey Discovery & Storage │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Playwright Driver (Stateful) │ │
│ │ • Persistent browser context │ │
│ │ • Smart selector generation │ │
│ │ • Automatic retry & recovery │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Your Web Application │
└─────────────────────────────────────────────────────────┘关键建筑优势：
- 持久服务器 - 无启动开销，跨测试保持状态
- 智能层 - 基于大型语言模型（LLM）的理解，而不仅仅是自动化
- 旅程系统 - 一次性录制，多次播放并做变化
- 有状态上下文 - 记住登录会话、之前的交互
- 自适应执行 - 根据页面行为调整策略
______________________________________________________________________
🔬 技术架构（面向大型语言模型与开发者）
请求流程：从自然语言到执行
User → "Search for blue t-shirt on Amazon"
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. MCP Server (src/server/MCPServer.ts:1270-1524) │
│ handleRunFlow(goal: "Search for blue t-shirt") │
└──────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. LLM Strategy (src/llm/llmStrategy.ts:86-148) │
│ ✨ CALLS OPENAI API │
│ parseGoal("Search for blue t-shirt") │
│ → { │
│ action: "fill", │
│ target: "search bar", │
│ targetType: "input", │
│ value: "blue t-shirt", ← PARSED VALUE │
│ submit: true │
│ } │
└──────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Form Inference (src/infer/form.ts) │
│ Analyzes page to understand form structure: │
│ → { │
│ name: "site-search", │
│ fields: [ │
│ {name: "field-keywords", type: "text"}, ← TARGET │
│ {name: "nav-search-submit-button", type: "submit"} │
│ ] │
│ } │
└──────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Override Creation (src/server/MCPServer.ts:1404-1441) │
│ ✨ CRITICAL FIX: Maps LLM value to field name │
│ overrides = { │
│ "field-keywords": "blue t-shirt" ← Uses LLM value │
│ } │
│ (Instead of random "sample384") │
└──────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 5. Flow Engine (src/flows/flowEngine.ts:15-89) │
│ executeFlow(page, formSchema, overrides) │
│ For each field: │
│ - Checks overrides first │
│ - Uses LLM value if present │
│ - Generates random data only if not in overrides │
└──────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 6. Playwright Execution │
│ page.fill("#field-keywords", "blue t-shirt") ✅ │
│ page.click("#nav-search-submit-button") │
└─────────────────────────────────────────────────────────────┘OpenAI 集成点
UI-Probe 在这些特定点使用 OpenAI GPT-4（全部在 src/llm/llmStrategy.ts)：
1. 目标解析（第86-148行）
async parseGoal(goal: string): Promise
- 输入自然语言目标（“搜索蓝色T恤”）
- 输出具有结构化的动作对象
{action, target, value} - OpenAI 通话:
openai.chat.completions.create()在第261行 - 模型：
gpt-4-turbo-preview（可通过LLM_MODEL） - 成本每请求约0.01-0.05美元
- 备用方案/回退方案如果API失败，则使用正则表达式解析器
UI_PROBE_FALLBACK_MODE=true
已向OpenAI发送提示 （第322-358行）：
Parse this UI testing goal into structured actions:
"Search for blue t-shirt"
Return JSON:
{
"action": "fill",
"target": "search bar",
"value": "blue t-shirt",
"submit": true
}2. 替代选择器建议（第224-238行）
async suggestAlternatives(failedSelector: string, pageContent: string): Promise- 当被调用时仅当主选择器失效时
- 输入选择器失败 + 页面HTML片段
- 输出尝试的一系列备选选择器
- 示例：
.submit-button失败 → 表明["button[type='submit']", "[aria-label='Submit']"]
3. 错误解释（第150-163行）
async interpretError(error: string, context: any): Promise- 当被调用时当测试失败时
- 输入错误信息 + 页面上下文
- 输出可读性强的解释 + 恢复建议
- 示例“元素不可点击” → “元素可能被覆盖层遮挡，尝试关闭模态框”
4. 文本填空（第168-222行）
async complete(prompt: string): Promise- 被用于自定义集成与未来功能
- 当前使用情况最小值（保留用于高级功能）
关键文件与职责
src/
├── server/
│ └── MCPServer.ts # Main MCP server, request handling
│ ├── handleRunFlow() # Entry point for natural language goals
│ ├── handleClickButton() # Button clicking with AI fallback
│ └── handleNavigate() # Page navigation
│
├── llm/
│ ├── llmStrategy.ts # ✨ OpenAI integration hub
│ │ ├── parseGoal() # Natural language → structured action
│ │ ├── suggestAlternatives() # Selector recovery
│ │ ├── interpretError() # Error analysis
│ │ └── callLLM() # Core OpenAI API wrapper
│ │
│ ├── workflowDecomposer.ts # Multi-step workflow parsing
│ └── adaptiveExecutor.ts # Execution with retry logic
│
├── flows/
│ └── flowEngine.ts # Form execution engine
│ ├── executeFlow() # Runs through form fields
│ ├── fillField() # Fills individual field
│ └── Uses overrides map to prioritize LLM values
│
├── infer/
│ └── form.ts # Form structure analysis
│ └── inferForm() # Analyzes page to understand forms
│
└── utils/
├── dataSynthesizer.ts # Test data generation
│ └── generateFieldData() # Creates field values (checks overrides first)
└── goalParser.ts # Regex-based fallback parser数据流示例：亚马逊搜索
// User command via MCP
run_flow({ goal: "Search for blue t-shirt" })
// Step 1: MCPServer.handleRunFlow()
const parsedGoal = await llmStrategy.parseGoal(goal);
// OpenAI returns: {action: "fill", value: "blue t-shirt"}
// Step 2: Analyze page structure
const analysis = await analyzeUI();
// Finds: search form with field-keywords input
// Step 3: Create overrides (THE FIX!)
const overrides = {
"field-keywords": "blue t-shirt" // Maps LLM value to field name
};
// Step 4: Execute with overrides
await flowEngine.executeFlow(page, formSchema, overrides);
// → Calls dataSynthesizer.generateFieldData(field, overrides)
// → Checks overrides["field-keywords"] first
// → Returns "blue t-shirt" (not random data!)
// Step 5: Playwright fills the field
await page.fill("#field-keywords", "blue t-shirt");
await page.click("#nav-search-submit-button");
// ✅ Result: Searches for "blue t-shirt", not "sample384"环境配置
# Required for LLM features
OPENAI_API_KEY=sk-... # OpenAI API key
LLM_MODEL=gpt-4-turbo-preview # Model selection
LLM_TEMPERATURE=0.3 # Response randomness (0-1)
# Optional
UI_PROBE_FALLBACK_MODE=false # Set true to disable LLM calls
LLM_CACHE_ENABLED=true # Cache LLM responses (5 min TTL)
LLM_REQUEST_TIMEOUT=60000 # API timeout in ms
LLM_MAX_RETRIES=2 # Retry failed API calls
# Cost controls
UI_PROBE_COST_LIMITS=true # Enable cost tracking
UI_PROBE_MAX_COST=10 # Max spend in USD常见的集成模式
模式1：以大型语言模型（LLM）为主，辅以备用方案
// Try LLM parsing first, fall back to regex if fails
const parsed = await llmStrategy.parseGoal(goal);
// If LLM unavailable or fails → uses GoalParser.parse() as fallback模式2：先启发式搜索后大型语言模型（LLM）恢复
// Try Playwright selectors (15+ patterns)
if (!found) {
// Fall back to AI element detection
const aiSelector = await findClickableElementWithAI(page, text);
}模式3：用于降低成本的缓存
// LLM responses cached for 5 minutes
// Same goal → uses cached response, no API call
if (cacheEnabled && cached) {
return cached;
}
const response = await callLLM(prompt);
cache.set(goal, response);调试大型语言模型（LLM）集成
启用调试日志记录
export LOG_LEVEL=debug
export UI_PROBE_DEBUG=true检查是否正在调用OpenAI
# Look for these log messages:
[DEBUG] Attempting LLM goal parsing (attempt 1/3)
[DEBUG] LLM goal parsing succeeded
[INFO] Using LLM-parsed value for field查看大型语言模型（LLM）成本
// Check usage tracker (src/monitoring/usageTracker.ts)
const stats = llmStrategy.getUsageTracker()?.getStats();
console.log(`Total cost: $${stats.totalCost}`);
console.log(`Total tokens: ${stats.totalTokens}`);不使用大型语言模型的测试
# Use fallback mode for testing without API costs
UI_PROBE_FALLBACK_MODE=true npm start性能特性
| 操作 | 时间 | 成本 | 缓存 |
|---|---|---|---|
| 目标解析（缓存） | \ 表单数据（formData）> 约束条件 > 生成的数据 |
- 兼容性与现有数据合成器配合使用
- 可测试性易于注入测试数据
______________________________________________________________________
内置测试游乐场
UI-Probe 包含一个全面的测试平台，供您在部署到项目之前进行尝试：
# Start the test server (runs on port 8081)
npm run test:server
# Visit http://localhost:8081/test in your browser to see the playground可用的测试页面：
- 主测试页面 (
/test- 完成带验证的注册表单 - 表单测试 （
/test/forms- 每种输入类型（文本、选择、单选、复选框等） - 导航测试 (
/test/navigation) - 多页导航和路由 - 动态内容 (
/test/dynamic) - 由JavaScript驱动的用户界面更新 - 验证场景 (
/test/validation) - 错误处理和边界情况
在Claude上的测试：
# Analyze form structure
analyze_ui "http://localhost:8081/test/forms"
# Fill and submit forms
fill_form "http://localhost:8081/test/forms" {"firstName": "John", "email": "john@example.com"}
# Run complete flows
run_flow(goal="Sign up as new user", url="http://localhost:8081/test")
## Cost Estimation
UI-Probe uses LLM API calls for intelligent features. Here's what to expect:
| Operation | GPT-4 Tokens | Estimated Cost | Frequency |
|-----------|--------------|----------------|-----------|
| Navigate (basic) | 0 | $0.000 | Per page |
| Navigate (with LLM analysis) | ~500 | $0.005 | Per page |
| Form Analysis (LLM) | ~1000 | $0.010 | Per form |
| Error Collection (LLM enhanced) | ~300 | $0.003 | Per test |
| UI Analysis (LLM) | ~800 | $0.008 | Per page |
| Complete Workflow (run_flow) | ~2000 | $0.020 | Per test |
### Cost Examples:
- **Per Test Suite** (10 tests with LLM): ~$0.30-$1.00
- **Per Month** (1000 tests with LLM): ~$30-$100
- **Fallback Mode**: $0.00 (no LLM calls)
### Cost Optimization Tips:
1. Use **fallback mode** for basic navigation and clicking
2. Enable **LLM caching** to reduce repeated API calls
3. Use explicit selectors when you know the exact element
4. Reserve `run_flow` for complex workflows that truly need intelligence
5. Monitor usage through your OpenAI/Anthropic dashboard
## Fallback Mode
UI-Probe can operate in fallback mode without LLM, providing basic Playwright functionality:
### Enable Fallback Mode:In .env file:
UI_PROBE_FALLBACK_MODE=true
### 在回退模式下有效（无需API密钥）：
- ✅ **基本导航** - `navigate(url)`
- ✅ **元素点击** - 使用明确的选择器
- ✅ 翻译成中文是：✓（对号，表示正确或确认） **填写表格** - 带有明确的字段名称
- ✅ **屏幕截图** - 捕获页面状态
- ✅ **简单的断言** - 检查元素是否存在
- ✅ **旅程回放** - 使用明确选择器记录的行程
### 需要大型语言模型（需API密钥）的内容：
- 机器人 **自然语言工作流** - “注册为新用户”
- 🤖 机器人 **表单推断** - 自动表单结构理解
- 🤖 表情符号“🤖”通常被用来表示机器人，或者以一种拟人化的方式表达“机器人”相关的概念，比如机器人说话、机器人思考等，也可以用来形容某人或某物像机器人一样呆板、机械。在中文中，这个表情符号可以直接用“🤖”来表示，或者根据上下文翻译为“机器人”、“机器人表情”等，具体翻译方式取决于语境和表达需要。 **智能元素检测** - 查找没有精确选择器的元素
- 机器人🤖 **误差增强** - 智能错误提示
- 机器人 **旅程分析** - 人工智能驱动的优化
- 机器人 **自适应执行** - 用户界面（UI）变化时的自我修复
**建议**从简单测试的回退模式开始，需要智能功能时再添加API密钥。
## 配置
### 基本配置（.env 文件）
Required for intelligent features (see Cost Estimation above)
OPENAI_API_KEY=sk-...
OR
ANTHROPIC_API_KEY=your-key
Optional: Use fallback mode without LLM
UI_PROBE_FALLBACK_MODE=true
See the browser window
HEADLESS=false
Show detailed logs
DEBUG=true
### 高级选项
Timeout for slow sites (milliseconds)
TIMEOUT=60000
Retry failed operations
MAX_RETRIES=5
Take screenshots on failure
SCREENSHOT_ON_FAILURE=true
LLM Configuration
LLM_PROVIDER=openai # or 'anthropic' LLM_MODEL=gpt-4-turbo-preview LLM_CACHE_ENABLED=true # Reduce costs by caching responses
## 故障排除
### 在 Claude Code CLI 中显示“连接失败”或“连接未建立”
**问题：** 当你运行时，Claude 显示 ui-probe 为“失败”或无法连接 `claude mcp list`。
**解决方案：** Claude Code CLI 需要 npx 的完整路径，而不仅仅是“npx”。
1. **找到你的npx位置：**
which npx # Mac/Linux where npx # Windows
1. **移除损坏的配置：**
claude mcp remove ui-probe
1. **加上完整路径：**
# Use YOUR actual path from step 1 claude mcp add ui-probe "/path/from/step1/npx" "mcp-ui-probe@latest" "start"
1. **开始一个新的Claude Code会话**
claude # The MCP server will now connect properly
**常见的npx位置：**
- 标准 Node.js： `/usr/local/bin/npx`
- NVM（Node.js 版本管理器）： `~/.nvm/versions/node/vXX.XX.X/bin/npx`
- Homebrew（Mac）： `/opt/homebrew/bin/npx`
- Windows： `C:\Program Files\nodejs\npx.cmd`
### “启动测试服务器时，端口已被使用”
**解决方案：** 使用不同的端口：
npx mcp-ui-probe test-server --port 3000
### “导航失败”
无法访问该网站。请检查：
1. 网址正确吗？
1. 网站在运行吗？（针对本地主机）
1. 跑 `npx playwright install` （如果你还没的话）
### “元素未找到”
按钮/表单/链接不存在。请尝试：
1. `analyze_ui "URL"` 查看页面上的内容
1. `wait_for "URL" "element" "visible"` 对于加载缓慢的内容
1. 更具体一些：“蓝色的提交按钮”与仅仅“提交”
### 表格无法填写
自定义表单元素。尝试：
1. `analyze_ui` 查看UI-Probe检测到的内容
1. 使用 `click` 用于自定义下拉菜单
1. 使用 `run_flow` 对于复杂交互
## 🎬 行程记录与回放系统
**新功能！** UI-Probe 现在包含了一个智能行程记录系统，该系统消除了重复发现用户界面流程的需求。
### ⚡ 测试速度提升80%
一次性记录用户交互，即时回放：
Record a complete signup flow
journey_record_start {"name": "User Signup", "description": "Complete signup from landing page"}
Perform your interactions...
journey_record_stop {"tags": ["auth", "signup"], "category": "user-onboarding"}
Replay instantly later
journey_play {"journeyId": "journey_20250925_123456", "config": {"speed": 1.5}}
### 🤖 人工智能驱动的智能
- **智能命名**AI生成有意义的旅程名称和描述
- **上下文验证**确保旅程仅在适当时候运行（不能在注册页面下单）
- **自修复选择器**适应用户界面变化，具备多种回退策略
- **模式识别**建议类似的旅程和优化方案
### 🔍 旅程探索
Find journeys compatible with your current page
journey_discover {"url": "https://mysite.com/login", "limit": 5}
Search by tags, category, or success rate
journey_search {"query": "checkout", "tags": ["payment"], "minSuccessRate": 0.8}
### 📊 成功追踪
每次行程都会记录：
- 多次运行的成功率
- 性能指标和时间安排
- 使用统计
- 难度估计
### 🎯 优势/好处
- **速度快80%** 通过省略元素发现来执行测试
- **自我修复** - 旅程自动适应用户界面变化
- **可重复使用** - 在团队和项目之间分享经验历程
- **可发现的** - 基于人工智能的搜索功能可找到相关流程
- **可靠的** - 上下文验证可防止执行不匹配
📖（书本的符号，可直接意译为“书”或根据上下文具体翻译） **看见 [完整的旅程系统文档](docs/JOURNEY_SYSTEM.md)** 用于高级功能和使用模式。
## 智能功能
### 自动测试数据
UI-Probe 生成适当的测试数据：
- 通过验证的有效电子邮件
- 符合要求的强密码
- 格式正确的电话号码
- 真实的姓名和地址
- 测试信用卡卡号（4111111111111111）
### 自我修复测试
当开发者发生变化时：
- 类名 → UI-Probe 仍然能找到按钮
- IDs → 仍然有效
- 页面结构 → 自动适应
- 文本标签 → 理解上下文
### 清晰的错误信息
❌ Traditional: "WebDriverException: unknown error: Element is not clickable at point (780, 532)"
✅ UI-Probe: "The submit button is hidden behind a cookie consent banner. Try dismissing the banner first."
## 响应结构
MCP UI-Probe 提供两种确定性的 JSON 响应：
### 简单工具响应
单个工具命令（`navigate`， `click_button`， `analyze_ui`等。）返回：
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `success` | 布尔值 | 操作成功状态 |
| `data` | 对象 | 特定工具的响应数据 |
| `error` | 字符串 | 错误信息（当 success=false 时） |
**示例：**
{ "success": true, "data": { "clicked": true, "selector": "button:has-text(\"Submit\")", "currentUrl": "http://example.com/success", "pageTitle": "Success Page" } }
### 复杂的测试执行响应
综合测试命令（`run_flow`， `fill_and_submit`) 返回包含以下内容的详细报告：
- 完整的测试执行流程，包含所有步骤
- 性能指标和时间安排
- 错误收集与分类
- 无障碍性研究结果
- 测试工件和证据
这种确定性结构实现了智能自动化：
// Simple tool for conditional logic const result = await ui_probe.click_button({ text: "Submit" }); if (result.success) { console.log(Navigated to: ${result.data.currentUrl}); } else { console.log(Failed: ${result.error}); }
// Complex command for full test execution const testResult = await ui_probe.run_flow({ goal: "Complete signup process", url: "http://example.com/signup" }); console.log(Test ${testResult.result}: ${testResult.metrics.steps} steps)
📖 书籍 **看见 [完整响应文件/记录](docs/RESPONSE_STRUCTURE.md)** 关于简单和复杂响应类型的全面详细信息。
## API 参考文档
### 核心测试命令
| 命令 | 功能 | 示例 |
|---------|--------------|---------|
| 项目 | 描述 | 数值 | `navigate` | `navigate "https://site.com"` | 转到某页 |
| `analyze_ui` | `analyze_ui "https://site.com"` | 查看页面内容 |
| `fill_form` | `fill_form "URL" {"field": "value"}` | 填写一份表格 |
| `run_flow` | `run_flow "Sign up and verify email"` | 执行多个步骤 |
| `click_button` | `click_button { text: "Submit" }` | 点击按钮 |
| `assert_element` | `assert_element "URL" "text" "visible"` | 检查某物是否存在 |
| `wait_for` | `wait_for "URL" "Loading..." "hidden"` | 等待某事 |
### |
行程记录与回放命令
| 命令 | 功能 | 示例 |
|---------|--------------|---------| `journey_record_start` | `journey_record_start {"name": "Login Flow"}` | 开始记录交互 |
| `journey_record_stop` | `journey_record_stop {"tags": ["auth"]}` | 停止并保存录音 |
| `journey_play` | `journey_play {"journeyId": "journey_20250925_123456"}` | 重播已保存的旅程 |
| `journey_validate` | `journey_validate {"journeyId": "journey_20250925_123456"}` | 检查行程是否可运行 |
| `journey_search` | `journey_search {"query": "login", "tags": ["auth"]}` | 搜索已保存的旅程 |
| `journey_discover` | `journey_discover {"url": "https://site.com/login"}` | 查找兼容行程 |
| `journey_list` | `journey_list {"category": "auth"}` | 列出所有旅程 |
| `journey_analyze` | `journey_analyze {"journeyId": "journey_20250925_123456"}` | 获取AI分析 |
| **📖 书籍 [看](docs/API_REFERENCE.md)** 完整的API参考
## 以获取详细参数和响应结构。
### 与playwright-mcp的比较
**快速概要** UI-Probe（中文可译为“用户界面探测器”或根据具体语境简化为“界面探查工具”） **并且** playwright-mcp 翻译为中文是“playwright 多进程控制（或框架/模块）”。不过，具体翻译可能需要根据上下文来确定“mcp”在这里的确切含义，因为“mcp”在不同领域可能有不同的解释。在这里，我将其理解为与 Playwright 相关的一个多进程控制或扩展功能模块
- **是互补工具，而非竞争对手：**playwright-mcp 翻译为中文是“Playwright MCP（可能指某种特定配置或模式，具体需根据上下文确定）”。不过，由于“MCP”在不同上下文中可能有不同的含义，这里直接按照字面意思进行了翻译。如果“MCP”有特定的行业或技术含义，那么翻译时可能需要加入相应的解释或调整
- **为AI代理提供基本浏览器命令的底层基础设施工具**UI-Probe（用户界面探针）
### 面向最终用户的高级测试应用程序，配备简洁易懂的英文界面
关键差异
| 方面 | playwright-mcp | UI-Probe |
|--------|---------------|----------| **|** 目标用户
| 开发人员构建AI代理 | 非技术人员用户（产品经理、设计师、质量保证人员） | **|** 接口`browser_click`基于元素的（ `browser_type`，`run_flow "Sign up"`基于意图的
）| **|** 自我修复
| 不因DOM变化而中断 | 是 - 使用AI适应变化 | **|** 测试数据
| 用户必须提供 | 自动生成有效数据 | **|** 设置
| 单个 npx 命令 | 克隆仓库 + npm 安装 | **|** 需要代码
| 是 - 克劳德编写测试脚本 | 否 - 立即工作 | **|** 响应格式
### | 原始浏览器事件 | 用于自动化的结构化JSON |
关键优势：无需代码生成 **随着**playwright-mcp 可以翻译为“Playwright MCP”或根据上下文具体含义进一步细化，但在这里，一个通用且直接的翻译是“Playwright MCP（或Playwright的MCP，具体含义需根据上下文确定）”。不过，如果“mcp”在这里没有特定的含义，或者是一个特定项目、配置或模式的缩写，那么直接翻译为“Playwright MCP”可能已经足够，具体含义需结合上下文理解
// Claude has to generate this for every test await page.goto('http://example.com'); await page.fill('#email', 'test@example.com'); await page.click('button[type="submit"]'); // Error handling, retries, validation...
克劳德必须编写并执行测试代码： **随着**UI-Probe 翻译成中文是“用户界面探针”
"Test the login form"
That's it - no code generation needed
### ，只需描述你想要的：
用于自动化的确定性JSON
// UI-Probe response - always structured the same way { "success": true, "data": { "formSubmitted": true, "validationErrors": [], "nextUrl": "/dashboard" } }
// This enables intelligent automation: if (!response.success) { // Handle failure automatically useAlternativeFlow(); }
### 每个UI-Probe操作都会返回可预测的JSON，以支持条件逻辑：
- 最终结论 **使用** playwright-mcp 可以翻译为“Playwright MCP（或特定于Playwright的MCP，具体含义需根据上下文确定）”。不过，由于“MCP”本身是一个缩写，其具体含义可能因领域或上下文而异，这里直接保留了原缩写形式。如果“MCP”在特定上下文中有明确含义，如“Microsoft Certified Professional”（微软认证专业人员）或其他专业术语，则应根据具体情况进行翻译。但在此通用翻译中，我们保持其原样
- 如果你是一名开发者，正在构建一个需要浏览器控制的AI代理 **使用** UI-Probe（可译为“用户界面探测器”或根据具体上下文调整为更贴切的表述）
如果你想测试网站而无需编写代码
**可以将playwright-mcp视为引擎，而UI-Probe则是围绕其构建的用户友好型汽车。 [→ 如需详细对比，请参阅](docs/comparison.md)**
## docs/comparison.md 翻译为中文是：docs/对比.md
贡献；做出贡献 [我们热爱贡献！快来看看](docs/CONTRIBUTING.md)CONTRIBUTING.md（贡献指南文件）
## .
- **支持** [文档：](docs/)
- **完整的文档** [示例：](examples/)
- **更多示例** [问题：](https://github.com/yourusername/mcp-ui-probe/issues)
- **报告问题** [讨论：](https://github.com/yourusername/mcp-ui-probe/discussions)
## 提问
许可证
______________________________________________________________________
**麻省理工学院（MIT）——你想怎么用就怎么用！**
别再写会出错的代码了。像人一样开始进行测试吧。 [准备好了吗？](#quick-start-5-minutes) 立即安装 [或者](#common-tasks)