一句话操控 Web、安卓与桌面应用：Midscene.js 的完整 UI 自动化指南

一句话操控 Web、安卓与桌面应用：Midscene.js 的完整 UI 自动化指南

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

Midscene.js 是一个基于 AI 视觉理解（GUI Agent）的开源 UI 自动化框架，你用自然语言指令，就能在 Web、Android、iOS、HarmonyOS 和桌面应用上跑 E2E 测试与自动化流程，并自动生成带截图的测试报告。

它"看"屏幕，而不是 DOM

Midscene 与传统工具最本质的区别在于：它靠"看截图"定位元素，而不是靠你写 CSS 选择器或 XPath。就像人从屏幕上找到按钮一样，它根据元素的外观和位置定位，再执行点击、输入、滚动。

这意味着纯图标按钮、自定义控件、<canvas>绘制的内容、跨域 iframe 里的元素，都能直接定位，不需要任何语义化标注。断言同样是视觉方式：用自然语言描述预期外观，就能检查颜色、选中高亮、布局和视觉反馈。

5 分钟跑通第一次自动化：Chrome 扩展体验

你不需要搭项目、写代码，装一个 Chrome 扩展就能在任意网页上发指令。

首先，从 Chrome Web Store 安装 Midscene 扩展，打开扩展列表中的"Midscene"，浏览器右侧会出现操作侧边栏。接着，在设置页粘贴一组具备 UI 定位能力的多模态模型配置并保存。最后，打开任意网页，在侧边栏输入一条自然语言指令运行。常用的三类指令：

运行后，Midscene 会先理解当前页面，再执行动作或返回结果。具体步骤见快速开始文档。

把 Playground 里的指令搬进测试脚本

在扩展里验证过的指令与脚本是同一套能力，可以直接搬进代码。以 Playwright 集成为例，配置好模型、打开页面后：

import { PlaywrightAgent } from '@midscene/web/playwright'; const agent = new PlaywrightAgent(page); await agent.aiAct('搜索耳机，然后将结果筛选为价格低于 100 美元'); await agent.aiWaitFor('筛选后的搜索结果已显示'); await agent.aiAssert('搜索结果中的每件商品价格都低于 100 美元');

另外，除了 SDK，你还可以用 YAML 脚本编写 UI 流程；@midscene/test框架（Beta）进一步把"声明式测试意图"和"可编程工程实现"分开：UI 流程写在 YAML，API 调用、数据准备与清理封装成可复用的 TypeScript 节点。一条退款用例就可以先通过 API 准备订单，再通过 UI 申请退款并验证结果。

Bridge 模式：远程操控你本地的 Chrome

桥接模式让你用终端脚本控制本地桌面版 Chrome，浏览器里的 cookies、插件和登录态全部复用。这种"人在回路"（man-in-the-loop）的方式，特别适合需要登录态、或要人工查看和脚本操作并存的流程。

做法是：在扩展的 Bridge Mode 面板开启监听，脚本侧创建AgentOverChromeBridge连接新标签页或当前激活的标签页，扩展弹出确认窗口、点击允许后，脚本就接管控制：

import { AgentOverChromeBridge } from '@midscene/web/bridge-mode'; const agent = new AgentOverChromeBridge(); await agent.connectNewTabWithUrl('https://www.bing.com'); await agent.ai('type "AI 101" and hit Enter'); await agent.aiAssert('there are some search results');

配置细节见桥接模式文档。

从单条脚本到工程化：报告、并发与多模型

要长期用起来，可观测性是关键。Midscene 生成可交互的 HTML 报告，记录每一步的截图、元素定位、AI 决策过程和操作与断言结果，测试失败时能直接定位问题出在哪一步。

工程能力上，Midscene Test 框架提供项目脚手架、平台预设、生命周期钩子、重试，以及执行项目之间的隔离与并发；它还能根据已注册节点生成 Markdown 参考文档，让开发者和 AI Agent 都能发现同一套能力、共同维护用例。

模型方面，它支持Qwen3.x、Doubao-Seed-2.1、GLM-4.6V、gemini-3.5-flash、UI-TARS等多模态模型，包含可自托管的开源选项。官方公开了基准成绩：

另外，基于截图的操作不用向模型发送庞大的 DOM 树：AppControlBench 一次 60 个任务的评测，模型调用总费用仅 0.59 美元，成本很可控。

先弄清楚的两个问题

两个上手时最常卡住的问题，答案都很明确。

没有文本、没有 DOM 语义的元素能定位吗？

能。纯图标按钮、<canvas>内容、原生应用界面、跨域 iframe 中的元素都在能力范围内，这是视觉定位的直接优势，不需要额外添加任何标注。

指令没生效时怎么排查？

两条路径：先打开 HTML 报告，查看该步截图和 AI 的决策过程，看它是"看错了"还是"理解偏了"；再回到 Playground 里反复试验和调整指令措辞，确认稳定后搬进脚本。

下一步建议：今天就装上 Chrome 扩展发出第一条指令，跑通后再把验证过的指令搬进你的测试工程，更多细节可以看官方文档目录。

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