Midscene.js实战指南：如何用视觉AI替代脆弱选择器，一套自然语言搞定Web到手机的UI自动化测试

Midscene.js实战指南：如何用视觉AI替代脆弱选择器，一套自然语言搞定Web到手机的UI自动化测试

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

Midscene.js 是一款面向端到端（E2E）测试的 GUI Agent，它靠"看图说话"驱动 AI 多模态模型，让你用一句句自然语言就能操作 Web、Android、iOS、HarmonyOS 和桌面应用。你不再需要维护脆弱的 CSS 选择器，也不必为每个平台各写一套脚本，这是 Midscene.js 与所有传统 UI 自动化工具最本质的区别。

那个深夜，你还在为一条选择器debug吗

想象一下这个场景：你花了一下午写好一条#login-form > div:nth-child(3) > button定位登录按钮，第二天前端同事顺手改了 DOM 结构，你的整个测试套件全线飘红。更崩溃的是，产品里还有纯图标按钮、<canvas>绘制的图表、跨域 iframe 里的支付组件——用传统工具，这些元素要么"看不见"，要么根本测不了。原生 App 呢？要么引入整套重框架，要么靠坐标硬点，换个分辨率就翻车。

这种"测一次改一次"的循环，相信每个写过 UI 测试的人都懂。问题不在你的脚本，而在工具的定位逻辑本身。

一句话认识 Midscene.js

Midscene.js 是一个AI 视觉驱动的 GUI Agent：它像人一样"看着"屏幕截图来理解界面，用自然语言完成定位、点击、输入、断言与数据提取。解决什么问题？选择器脆弱、无语义元素不可达、原生应用与跨域页面难以测试、界面视觉效果无法验证。给谁用？想用更少维护成本做 E2E 测试的开发者、需要跨 Web/Android/iOS/桌面统一测试的团队，以及想快速搭建 UI 自动化的产品与测试工程师。

它和 Selenium、Playwright 到底差在哪

传统工具"读结构"，Midscene.js "看像素"。这一字之差，带来的是完全不同的维护体验：

Midscene.js 还有个独特设计：先看后做。模型会先"观察"截图再规划点击位置，这让它天然免疫分辨率变化、页面微调带来的误操作。

上手路线图：3步跑通你的第一个自动化脚本

第一步：装好"眼睛"——配置多模态模型。这是唯一绕不开的准备工作。Midscene.js 支持 Qwen-VL、UI-TARS、Gemini、GLM 等具备 UI 定位能力的多模态模型，也支持可自托管的开源选项。只需要准备模型的 API Key 与服务地址，官方文档apps/site/docs/zh/model-common-config.mdx里有完整对照表。

第二步：用 Chrome Extension 零代码体验。在 Chrome 应用商店安装 Midscene 扩展，粘贴模型配置并保存。打开任意网页，侧边栏输入一句中文指令，比如"点击登录按钮"，它就会自己规划步骤并执行。这一步 5 分钟就能完成，非常适合先验证模型效果再写代码。

第三步：把指令升级成可复用的脚本。在项目中安装@midscene/web，用最精简的代码接入：

import { PlaywrightAgent } from '@midscene/web/playwright'; // 创建 agent 后，一句自然语言就是一个步骤 await agent.aiAct('在搜索框输入 "Headphones" 并回车');

不用写选择器、不用管等待时机，这一句就是完整的一步。全部 API 的调用方式见packages/core/src与文档reference/。

核心能力，从会用升级到用好

第一级：让脚本"看得懂、点得准"

四个基础 API 覆盖 90% 的日常场景：

• aiAct：多步骤规划，一句"把第一件商品加入购物车并确认数量变为1"它会自己拆解执行；
• aiTap/aiInput：单步定位并点击、输入，输入默认替换原有内容；
• aiAssert：视觉断言，"页面顶部显示导航栏"，不满足会抛错并说明原因；
• aiQuery：结构化数据提取，直接返回 JSON 对象数组。

小技巧：当目标元素特别小、容易和周围元素混淆时，给aiTap加上deepLocate: true，会多一次模型调用专门确认坐标，误点率明显下降。

第二级：让 AI 替你编排流程

遇到"如果出现弹窗先关闭，再点结账"这类带分支的任务，别自己写 if/else。用aiAct把整条路径交给 Agent，它会基于最新的界面状态持续规划，弹窗出不出现它都能应对。只有当流程完全固定、必须精确控制每一步时，才用 JavaScript 编排（aiQuery拿到数据后循环处理）。原则很简单：不确定的流程交给aiAct，确定的流程才自己写代码。

第三级：用 YAML 把测试写成"说明书"

