Midscene.js实战：如何用AI视觉四步跑通跨平台UI自动化测试

Midscene.js实战：如何用AI视觉四步跑通跨平台UI自动化测试

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

Midscene.js 是一个基于 AI 视觉的跨平台 UI 自动化框架：用自然语言描述每一步操作，它通过截图识别来定位元素并执行动作，同一套 API 覆盖 Web、Android、iOS 和桌面。全文以"电商搜索流程回归测试"为例，按 连接模型 → 写第一条自然语言测试脚本 → 运行并看报告 → 真机复用 四步展开，全程不需要写选择器。

🔍 为什么选择器方案走不远

传统 UI 自动化依赖页面结构：先解析 DOM，再用 CSS 选择器或 XPath 找到目标。同一个"登录"按钮，两种方案的差别是这样的——

• 选择器方案：button.login-btn。前端把类名改成btn-login或重构成 div，脚本立刻失效；
• 视觉方案：点击页面右上角的"登录"按钮。只要按钮还长那样、还在那个位置，指令就不用改。

结构依赖带来三个具体问题。其一是维护成本，每次 UI 重构都要追着选择器修；其二是覆盖盲区，只有图标的按钮、自定义控件、<canvas>绘制的游戏和图表界面没有语义标记，结构解析根本"看不见"；其三是无法验证外观，DOM 查询只能证明节点存在，证明不了颜色、高亮状态、布局是否符合预期。Midscene.js 把参照物从代码结构换成截图：元素定位只基于截图像素，人眼能看到的界面它都能操作，也因此能直接断言"用户实际看到的"界面状态。代价是它依赖具备 UI 定位能力的视觉模型，模型怎么选、怎么配，是后面第一件事。

⏱️ 五分钟安装与首次配置

Web 端的核心包是@midscene/web。安装依赖并配置模型环境变量（以 Qwen 系列为例，Doubao、GLM、Gemini 等均可按模型配置接入）：

npm install @midscene/web playwright tsx export MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" export MIDSCENE_MODEL_API_KEY="your-api-key" export MIDSCENE_MODEL_NAME="qwen3.7-plus" export MIDSCENE_MODEL_FAMILY="qwen3"

不想写代码可以先走最快的路：在 Chrome 商店安装 Midscene 扩展，打开任意网页，在右侧边栏输入自然语言指令（aiAct做操作、aiQuery提取数据、aiAssert校验界面）即可试跑。指令验证通过后，可以原样翻译成 Agent API 调用进入正式脚本。

第一条自然语言测试脚本：回归电商搜索流程

下面这个脚本在 eBay 搜索耳机，覆盖最常用的四个 API：aiAct执行操作、aiWaitFor等待条件成立、aiQuery提取结构化数据、aiAssert断言界面状态。

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://www.ebay.com'); await page.waitForLoadState('networkidle'); const agent = new PlaywrightAgent(page); await agent.aiAct('type "Headphones" in search box, hit Enter'); await agent.aiWaitFor('there is at least one headphone item on page'); const items = await agent.aiQuery('{itemTitle: string, price: number}[], find items and their prices'); console.log(items); await agent.aiAssert('There is a category filter on the left'); await browser.close();

运行与查看报告：

npx tsx demo.ts

成功后终端会打印报告文件路径（midscene_run/下的一个 HTML 文件），用浏览器打开即可看到每一步的截图、模型推理过程和耗时。脚本失败时，第一步永远是先打开报告，看模型在哪一步"看到"了什么。

📱 Web与真机如何用同一套API

平台适配拆成独立的 npm 包，但 API 面与 Web 端一致：

另支持 HarmonyOS。也就是说，Web 上验证过的"搜索 → 等待结果 → 提取价格"指令，换到真机上几乎不用改写。以 Android 为例：开启 USB 调试、adb devices能看到设备后，安装@midscene/android、创建 Agent，调用的还是aiAct、aiQuery这些方法；Android 模块源码里可以看到完整的 adb 与 scrcpy 交互链路，视觉引擎源码则实现了跨平台共享的截图定位与任务规划。

🛠️ 两个提升执行稳定性与效率的实用能力

计划缓存：少调一次模型

同样的指令在相似的页面环境下重复执行时，Midscene.js 可以把 AI 规划结果（Web 端还包含元素定位信息）缓存到./midscene_run/cache，下次优先复用。官方文档给出的实测案例中，执行时间从 51 秒降到 28 秒。缓存的计划在运行期失效（比如弹窗不再出现）会自动回退到重新规划；注意两点：默认关闭缓存，需显式指定 id 才生效；aiQuery这类查询结果从不缓存。

const agent = new PlaywrightAgent(page, { cache: { id: 'ebay-search' }, });

多模型组合与报告回看

Default 模型之外，可以为复杂多步任务追加 Planning 模型增强规划，或追加 Insight 模型增强数据提取与断言，脚本本身不用改。另外，纯视觉方案的 token 消耗只取决于屏幕分辨率和任务复杂度，不随页面 DOM 节点数量增长——同一份脚本跑在结构臃肿的大页面上，成本不会跟着膨胀。

⚠️ 使用前的注意事项

1. 不是任何大模型都能用。纯视觉定位要求模型具备稳定的 UI 定位能力，README 列出的适配模型包括 Qwen3.x、UI-TARS、Doubao-Seed、GLM-4.6V、Gemini 等；换成普通文本 LLM 会直接不可用。
2. Web 端建议用 Chromium 系浏览器。浏览器级事件、触摸手势等能力依赖 Chrome DevTools Protocol，Firefox 和 WebKit 能跑基础操作，但 CDP 相关功能可能报错。
3. Playwright 浏览器要单独安装。npm install不会下载浏览器二进制，需先执行npx playwright install，网络受限时可配置镜像加速。
4. 留意默认的网络等待。导航和操作之后 Midscene 会自动等待网络空闲，默认超时分别是 5000ms 和 2000ms；在慢网络或受限的 CI 环境里，可以通过waitForNavigationTimeout、waitForNetworkIdleTimeout调整或放宽。
5. 依赖缓存前想清楚场景。缓存默认关闭，查询结果也从不缓存；需要验证实时数据（价格、库存）的断言，不要指望缓存命中。

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