Midscene.js 实践指南：让 AI 驱动的跨平台 UI 自动化跑起来

Midscene.js 实践指南：让 AI 驱动的跨平台 UI 自动化跑起来

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

Midscene.js 是面向 E2E 测试的 AI 驱动跨平台自动化框架。它不依赖页面结构，靠截图加多模态模型定位元素，你用自然语言描述操作即可，Web、Android、iOS、HarmonyOS 和桌面端都能覆盖。

🎯 它能替你干什么

只要任务能用一句自然语言讲清楚，就可以交给 Midscene 去执行。

你常交给它做的，是下面这几件事。

跑通一条回归流程。登录、搜索、加购、下单，过去要一步步写选择器，现在直接写"打开站点并完成注册第一步"，模型自己规划点击路径。

跨平台复用同一套流程。同一个购物流程，需要在 Web、Android、iOS 上分别验证。你只换设备配置，流程描述可以原样保留。

验证用户真正看到的东西。不只判断"DOM 节点存在不存在"，还能断言"价格是否高亮、布局是否正常"，这些检查直接基于截图完成。

🚀 第一次跑起来

最小路径只有三步：准备模型配置、选一个起点、看报告判断成败。

第一步：准备模型配置。Midscene 需要一个有 UI 定位能力的多模态模型，Qwen、豆包、GLM、Gemini、UI-TARS 都可以。导出下面四个变量即可：

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"

第二步：选一个起点。想立刻体验，安装 Chrome 扩展就行，不用写任何项目代码。想从源码运行，先执行git clone https://gitcode.com/GitHub_Trending/mid/midscene，再依次运行pnpm install和pnpm build。

第三步：判断成功。首条指令跑完后，midscene_run/目录会生成报告文件。用浏览器打开，能看到分步时间线和截图，说明模型真的点到了正确的按钮。

🧩 三种典型用法

按复杂度分三种用法：浏览器里说人话、YAML 脚本、接入代码工程。

用法一：浏览器里直接下指令。打开 Midscene 扩展的侧边栏，输入"点击登录按钮"。它等价于调用aiAct，模型自己规划并执行。也可以让它提取数据（aiQuery）或检查界面（aiAssert）。

用法二：YAML 脚本。把流程写进一个.yaml文件，用命令行运行，不需要搭测试框架：

page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 "今日天气" - sleep: 3000 - name: 检查结果 flow: - aiAssert: 结果中展示了天气信息

用法三：接进自己的测试工程。如果你已经用 Playwright 或 Puppeteer，给脚本挂一个 Agent，测试代码里这样调用：

await agent.aiAct('搜索耳机，并把第一件加入购物车'); const items = await agent.aiQuery< Array<{ name: string; price: number }> >('购物车中的商品，{name: string, price: number}[]'); await agent.aiAssert('购物车中有一件商品，并且页面显示了小计金额');

📱 一个完整案例

以 Android 上的一条真实回归流程为例，四步能跑完并产出报告。

背景。某车类 App 每周发版，每次都要人工验证"启动应用 → 搜索车型 → 查看参数页"。

目标。把这条流程变成一条命令：回归通过就放行，出问题立刻报红，并附上报告给发版会议。

步骤。

1. 用 adb 连接设备，确认模型环境变量已导出
2. 写一份 Android 的 YAML，把流程描述写成自然语言句子
3. 在 agent 配置里开启缓存，并指定固定的缓存 ID
4. 命令行运行 YAML，让它生成报告

结果。报告里能看到每一步的截图和耗时，第二次执行命中缓存，整条流程明显变快。

可优化点。"参数"标签是个小按钮，容易点偏，可单独开启deepLocate精确定位；CI 环境建议改用只读缓存策略，避免并发写缓存互相覆盖。

⚡ 把成本与速度调优起来

核心思路只有一条：重复的交给缓存，精确的用即时 API。

问题：同一流程反复跑，每次都重新做 AI 规划，费用和耗时一起涨。手段：开启缓存。AI 规划结果以指令为键存下来，Web 场景还会缓存元素 XPath 定位。 收益：官方示例里同一条流程从 51 秒降到 28 秒；缓存失效时自动回退给模型重新规划，不会卡死。

问题：点一下、填一次这类单步操作，却走了多步规划。手段：固定单步操作用aiTap、aiInput这类即时交互 API，把aiAct留给路径不确定的多步任务。 收益：一次调用完成一个动作，token 和时间都省下来。

问题：小元素、易混淆元素定位不准。手段：在单次调用上开deepLocate（更精准定位）或deepThink（更强的任务拆解）。 收益：定位准确率提升，代价是每次多一轮模型调用，按需使用。

缓存文件落在midscene_run/cache目录，扩展名.cache.yaml，可以直接查看和管理。

🩹 高频问题速查

最常遇到三个问题，每个按三行讲清楚。

设备连接超时

• 现象：adb devices看不到设备，或设备状态显示 offline
• 原因：USB 调试没开，或设备上的授权弹窗没点确认
• 解决：开发者选项里开启 USB 调试，在设备上确认授权后重试

本地 Ollama 模型报 403

• 现象：扩展或脚本调用模型失败，返回 403
• 原因：Ollama 默认禁止来自扩展的跨域访问
• 解决：设置环境变量OLLAMA_ORIGINS="*"后重启 Ollama

扩展提示 Cannot access a chrome-extension:// URL

• 现象：扩展里第一次运行就报错，信息含 chrome-extension
• 原因：其他扩展往页面注入了 iframe 或脚本，产生冲突
• 解决：开发者工具里按扩展 ID 找到注入来源，禁用后刷新页面

🧭 继续深入

想改而不只是用，按这个顺序读源码。

• 核心引擎：Agent 主循环、任务调度与报告生成
• AI 模型管理：模型配置与调用策略
• YAML 执行：脚本如何变成任务
• Web 集成：Playwright、Puppeteer 适配与 CDP 桥接
• Android 支持、iOS 支持、桌面端支持：设备接入与输入驱动
• 报告应用、Chrome 扩展、交互式 Playground

学习建议：先读基本概念，理解 aiAct、aiQuery、aiAssert 三类 API 的分工；再读缓存文档；最后试Playwright 集成。

Midscene.js 的思路不复杂：用截图代替选择器，用自然语言目标代替逐步脚本。对测试套件的维护成本来说，值得一试。挑一条你最常回归的流程，把选择器改写成一句自然语言，先在 Chrome 扩展里把它跑通。

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