不想维护大型测试工程？Midscene.js 支持纯 YAML 脚本，几行就能跑一个检查：

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

Web、Android、桌面端都能用同一套 YAML 格式，非常适合冒烟测试和关键路径巡检，写法参考apps/site/docs/zh/automate-with-scripts-in-yaml.mdx。

跨平台：一套思路，五个平台

只要"能截图"，Midscene.js 就能工作。Android 走 adb + scrcpy，iOS 用 WebDriverAgent，加上 HarmonyOS 和桌面端，每个平台都有对应的 Playground 可以先试后写，平台接入指南在apps/site/docs/zh/platforms/目录下。

新手最容易踩的4个坑

坑1：模型没配好，指令永远没反应。症状是运行时报连接错误或超时。解法：先检查MIDSCENE_MODEL_BASE_URL、API_KEY、MODEL_NAME三个环境变量是否齐全，并确认模型属于文档"支持列表"内的 UI 定位型模型。

坑2：Ollama 本地模型返回 403。本地起 Ollama 时扩展访问被拦。解法：设置环境变量OLLAMA_ORIGINS="*"再重启服务。

坑3：浏览器扩展互相打架。报错Cannot access a chrome-extension:// URL，通常是其他扩展注入了 iframe 或脚本。解法：打开 DevTools 找到注入的扩展 ID，去chrome://extensions/禁用它再刷新页面。

坑4：切换模型后点击坐标偏移。同一脚本在官方 API 正常、换到网关后点击位置固定偏移。解法：优先使用视觉定位而非坐标；如必须用坐标，把截图分辨率固定，并阅读 FAQ 里针对 Azure 等网关的配置说明。

真实场景演练：30行代码做一次电商"逛买"巡检

以电商搜索为例，看 Midscene.js 怎么把"人怎么逛，脚本就怎么写"落地：

const agent = new PlaywrightAgent(page); await agent.aiAct('搜索 "Headphones" 并回车'); await agent.aiWaitFor('页面上出现了至少一个耳机商品'); const items = await agent.aiQuery( '{itemTitle: string, price: number}[], 列表中的商品及价格' ); // 对每个商品做断言与点击，完全不需要 DOM await agent.aiAssert('页面左侧有分类筛选栏'); await agent.aiTap('列表中的第一件商品');

为什么这么写？因为aiWaitFor取代了脆弱的 sleep 等待，aiQuery返回的是可直接断言的 JSON，aiTap靠视觉找元素——整段代码里没有一个选择器，页面前端怎么改都不会让这套巡检失效。同样的逻辑，把 agent 换成 Android 的，就成了一台真机上的 App 巡检。

让它跑得更快更稳的4个习惯

1. 开启规划与定位缓存：相同指令重复执行时命中缓存，官方实测一个案例耗时从 51 秒降到 28 秒。配置cache: { id: "my-test" }即可，缓存文件在./midscene_run/cache/。注意：查询类 API（aiQuery/aiAssert）永不缓存，别指望它们提速。
2. 给aiAct补充业务上下文：用agent.setAIActContext('出现Cookie弹窗先关闭，价格单位是美元')，减少模型瞎猜、提高一次成功率。
3. 复杂任务开deepThink：它把"规划"和"定位"拆成两次独立模型调用，成功率更高，代价是更慢更贵，只在关键流程上开。
4. 固定视口与截图质量：脚本里统一设置setViewportSize，避免不同机器分辨率导致视觉定位差异。

文档、代码与社区资源一览

想深入，这几个入口最有用：

• 官方文档：apps/site/docs/zh/覆盖快速开始、模型策略、缓存、数据隐私与 FAQ；
• 核心实现：packages/core/src/agent/是 Agent 与视觉定位引擎，packages/web-integration/是各平台接入层；
• 平台代码：Android 在packages/android/，iOS 在packages/ios/，桌面端在packages/computer/；
• 演示报告：apps/report/e2e/里有可直接打开查看的 YAML 测试报告样例；
• Chrome 扩展与桌面 Studio：apps/chrome-extension/、apps/studio/，分别对应网页与本地调试体验。

下一步：现在就去点第一个"按钮"

Midscene.js 把 UI 自动化从"维护选择器"拉回到了"描述意图"，这不仅是工具的升级，更是测试思路的转变——让 AI 替你"看"，你只管说清要什么。别再等下一个重构让你改测试了，现在就动起来：

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

然后装好 Chrome 扩展、贴入模型配置，对任意网页输入那句"点击登录按钮"。当它真的替你点下去的那一刻，你就知道为什么说这是测试的新玩法了。

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