5 分钟读懂 Midscene：用 AI 视觉自动化测试打通 Web 与移动端的完整指南

5 分钟读懂 Midscene：用 AI 视觉自动化测试打通 Web 与移动端的完整指南

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

周五傍晚，一个只在安卓端复现的 UI 回归问题堵住了发版：网页脚本运行正常，换到真机上选择器就失效，canvas 里的内容更是无从断言。Midscene 是一个 AI 视觉自动化测试框架：它像人一样看屏幕、定位元素、执行操作并校验可见结果，同一套 Agent API 覆盖 Web、Android、iOS、HarmonyOS 与桌面端，适合刚接触跨端 E2E 的开发者与测试工程师。

看清 Midscene 能覆盖哪些场景 🧭

在浏览器里跑一条自然语言回归用例

先拿到源码，后文实操都基于本地仓库：

git clone https://gitcode.com/GitHub_Trending/mid/midscene pnpm install

从 Chrome 商店安装 Midscene 扩展后，打开任意待测页面，浏览器右侧会出现 Midscene 侧边栏。先在设置页粘贴一份模型配置——任何具备 UI 定位能力的多模态模型（Qwen、Doubao、Gemini、UI-TARS 等）都可以。然后在侧边栏选择 Action，输入"点击登录按钮"：页面会自动完成操作，侧边栏同步展示规划过程。切到 Query 可以提取结构化数据（例如"页面中的商品 {name, price}"），切到 Assert 可以校验界面状态（例如"页面顶部显示导航栏"）。

Playground 里验证过的指令与代码 API 一一对应：aiAct、aiQuery、aiAssert。每次运行还会生成一份 HTML 报告，逐步骤记录截图、动作与断言结果，失败时直接定位到出问题的那一帧。

把 Android 真机接进同一个 Playground

开启 USB 调试、装好 adb 之后，按 Android 平台指南 启动 Android Playground。浏览器打开本地面板：左侧是规划步骤列表，右侧是实时设备屏幕。输入一句"Open the settings to check the current android version number"，能看到 Planning → Locate（找到 Settings 图标）→ Tap 逐步推进，手机真实地完成点击，最后把版本号读回左侧面板。

iOS 需要额外准备 WebDriverAgent 环境，HarmonyOS 依赖 hdc 工具链，但三者共用同一套 Agent API，用例文本基本可以原样迁移，不用为每个端重写一遍。

用桥接模式让本地脚本接管日常 Chrome

常规 Playwright/Puppeteer 方案启动的是无头或全新浏览器，登录态和插件全部丢失。桥接模式（Bridge Mode）反过来：让本地 Node 脚本直接接管桌面版 Chrome 里正在使用的标签页，复用 cookies、登录态与页面状态。

开启方式：扩展里打开 Bridge Mode 面板，状态变为 "Listening for connection"。注意模型配置写在 Node 侧的终端环境变量里，而不是浏览器侧。然后写一个很短的脚本：

const agent = new AgentOverChromeBridge(); await agent.connectCurrentTab(); await agent.aiAct(`在搜索框输入 "Midscene.js" 并点击搜索`);

运行后扩展弹出确认窗口，点 Allow（或 Always Allow），当前标签页即被脚本接管。这种方式也被称作 man-in-the-loop：人可以继续操作同一个浏览器，脚本只在需要时介入，适合依赖真实登录态的回归场景。

拆开看视觉定位：为什么不需要选择器 🔍

Midscene 把"看屏幕、对所见做操作、校验可见结果"建模成唯一的执行循环：输入是截图加自然语言指令，模型负责理解界面、决定坐标、执行动作，再截屏复核。这个选择带来两个实际好处。第一，选择器不再是瓶颈——纯图标按钮、canvas 绘制内容、跨域 iframe、原生 App 界面在 DOM 里都难以触达，视觉定位统一处理。第二，跨平台接口真正统一：同一条 aiAct 在 Web、移动端、桌面端语义一致，跨端用例可以复用而不是重写。代价方面：不再向模型发送完整 DOM 树，token 开销主要来自截图，官方 AppControlBench 报告中 60 个任务的模型总成本约 0.59 美元；但每一步都要走一次推理，多步任务下模型选择与缓存就成了成本与稳定性的主要调节旋钮。

调优建议与已知边界

• 模型策略：起步用单一多模态模型即可；调用量大后可拆成"规划模型 + 视觉定位模型"组合，开源模型支持自托管。
• 缓存：默认关闭；开启后规划步骤与 Web 元素 XPath 会缓存到./midscene_run/cache，官方示例执行耗时约下降 45%。查询与断言类操作永不缓存，UI 变动时缓存自动回退重新规划，因此适合"指令稳定、页面相对稳定"的回归场景。
• 平台环境：Android 依赖 adb、iOS 依赖 WebDriverAgent、HarmonyOS 依赖 hdc，首次接入有环境准备成本，建议按平台指南逐个打通再扩展。
• 桥接模式：脚本需要上传本地文件时，要在扩展里开启 file URL 访问权限；模型配置只认 Node 侧环境变量。
• 长任务边界：步骤多、UI 频繁变化的流程，单步推理开销与偶发失效会被放大，建议先在 Playground 验证指令再进 CI，并配合报告时间轴定位失败步骤。

继续深入

• 中文文档目录：平台接入、模型配置与完整 API 参考，环境搭建的第一站
• 核心 Agent 实现：想了解截图循环与任务规划如何落地，从这里读起
• AI 模型集成层：视觉模型调用与定位决策的具体实现，适合要更换或自托管模型的开发者

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