企业官网建设流程全解析

如何用一份 YAML 批量跑多台 Android 与 iOS 设备：Midscene.js 多设备自动化完整指南

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

Midscene.js 是一个 AI 驱动的 GUI 自动化测试框架（GUI Agent，即"会看屏幕的软件操作智能体"）。它不依赖你写死按钮的位置，而是像人一样截屏、理解界面，然后决定点哪里、输什么。这篇文章带你用一套 YAML 脚本同时驱动多台 Android 和 iOS 设备，批量执行 UI 测试，并拿到一份看得懂的结果汇总。

先弄清它靠什么干活：看屏幕，而不是找按钮

传统自动化脚本依赖"选择器"——一段描述按钮在页面结构中位置的代码。页面一改版，选择器就可能失效，脚本随之报错。Midscene.js 换了一条路：每一步都把当前屏幕截图交给多模态 AI 模型，用自然语言告诉它要做什么，模型负责判断"搜索框在哪""结果页长什么样"。

这样你能拿到几样东西：

• 一套 API 覆盖 Web、Android、iOS、HarmonyOS 和桌面应用。控制一台手机和控制一个网页用的是同一组方法，写过的流程换个平台基本能复用。
• 用大白话写断言。aiAssert('结果列表中每一条价格都低于 100 元')这样的校验，连"蓝色边框、对勾高亮"这类纯视觉效果都能检查，不需要读 DOM。
• 不需要给界面加任何标注。只有图标的按钮、画布 canvas 渲染的内容、跨域 iframe 里的元素，都能靠视觉定位。

官方在 AndroidWorld、AppControlBench 等基准上公开了成绩（如 AndroidWorld 93.1% Pass@1），并且一次 60 任务的评测总模型成本只有 0.59 美元——截图驱动意味着不需要把巨大的 DOM 树塞给模型，费用可控。

十分钟上手：装好 CLI，配好模型

多设备批量执行的入口是官方命令行工具@midscene/cli，它负责解析你的 YAML 脚本、调度执行、生成报告。

先确认终端里的 Node.js 是 20.19+、22.12+ 或 24+，然后全局安装：

npm i -g @midscene/cli

接下来在项目运行目录下创建一个.env文件，填入你要用的多模态模型（Qwen、Doubao、GLM、Gemini、UI-TARS 等都支持，也有可自建的开源模型）：

MIDSCENE_MODEL_BASE_URL="https://你的模型服务地址/v1" MIDSCENE_MODEL_API_KEY="你的 API Key" MIDSCENE_MODEL_NAME="模型名称" MIDSCENE_MODEL_FAMILY="模型系列"

两个容易踩的点：.env放在跑命令的目录下，而不是 YAML 文件旁边；文件里不要加export前缀。完整字段说明可以看 模型配置文档。

配到这一步，你的"驾驶员"就坐进车里了——接下来给它写任务书。

给每台设备写一份 YAML：Android 和 iOS 各一份

Midscene 的脚本就是 YAML 文件（一种键值结构的配置格式，比 JSON 更省空格）。一个文件对应一台设备、一个执行目标，tasks下面的每一行ai就是一条自然语言指令。

Android 设备（deviceId可以通过adb devices命令查到）：

android: deviceId: s4ey59 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 "杭州西湖"，然后点击搜索按钮 - ai: 点击第一个搜索结果，进入详情页 - aiAssert: 路线规划页面已显示

iOS 设备（需要先配好 WebDriverAgent，一个负责驱动 iOS 设备的开源测试代理）：

ios: wdaPort: 8100 tasks: - name: 修改系统设置 flow: - ai: 打开设置应用 - ai: 点击 "显示与亮度" - ai: 开启 "深色模式" - aiAssert: 深色模式已开启

指令里能直接写中文，aiAssert负责验证"屏幕上确实出现了预期结果"，这一步失败整个脚本会判定不通过。两个平台的完整接入细节（设备连接、前置条件）分别见 Android 平台指南 和 iOS 平台指南。

一条命令跑多台设备：并发、重试、失败继续

把上面这些脚本放进同一个目录，用通配符一次性交给 CLI，就进入了批量模式：

midscene './scripts/devices/*.yaml'

批量执行器（实现在 packages/cli/src/batch-runner.ts）默认按顺序逐个跑（并发数为 1）。如果你想让 3 台设备同时开工、某台失败后其余继续、失败脚本自动补跑一次，可以这样配置：

new BatchRunner({ files: ['./scripts/devices/*.yaml'], concurrent: 3, // 同时执行 3 个脚本 continueOnError: true, // 单台失败不拖垮整批 retry: 1, // 失败的文件额外重试 1 次 summary: 'output/summary.json', })

并发数不用追求拉满：它受你的模型 API 限流和设备性能约束，从 2～4 开始调，观察模型报 429 错误的频率再决定加不加。全部跑完后，执行摘要（packages/cli/src/execution-summary.ts）会把每个脚本的状态归为成功、部分失败、失败或未执行四类，打印在终端，也写进 summary JSON。

跑完看什么：HTML 报告加 JSON 汇总

批量执行结束后，输出目录里会有三层结果：

1. 汇总文件（默认index.json）——所有脚本的状态和统计，适合交给 CI 判断整批通过与否；
2. 每个脚本的独立 JSON 结果——单条用例的详细执行数据；
3. 每个脚本的交互式 HTML 报告——截图序列、元素定位框、AI 每一步的决策过程、断言结果都点得开。

调试多设备问题时建议从 HTML 报告入手：失败那台设备的报告里能直接看到失败前一刻的屏幕和 AI 的判断，比翻日志快得多。报告本身也可以独立消费，做法见 consume-report-file 文档。

几个让批量更稳的小技巧

• 用${变量}注入动态值：脚本执行前会用.env里的值替换${topic}这类占位符，同一份脚本模板可以复用给不同设备、不同数据。
• .env的位置决定成败：它只从命令运行目录加载，CI 里记得先cd到正确位置。
• shareBrowserContext只服务于 Web 目标：多个网页脚本共享一个浏览器上下文（省登录、省资源），但批量里混入 Android/iOS 脚本时不能开它，CLI 会直接报错拦下。
• 有头模式只适用于 Web：--headed可以开浏览器窗口肉眼旁观执行过程，手机目标没有这个开关，想看过程就用报告里的截图回放。

现在就动手

下一步：克隆 https://link.gitcode.com/i/6f672561269061bae375a6b805e937f8，在packages/cli/tests/下找现成的multi_yaml_android_scripts、multi_yaml_ios_scripts示例对照着写自己的第一份设备脚本，配好.env后跑midscene ./your-script.yaml，打开生成的 HTML 报告确认 AI 的每一步决策——这就是你多设备测试流水线的最小闭环。更多脚本语法见 YAML 脚本运行器文档。

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