Midscene.js 完整指南：用自然语言驱动视觉化的跨平台 UI 自动化测试-育师

Midscene.js 完整指南：用自然语言驱动视觉化的跨平台 UI 自动化测试

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

上周一次前端重构上线后，你们的 UI 测试挂了 40 多条用例——不是因为功能坏了，而是选择器全失效了。如果改用 Midscene.js 这类视觉驱动的 UI 自动化测试框架，界面怎么改都不影响：它只看屏幕截图、用自然语言下指令，Web、Android、iOS 到桌面端共用一套 API。这篇文章带你从环境配置跑通第一条指令，再到组织一条完整的验收任务线，把最实用的能力和避坑经验一次讲清。

一分钟看懂：Midscene.js 是什么

先给结论：Midscene.js 是一个「GUI Agent for E2E Testing」，把「点哪里、填什么、结果对不对」全部交给多模态大模型基于截图判断，你只负责用自然语言描述目标。

视觉定位：元素识别完全基于截图，不依赖 DOM、选择器或无障碍树。图标按钮、Canvas 画布、跨域 iframe、原生 App 这类传统手段够不着的目标，它都能点。
自然语言驱动：aiAct执行操作、aiQuery提取结构化数据、aiAssert断言界面状态，读起来接近人话。
一套 API 跨平台：同一个 Agent 抽象跑在浏览器（Playwright/Puppeteer 集成）、Android（scrcpy 投屏控制）、iOS（WebDriverAgent）、HarmonyOS 和 Windows/macOS/Linux 桌面。
模型可插拔：UI-TARS、Qwen-VL、Gemini、GLM-4.6V、Doubao 等支持 UI 定位的多模态模型都能接，含可自部署的开源模型。
谁适合用：被选择器维护拖累的测试工程师、想给存量 Playwright 用例「上 AI」的开发者、以及需要非技术同学也能写验收脚本的团队。

🧭 三步跑通第一个视觉测试

最短路径是：装 CLI → 配模型 → 跑一个 YAML 脚本。全程不需要写一行测试框架代码。

第一步：配置模型。Midscene 通过 4 个环境变量认模型服务（详细取值见仓库文档 apps/site/docs/zh/model-common-config.mdx）：

export MIDSCENE_MODEL_BASE_URL="https://你的模型服务地址/v1" export MIDSCENE_MODEL_API_KEY="你的 API Key" export MIDSCENE_MODEL_NAME="模型名称" export MIDSCENE_MODEL_FAMILY="模型系列" npm i -g @midscene/cli midscene ./demo.yaml

这段代码做了两件事：告诉 Midscene 用哪个视觉模型，然后用midscene命令执行脚本。注意.env文件必须放在命令运行目录下，且不要加export前缀。

第二步：写最小脚本。下面是完整的可运行示例，结构是「目标环境 + 任务流」：

page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - aiAct: 在搜索框输入"今日天气"并回车 - sleep: 3000 - name: 检查结果 flow: - aiAssert: 结果页展示了天气信息

第三步：看报告。命令跑完会输出进度，并在midscene_run目录生成 HTML 报告、日志和缓存，浏览器打开即可逐步回放截图。想零代码先体验的话，装它的 Chrome 扩展在侧边栏直接输入指令就行，完整步骤见 apps/site/docs/zh/quick-start.mdx；也可以从源码仓库入手阅读：git clone https://gitcode.com/GitHub_Trending/mid/midscene。

核心能力拆解

结论先行：日常 90% 的场景只需要三个 API，其余都是它们的变体。

aiAct：规划式执行，最接近「替人干活」。它接收一个目标，自己观察界面、拆解步骤、循环执行直到完成，中途还能带上断言条件。适合多步操作和路径不确定的流程，比如「把第一件商品加入购物车，确认购物车数量变为 1」。代价是每轮都要调模型，耗时和 token 都更高；复杂任务可以开deepThink: true让规划与定位分两次调用完成，稳定性更高。

aiQuery：把界面变成结构化数据。用 JSON 形状描述你要什么，它返回解析结果。提取电商列表商品、抓取页面字段这类需求一步到位。

aiAssert：断言用户真正看到的东西。传统断言只能确认 DOM 节点存在，它能验证颜色、高亮、布局这类视觉状态——这正是「看截图」路线独有的价值。

即时操作类 API 如aiTap、aiInput、aiWaitFor则各干一件事：定位 + 固定动作，不规划多步，更快更省。拿不准用哪个时记住一条原则：流程描述用aiAct，单点操作用即时 API。

实战：一条完整的电商验收任务线

把前面的能力串起来，走一遍「需求 → 操作 → 结果」的完整流程。

需求：验收「登录 → 浏览商品 → 校验价格」这条核心链路，并且要能沉淀给非开发同学复用。

操作：写成一份 YAML，用aiActContext给 Agent 补充业务背景（如处理 Cookie 弹窗），每个 task 用自然语言描述：

任务一：输入用户名密码并登录，aiWaitFor等商品列表出现；
任务二：aiQuery按{name: string, price: number}[]提取全部商品；
任务三：aiAssert校验指定商品价格与文案一致。

如果是代码集成场景，同样的逻辑用 Playwright 写成这样——启动浏览器、创建 Agent、下自然语言指令：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://saucedemo.com'); const agent = new PlaywrightAgent(page); await agent.aiAct('输入 standard_user 和 secret_sauce，点击登录'); const items = await agent.aiQuery('{name: string, price: number}[]');

结果：一条命令跑完全流程，midscene_run/report里产出可视化报告，每一步的截图、模型规划和操作回放都可在时间线里逐帧查看：

同一套「自然语言任务流」换个环境段就能搬到手机上。Android 侧通过 scrcpy 接管真机或模拟器，YAML 里的目标从page换成android即可复用同样的 flow 写法，运行界面如下：

把成本打下来：缓存与即时操作

视觉测试的开销主要来自模型调用，两个手段能明显压缩它。

开缓存。Agent 支持缓存「AI 规划」和「元素定位」两类结果：相同指令在相似页面上重复执行时直接复用，未命中才回退到模型重算，缓存落在midscene_run/cache目录。配置上给 Agent 传cache: { id: 'your-id' }即可，官方文档有完整策略说明：apps/site/docs/zh/caching.mdx。注意aiQuery、aiAssert这类查询操作永远不走缓存，保证结果实时。

换即时 API。单步动作别用aiAct，直接agent.aiTap('结账按钮')，少一轮规划调用。另外，截图分辨率越高 token 越多，视口别盲目拉满。

🩹 三个高频问题与避坑

现象一：点击位置漂移，有时点错元素。原因通常是模型没读懂图标的语义，或MIDSCENE_MODEL_FAMILY配错导致适配逻辑跑偏。处理：把功能性描述改成视觉描述——aiTap('个人中心')不如aiTap('页面右上角的人形头像图标')稳；同时升级到最新版，并核对模型系列参数。

现象二：模型调用报鉴权或配置错误。原因多数出在环境变量：变量名拼错、.env放错目录（必须在 CLI 运行目录，而非 YAML 所在目录）、或值里带了多余的引号。处理：用--dotenv-debug参数看变量实际加载情况，对照模型配置文档逐项核对四个MIDSCENE_MODEL_*变量。

现象三：Chrome 扩展运行报「Cannot access a chrome-extension:// URL of different extension」。原因是其他扩展先向页面注入了 iframe 或 script，与 Midscene 冲突。处理：在开发者工具里找到以chrome-extension://开头的注入节点，复制扩展 ID，到chrome://extensions/里禁用它再刷新页面。