Midscene.js 十五分钟上手：用自然语言写跨平台 UI 测试-育师

Midscene.js 十五分钟上手：用自然语言写跨平台 UI 测试

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

接手一个频繁改版的项目那周，选择器失效了一半，用例跟着批量变红。Midscene.js 是一种 AI 视觉自动化思路：它不维护选择器，而是把界面截图交给视觉语言模型识别，用自然语言驱动 Web、Android、iOS 等多端的 UI 操作。

🧭 项目定位：用一套视觉模型驱动多端界面

Midscene.js 是一个面向 E2E 测试的 GUI Agent，相当于浏览器和设备之上的“视觉操作层”：把当前截图交给视觉语言模型，由模型识别元素、规划动作，再把操作写回对应端。

覆盖端：Web（Chrome 扩展、Playwright / Puppeteer）、Android、iOS、HarmonyOS 与桌面（Windows / macOS / Linux）
同一套 Agent API 与 YAML 脚本结构通用于所有端
接法与差异细节见 quick-start.mdx

🔍 能力拆解

看屏幕找元素

传统做法对着 DOM 写选择器，页面一改版就失效，canvas 和原生控件基本无能为力。Midscene.js 的做法是把截图发给模型，让模型说出“右下角蓝色提交按钮”在哪里，再按坐标执行点击与输入：

await agent.aiTap('右下角的蓝色提交按钮'); await agent.aiAssert('页面应出现“操作成功”提示');

用自然语言写操作

脚本就是 YAML 文件，flow里每一步是一句自然语言，不用查 API 就能读懂要做什么。

page: url: https://www.bing.com tasks: - name: Search for weather flow: - ai: Search for "today's weather" - aiAssert: Results show weather information

字段全集（agent配置、各端 target 声明等）在 automate-with-scripts-in-yaml.mdx 有完整说明。

一套脚本多端跑

脚本顶部的目标声明决定跑在哪一端：page指 Web 页面，android通过 adb 连真机，ios通过 WebDriverAgent 连设备，flow部分保持同构。需要复用已登录的桌面浏览器时，开桥接模式，让本地脚本远程控制本机 Chrome，cookie 与登录态直接复用：

page: url: https://www.bing.com + bridgeMode: newTabWithUrl

⚙️ 上手：从安装到跑通第一个脚本

安装 CLI 与配置模型

终端里的 Node.js 需要 20.19+。装好 CLI 后，在运行目录建.env，填入模型服务的四项配置：

npm i -g @midscene/cli

MIDSCENE_MODEL_BASE_URL="https://your-model-endpoint/v1" MIDSCENE_MODEL_API_KEY="your-api-key" MIDSCENE_MODEL_NAME="your-model-name" MIDSCENE_MODEL_FAMILY="your-model-family"

可选模型清单与各家示例见 model-common-config.mdx。

第一个 YAML 脚本

把上文“用自然语言写操作”一节的search.yaml保存到项目里即可。文件只有三部分：顶部 target 声明要操作的端、tasks声明用例、flow列出步骤，sleep、runAdbShell等工具步骤可按需插入。

CLI 运行与查看报告

midscene ./search.yaml # 单脚本 midscene './scripts/*.yaml' # glob 批量

执行过程实时打印进度，结束后在midscene_run/report/下生成 HTML 报告，逐步截图、模型定位框和可回放动画都在里面，失败时直接看哪一步的定位偏了。

跑不顺时先调这两项

超时与重试：命令行加--retry 2，失败脚本会重跑；批量执行配--continue-on-error，一个用例挂了不拖累整批。
模型选择：元素识别质量由模型的视觉能力直接决定。定位频繁偏差时，换更新、参数更大的视觉模型，并核对MIDSCENE_MODEL_FAMILY是否配错。

🧪 两个代表性用例

页面搜索测试（Web）

典型的冒烟路径：打开搜索页、输入关键词、断言结果出现。弹窗等干扰交给aiActContext兜底：

page: url: https://www.bing.com agent: aiActContext: 如果出现弹窗，先关闭 tasks: - name: 搜索关键词 flow: - ai: 在搜索框输入“无线耳机”，点击搜索 - sleep: 3000 - aiAssert: 结果页展示带价格的商品结果

移动端登录回归（Android）

adb 连上真机后，flow里不出现任何资源 ID，改版只影响文案时脚本往往不用动：

android: deviceId: s4ey59 # adb devices 查看 tasks: - name: 登录回归 flow: - ai: 打开 App，进入登录页 - ai: 在账号输入框填入测试账号 - ai: 输入密码，点击登录按钮 - aiAssert: 登录后可见首页主界面

电商价格监控、多端内容发布之类的场景，同样只改顶部 target 声明。更多可直接运行的样例在 packages/cli/tests/midscene_scripts/。

❓ 常见问题

需要自己部署模型吗

不必须。Midscene.js 把截图发给多模态模型服务做识别与规划，配好MIDSCENE_MODEL_*四项环境变量即可开工；想走本地服务时，任何 OpenAI 兼容接口（包括 Ollama 部署的视觉模型）都可以接。

点击位置偶尔会偏吗

会，定位精度取决于模型的视觉理解能力。常用手段有三个：换更强的视觉模型；描述元素时写外观特征加位置（“右上角的人像头像图标”而不是“个人中心”）；对小而模糊的目标开启deepLocate做二次精定位。

运行产物放在哪

报告、日志、缓存在midscene_run/下，HTML 报告在report/子目录。不想让它落在项目根目录，用环境变量MIDSCENE_RUN_DIR指到别处即可。

🗂️ 文档与示例入口

入门与 YAML 脚本：quick-start.mdx、yaml-script-runner.mdx
可运行脚本样例：packages/cli/tests/midscene_scripts/
社区与生态整理：awesome-midscene.md

工具选型看场景，但对改版频繁的页面，把选择器换成截图和自然语言，回归脚本的维护成本会直观下降。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Midscene.js 十五分钟上手：用自然语言写跨平台 UI 测试