Midscene.js 上手实录：5 分钟跑通能操作真机的 AI E2E 自动化测试-港品优选

Midscene.js 上手实录：5 分钟跑通能操作真机的 AI E2E 自动化测试

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

版本一上线，手动回归最耗人，而且最卡的往往不是点击本身，而是登录态——很多用例每次都要重新走一遍账号流程，纯属浪费。Midscene.js 是一个由 GUI Agent 驱动的 E2E 测试框架，所谓 GUI Agent，就是能看屏幕、自己做操作的 AI 程序：你用自然语言描述任务，它负责截图分析，再自动点击、输入并验证结果。这篇按"最小闭环 + 按终端分场景"的方式过一遍，配好模型到发出第一条指令，5 分钟以内。

最小闭环：从配模型到看见第一份报告

第 1 步：配模型。设 4 个环境变量，指向一个支持 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"

第 2 步：装扩展。从 Chrome 应用商店安装 Midscene，浏览器右侧随即出现侧边栏。

第 3 步：贴配置。点侧边栏里的设置图标，把上面 4 个值粘进设置页并保存。

第 4 步：发第一条指令。打开任意网页，在侧边栏输入一句自然语言，比如"点击登录按钮"。

第 5 步：看回放报告。执行完自动生成 HTML 报告，每一步的截图、AI 决策和断言结果都能逐步回看。

收尾动作：把同一条指令连续跑两遍，对比两份报告里各步的耗时，顺便确认模型输出是否稳定。

场景扩展：按你要操作的终端来选

执行报告：失败步骤怎么一分钟找到

所有 AI 测试都有同一个诉求：跑挂了得知道挂在哪。报告在 Midscene 里是独立产物：

运行产物默认落在midscene_run目录，报告、日志、缓存各占一个子目录
每个 AI 步骤的输入、输出、耗时、状态单独记录，点开 HTML 就能逐步查看决策过程和元素定位框
想整体迁移产物位置，设MIDSCENE_RUN_DIR环境变量即可

收尾动作：下次失败先看报告里卡住那一步的截图，再看日志，顺序反了。

浏览器网页：先体验，再写代码

扩展本身就是 Web 端的 Playground，和 SDK 共享同一套实现，侧边栏里验证过的指令，写成脚本行为一致。想把它固化进工程，在项目里安装@midscene/web，用aiAct、aiAssert、aiQuery这类 API 调用，指令文本和你在侧边栏输入的完全相同。

收尾动作：挑一条你刚在侧边栏跑通过的指令，用脚本形式复跑，确认结果一致。

Android 真机：让 AI 看见手机屏幕

手机上要跑起来的，看这里：

开发者选项打开 USB 调试，数据线连电脑
终端执行adb devices -l，出现设备序列号说明连接成功
运行npx --yes @midscene/android-playground，弹窗里贴入 API Key
输入"打开浏览器搜索 SU7"，AI 自行规划并执行

跑完打开报告，手机上每次点击、滚动、断言都有截图留痕。收尾动作：把这条指令原样搬进 Android SDK，写进正式测试脚本。

接管本地 Chrome：复用已登录的浏览器

用例卡在登录态上的，看这里。桥接模式让本地脚本直接控制你桌面上已经登录的 Chrome，cookies 和插件状态原样复用：

项目里安装@midscene/web和tsx
代码里new AgentOverChromeBridge()，接着调用connectNewTabWithUrl(url)
扩展弹出确认窗，点 Allow（本次允许）或 Always Allow（以后都允许）
桌面 Chrome 新开标签页自动执行，aiAct、aiAssert等 API 与浏览器内用法一致；期间你还可以在旁边手动补操作

收尾动作：跑通一次后，在 YAML 脚本里加bridgeMode: newTabWithUrl，让同一流程走脚本版再验一遍。

故障排查：报错先对号入座

报错现象	可能原因	处理方式
`Cannot access a chrome-extension:// URL`	其他扩展向页面注入了 iframe/script，与 Midscene 冲突	开发者工具里找到`chrome-extension://`开头的注入项，记下扩展 ID，到`chrome://extensions`禁用它，刷新重试
本地 Ollama 返回 403	Ollama 默认限制了浏览器扩展的来源	设环境变量`OLLAMA_ORIGINS="*"`放开来源限制
Azure 上 GPT-5 点击位置偏移	截图分辨率触发了服务端缩放逻辑	用`screenshotShrinkFactor`把截图预先缩小后再发给模型
配了 cache 却没有缓存文件	cache 没配`id`；只读模式下不会自动落盘	确认`cache`带了`id`；只读模式手动调`agent.flushCache()`
本地命中缓存、CI 全部重算	`midscene_run/cache`没进版本库	把`./midscene_run/cache`目录提交进仓库
`adb devices`只显示 unauthorized	手机端还没确认 USB 调试授权	在手机的授权弹窗里点一次"允许"

改完任何一项，重跑之前失败的流程，用报告确认耗时和步骤状态恢复常态。

参数速查：什么时候该调它

参数	推荐值	什么时候调它
`MIDSCENE_MODEL_NAME`	支持 UI 定位的多模态模型	所有场景必配，行为异常时第一个排查项
`cache`	`{ id: "任务名" }`	调试期用读写模式，重复跑同一条指令加速
`cache.strategy`	`read-only`	生产环境防缓存被意外改写
`MIDSCENE_MODEL_TIMEOUT`	`180000`（默认 180 秒）	模型响应慢、请求被超时打断时上调
`MIDSCENE_MODEL_RETRY_COUNT`	`1`（默认）	网络不稳、偶发请求失败时加到 2-3
`bridgeMode`	`newTabWithUrl`	用 YAML 脚本接管本地 Chrome 时开启
`MIDSCENE_RUN_DIR`	自定义路径	报告、缓存要集中管理或迁移位置时

以上为通用起点，按你的模型和页面复杂度微调即可，改完重跑一次、对比报告里的耗时变化。

企业官网建设流程全解析