browser-test-mcp

Playwright × browser-use 共生浏览器自动化测试 MCP Server

把两个顶级开源项目融合为一个 MCP server：AI 智能决策与精确测试执行共生，两层工具操作同一个浏览器实例，随时无缝切换。

┌──────────────────────────────────────────────────────────┐
│  browser-test MCP（单进程，59 个工具）                      │
│                                                            │
│  AI 层：browser-use（官方代码原封不动，16 个工具）           │
│    browser_navigate / browser_click / browser_type /       │
│    browser_get_state / retry_with_browser_use_agent ...    │
│  ──────────────────────────────────────────────────────── │
│  精确层：playwright-python（官方 API 薄封装，43 个工具）     │
│    pw_navigate / pw_fill / pw_click / pw_assert_*          │
│    pw_wait_* / pw_screenshot / pw_network / pw_trace ...   │
│  ──────────────────────────────────────────────────────── │
│  共享会话：playwright 启动 chromium（CDP 调试端口）          │
│  browser-use 通过 cdp_url 连接同一浏览器实例                 │
└──────────────────────────────────────────────────────────┘

核心特性

• 共生：AI 层（browser-use）自主探索复杂页面，精确层（Playwright）做确定性操作与断言——两层共用同一浏览器、同一页面，随时切换
• 测试完整：导航、填表、点击、断言（文本/可见/URL/数量）、等待、网络捕获、截图、登录态复用、trace 调试
• 内置 stealth 反检测：自研零依赖模块，10 个维度伪装（webdriver/plugins/userAgentData/chrome 对象/canvas/WebGL/Client Hints…），bot.sannysoft.com 专业检测站零失败项
• 无头默认：后台跑测试不弹窗（BROWSER_TEST_HEADLESS=0 可开有头）
• 不改上游一行代码：融合全部通过组合 + 运行时配置注入实现

快速开始

pip install -r requirements.txt
playwright install chromium        # 首次下载浏览器（可选：channel=chrome 用系统 Chrome）
python server.py                   # 直接跑（stdio 模式）

注册到任意 MCP 客户端

// Claude Desktop / Cursor / Reasonix 等
{
  "mcpServers": {
    "browser-test": {
      "command": "python",
      "args": ["/path/to/browser-test-mcp/server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-...",                    // AI 层 Agent 需要（可选）
        "OPENAI_BASE_URL": "https://api.deepseek.com", // OpenAI 兼容 provider（可选）
        "BROWSER_USE_LLM_MODEL": "deepseek-v4-flash",  // AI 层模型（可选）
        "BROWSER_TEST_HEADLESS": "1"                    // 1=无头（默认）0=有头
      }
    }
  }
}

冒烟测试

PYTHONIOENCODING=utf-8 python test_smoke.py   # 59 工具 + 共享会话验证
python test_fusion.py                          # 两层交叉操作验证

工具清单

AI 层（browser-use，16 个）：browser_navigate、browser_click、browser_type、browser_get_state、browser_extract_content、browser_get_html、browser_screenshot、browser_scroll、browser_go_back、browser_list_tabs、browser_switch_tab、browser_close_tab、browser_list_sessions、browser_close_session、browser_close_all、retry_with_browser_use_agent

精确层（Playwright，43 个）：

类别	工具
浏览器	pw_browser_info、pw_close_browser
导航	pw_navigate、pw_reload、pw_go_back、pw_go_forward
页面	pw_list_pages、pw_new_page、pw_switch_page、pw_close_page
元素	pw_click、pw_fill、pw_press、pw_select_option、pw_check、pw_uncheck、pw_hover、pw_dblclick、pw_clear_input、pw_upload_files、pw_drag_and_drop
读取	pw_get_text、pw_get_attribute、pw_get_value、pw_get_url、pw_get_title、pw_get_html、pw_evaluate、pw_screenshot
等待	pw_wait_for_selector、pw_wait_for_url、pw_wait_for_load_state
断言	pw_assert_text、pw_assert_visible、pw_assert_url、pw_assert_count
网络	pw_network_requests、pw_clear_network_log、pw_wait_for_response
登录态	pw_save_storage_state、pw_load_storage_state
调试	pw_trace_start、pw_trace_stop

环境变量

变量	默认	说明
BROWSER_TEST_HEADLESS	1	无头模式；0 = 有头（调试看界面）
BROWSER_TEST_CDP_PORT	9222	CDP 调试端口（browser-use 连接用）
BROWSER_TEST_USER_AGENT	Chrome/150	UA 覆盖（可改）
BROWSER_TEST_CHANNEL	空	用系统浏览器：chrome / msedge（指纹更真实）
OPENAI_API_KEY / ANTHROPIC_API_KEY	无	AI 层 LLM
OPENAI_BASE_URL	空	OpenAI 兼容 provider 地址
BROWSER_USE_LLM_MODEL	空	AI 层模型名
BROWSER_USE_ADD_SCHEMA_TO_SYSTEM_PROMPT	0	1 = schema 进 system prompt（兼容不支持 response_format 的 provider）
BROWSER_USE_DONT_FORCE_STRUCTURED_OUTPUT	0	1 = 不强制结构化输出（配合上行）
BROWSER_USE_REMOVE_MIN_ITEMS_FROM_SCHEMA	0	1 = 移除 schema 中 minItems（部分 provider 兼容）

标准测试工作流

1. pw_navigate(url)                 打开被测页面
2. pw_wait_for_selector / pw_assert_url   确认页面就绪
3. pw_fill(selector, value)         填表单
4. pw_click(selector)               触发交互
5. pw_wait_for_response / pw_wait_for_url 等待结果（接口/跳转）
6. pw_assert_text / pw_assert_*     断言，记录 PASS/FAIL
7. pw_screenshot                    留证
8. pw_close_browser                 清理

页面复杂时用 retry_with_browser_use_agent 交给 AI 智能体自主完成，再用精确层断言。

反爬对抗

内置 stealth.py 反检测模块（零第三方依赖），自动注入 10 个维度伪装： navigator.webdriver、plugins（真实 PluginArray）、userAgentData、languages/platform/硬件参数、window.chrome（含 iframe）、canvas 噪声、WebGL 参数、permissions、Client Hints 头（UA + Sec-CH-UA 一致性）、locale/timezone。

• ✅ bot.sannysoft.com 专业 WebDriver 检测站：零失败项
• ⚠️ 能力边界：百度等顶级风控为服务端模型判定，对自动化环境会降级隐藏交互元素（实测多层对抗后仍被识别）。对策：自家/中小站点直接可用；强风控大站用有头模式 + 持久化 profile 养号，或连真实用户浏览器会话
• 📌 合规：仅用于自己/授权项目的自动化测试

文件结构

browser-test-mcp/
├── server.py          # MCP stdio 入口
├── fusion_server.py   # 融合层：官方 AI 层工具 + 精确层工具合并
├── pw_bridge.py       # Playwright 精确层（43 工具 + 浏览器生命周期）
├── stealth.py         # 自研反检测模块
├── requirements.txt
├── skill/SKILL.md     # Reasonix skill 手册
├── test_smoke.py      # stdio 冒烟测试（59 工具 + 共享会话断言，CI 使用）
└── test_fusion.py     # 两层交叉操作测试

上游

• microsoft/playwright（Apache-2.0）
• browser-use/browser-use（MIT）
• microsoft/playwright-python（Apache-2.0）

本项目为两者功能的融合封装（组合 + 运行时注入，不改上游源码），License: MIT