Midscene.js 实战指南：3 步跑通视觉 AI 端到端测试-育师

Midscene.js 实战指南：3 步跑通视觉 AI 端到端测试

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

Midscene 是一个面向 E2E 测试的 GUI Agent，简单说就是"会看屏幕、会动手点"的 AI。你用自然语言描述任务，它自己找按钮、填输入框、验证结果，不用写任何选择器。读完本文，你能在自己的电脑上跑通第一条视觉自动化用例，并知道怎么扩展到 Android 和桌面场景。

场景切入 —— 它帮你解决什么

选择器总失效：页面改一次样式，你的cssSelector就崩一次。测试同事用 Midscene 描述"点击价格低于 100 美元的第一件商品"，页面怎么改都不怕。
图标按钮和画布元素没法测：纯图标按钮、<canvas>绘制的内容、跨域 iframe，传统工具根本定位不到，Midscene 靠截图认元素，看得到就能点。
一套用例想覆盖多个平台：同一套 Agent API 能跑 Web、Android、iOS 和桌面，换平台只换设备连接方式，流程描述不用重写。

最小组合 —— 从零到跑通

先做两个前置检查：Node 版本要在 20 以上，手机要能被 adb 识别。

node -v adb devices -l

✅ 第二行命令能看到一行设备序列号，说明设备链路通了。

然后配置 AI 模型，Midscene 需要一个能"看懂 UI"的多模态模型，四个环境变量搞定：

export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" export MIDSCENE_MODEL_API_KEY="your-api-key" export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628" export MIDSCENE_MODEL_FAMILY="doubao-seed"

最后一条命令启动 Android Playground（一个零代码的交互面板）：

npx --yes @midscene/android-playground

✅ 窗口里手机画面出现、你输入"打开设置页"后手机真的执行了，说明全链路成功。Playground 里的每条指令都对应一个 Agent API，验证完直接搬进脚本就行。

核心能力拆解

用自然语言写测试用例

核心就是三个 API：aiAct执行多步流程，aiAssert验证界面结果，aiQuery提取结构化数据。一个最小用例长这样：

const agent = new AndroidAgent(); await agent.aiAct('打开懂车帝，搜索 SU7，进入参数配置页'); await agent.aiAssert('页面显示了电池容量和电机参数');

⚠️ 避坑：aiAct是自主规划，每步都调用模型，又慢又费 token；能拆成单步的（比如aiTap、aiInput）就别让 AI 自由发挥。

配置 AI 模型参数

模型支持 Qwen、Doubao、GLM、Gemini 等自托管或 API 选项，全部通过环境变量注入，也可以在 Playground 窗口的齿轮按钮里直接粘贴配置。

⚠️ 避坑：MIDSCENE_MODEL_FAMILY别漏填，它告诉 Midscene 该用哪套提示词策略适配你的模型，填错了定位准确率会明显下降。

连接 Android 设备

Midscene 通过 adb 控制真机或模拟器，手机侧只需要开一个开关：开发者选项里的USB 调试。连上数据线后：

adb devices -l

✅ 输出里出现device状态的行就通了。

⚠️ 避坑：模拟器同样算设备，但没有 USB 调试开关时先确认模拟器控制台已启用 ADB over WiFi，否则adb devices永远是空的。

进阶玩法与调优

如果你想控制"正在自己用"的桌面 Chrome（复用 cookies 和登录态，不用维护一堆测试账号），可以启用桥接模式：安装 Midscene 插件后，本地脚本这样连上去：

import { AgentOverChromeBridge } from '@midscene/web/bridge-mode'; const agent = new AgentOverChromeBridge(); await agent.connectNewTabWithUrl('https://www.bing.com'); await agent.ai('搜索 AI 101 并回车'); await agent.aiAssert('搜索结果显示在页面中'); await agent.destroy();

插件会弹窗询问是否允许连接，点 Allow 即可；脚本侧记得模型环境变量配在终端里，而不是浏览器里。

如果你想压低成本或提高复杂任务稳定性，可以按场景拆模型：简单页面用便宜的视觉模型，复杂流程开启deepThink加强规划，小元素定位开启deepLocate。

踩坑速查

症状：用 Ollama 本地模型报 403 →原因：Ollama 默认拒绝来自浏览器扩展的跨域请求 →解决：export OLLAMA_ORIGINS="*"后重启 Ollama

症状：adb devices看不到手机 →原因：USB 调试没开，或数据线只供电不传数据 →解决：开开发者选项的 USB 调试，换数据线后执行adb kill-server && adb start-server

症状：Web 侧报Cannot access a chrome-extension:// URL of different extension→原因：其他浏览器插件向页面注入了 iframe 或脚本，与 Midscene 冲突 →解决：打开chrome://extensions/逐个禁用可疑插件，刷新重试

症状：小图标、和周围元素长得很像的按钮定位不准 →原因：单次定位在密集元素间选错了 →解决：调用时加{ deepLocate: true }，多花一次模型调用换准确率