告别选择器噩梦：Midscene.js 视觉自动化测试完整上手指南

【免费下载链接】midsceneAI-powered, vision-driven UI automation for every platform.项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

深夜十一点，你还在为一条测试用例发愁。产品经理上午改了按钮文案，下午改了布局，晚上设计师又换了图标。你盯着终端里红成一片的报错，默默叹了口气——又是#submit-btn找不到元素。这大概是每个写过 UI 自动化的人最熟悉的场景：选择器跟随页面结构而活，页面一改，测试就碎一地。

Midscene.js 就是冲着这个痛点来的。它是一个开源的视觉驱动 UI 自动化工具，核心思路只有一句话：只要你能截到屏幕，它就能操作。你不需要写选择器，只需要用自然语言描述"点击右上角的头像图标""在搜索框输入天气并回车"，多模态模型会看着截图自己完成定位和操作。Web、Android、iOS、桌面应用，一套思路通吃。

先纠正一个常见误解：它到底是不是"AI 随便点点"

很多人第一次听说 Midscene.js，会以为它就是个"AI 替人点网页"的玩具——模型看到什么点什么，结果不可控，也不敢用在正经项目里。这个理解对了一半，错了一半。

先说它对的部分：Midscene.js 确实是靠视觉模型看截图来理解界面的，不用 DOM、不用无障碍树、不用任何结构信息。再说错的部分：它远不止"随便点点"，而是一套工程化的自动化框架。它有明确的 API（aiAct操作、aiQuery取数据、aiAssert断言、aiWaitFor等待），可以无缝嵌入你现有的 Playwright、Vitest、Puppeteer 测试套件，跑完还会生成一份可逐步回放的可视化报告。

换个更准确的说法：它不是"AI 帮你点两下玩玩"，而是"把 AI 的眼睛和手装进你的测试框架"。你的测试用例依然是结构化的、可断言的、可回归的，只是"找到元素"这件事从查选择器变成了问模型。它要解决的从来不是"能不能自动操作"，而是"怎么让自动化测试不再被 UI 重构击垮"。

五分钟跑通第一个自动化脚本

先把"深究原理"放一边，我们直接用最短路径看到效果。你只需要三个步骤：装依赖、配环境变量、跑一段脚本。

第一步，安装依赖。

npm install @midscene/web playwright tsx --save-dev

第二步，配置你的多模态模型。用环境变量告诉 Midscene.js 调用哪个模型服务：

export MIDSCENE_MODEL_PROVIDER=openai export MIDSCENE_API_KEY=你的密钥

第三步，写一个不到二十行的脚本，描述你想做的事：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; const browser = await chromium.launch({ headless: false }); const page = await browser.newPage(); await page.goto('https://www.bing.com'); const agent = new PlaywrightAgent(page); await agent.aiAct('在搜索框输入 "today weather"，然后回车'); await agent.aiAssert('页面上显示了天气信息'); await browser.close();

跑npx tsx demo.ts，你会看到浏览器自己打开、自己搜索、自己判断结果。脚本结束时会输出一个 HTML 报告路径，打开它就能逐帧回放 AI 的每一步操作。先别急着研究每条 API，先体会一下"用一句话指挥浏览器干活"是什么感觉。

它能帮你解决哪四类真实问题

跑通之后，你可能已经发现了它和传统工具的本质差异。但它的价值不止于"省事"，具体拆开看，它解决的是四类此前很难缠的问题。

第一类：测试不再被前端重构反复击穿

传统 UI 测试的生命周期是这样的：写选择器 → 页面改版 → 修选择器 → 又改版 → 再修。每次 UI 调整都是全团队的加班时刻。Midscene.js 直接把这个循环掐断了——没有选择器，就没有可碎的依赖。产品改文案、工程师改 class、设计师换图标，测试代码一个字都不用动。

第二类：结构工具看不见的元素，它都看得见

有一类元素是 DOM 选择器的天敌：纯图标按钮没有文字标签、自定义控件渲染成<canvas>、跨域 iframe 里内容不可访问、原生 App 根本没有 DOM。但这一切在"人眼"看来毫无障碍——你能看到图标、能看到 canvas 上的内容、能看到屏幕上的 App。Midscene.js 只认截图，所以只要人能看见，它就能操作。

第三类：断言"用户真正看到的东西"

传统断言检查的是"这个 DOM 节点存在吗"。但用户在意的是"这个按钮是不是高亮的""这个弹窗是不是挡住了内容""这个图表是不是渲染出来了"。Midscene.js 的aiAssert直接问视觉模型："页面左上角是否有一个红色错误提示？"它验证的是渲染结果，而不是代码结构——这正是 QA 想验证的事。

第四类：一套 API 覆盖全平台

过去做移动端自动化是另一套技术栈、另一套学习成本：Android 用 Appium、iOS 用 XCUITest、桌面再来一套。Midscene.js 把 Web、Android、iOS、HarmonyOS、桌面应用统一到同一套aiAct/aiQuery/aiAssertAPI 上。学会了操作网页，就等于学会了操作手机和桌面应用，只是换了个 device 对象而已。

原理浅析：为什么"只看截图"反而更稳

你可能会好奇：放弃了 DOM 这种"精确结构"，只靠截图，为什么反而更可靠？

关键在"依赖什么"这件事上。DOM 结构是渲染栈的产物——它是代码的实现细节。前端框架一天三变，DOM 结构就跟着三变；但用户看到的画面是产品形态，它变化频率低得多，而且不同平台之间高度相似。Midscene.js 把"画面的截图"当作唯一的真值来源，等于把自动化从"追着实现细节跑"变成了"对着产品形态工作"。

具体工作时，它调用的是具备视觉理解能力的多模态模型：模型看着截图理解界面、根据你的自然语言指令规划动作、计算出目标元素在截图上的坐标，然后由驱动层执行点击和输入。整个过程里，UI 操作和元素定位都不依赖 DOM 数据或额外标注。同时，token 消耗只跟截图分辨率和任务复杂度有关，不会因为页面上 DOM 节点增多而膨胀。

当然这条路也有代价：它要求模型本身具备稳定的界面理解能力，不是随便接一个大语言模型就能用。但 Midscene.js 把模型选择做成了配置项——Qwen、Doubao、GLM、Gemini、UI-TARS 都支持，包括可以自托管的开源模型——你把"模型选型"变成一道选择题，而不是一道编程题。

四个角色可以这样用起来

Midscene.js 的价值在不同角色手里会以不同方式兑现，下面给每个角色一条可照做的路径。

前端/测试开发工程师：接入现有测试套件。在 Playwright 项目里引入@midscene/web，把高价值的端到端用例逐步换成自然语言写法。建议从"最容易碎"的用例开始迁移——比如依赖复杂选择器的登录流程、表单校验流程。具体的接入方式可以看项目里的 integrate-with-playwright 文档。

QA/测试工程师：零代码先验证思路。如果还不想碰代码，装上 Chrome 扩展，在任意网页上直接输入指令试用。扩展和 SDK 共用同一套核心，你在扩展里验证通过的指令，写成脚本后行为完全一致。这在写测试脚本前先探路，能省大量试错时间。

运维/CI 负责人：把视觉用例塞进流水线。Midscene.js 支持 YAML 脚本，一个文件就是一个测试任务，任何不懂 API 的团队成员都能维护。配上 CLI 就能在 CI 里跑，产出 HTML 报告留档。示例可以看 automate-with-scripts-in-yaml。

团队管理者：拿可视化报告做验收依据。每次运行生成的 HTML 报告带时间轴回放，失败原因一目了然。开会评审时不用再贴一堆日志，直接把报告链接甩出来，大家自己看 AI 在哪一步做错了什么。

新手最容易踩的四个坑

走了这么多路，说说我见过的新手最常见的翻车点，提前绕开能省很多时间。

坑一：选错了模型。Midscene.js 要求模型具备视觉理解能力，普通文本模型接了也白接。优先选官方文档推荐的视觉模型，配置里MIDSCENE_MODEL_FAMILY要跟模型对上，否则定位逻辑会错乱。

坑二：指令写得太"功能化"。写aiTap('个人中心')可能定位失败，因为模型不知道个人中心图标长什么样；改成aiTap('右上角的用户头像图标')，定位立刻变准。秘诀是用视觉特征和位置信息描述元素，就像你向朋友描述一样。

坑三：元素定位偏了几个像素。如果模型找对了目标但坐标有偏差，开启deepLocate通常能显著改善精度。网页场景还可以把浏览器 DPR 提到 2，画面更清晰，小元素定位更稳（代价是多花点 token）。

坑四：觉得跑得慢。用aiTap、aiInput这类即时动作 API 代替宽泛的aiAct，用低分辨率截图省 token，调试期开启缓存——详细技巧在 caching 文档里。

下一步：把"看得见的测试"变成你的默认选项

回头看看开头那个深夜改选择器的场景。Midscene.js 提供的不是又一个测试工具，而是把 UI 自动化从"依赖实现细节"迁移到"依赖产品外观"的一次范式转换。它不能消灭所有测试问题，但能让你把维护测试的时间省下来，花在真正值得测的事情上。

接下来建议你按这个顺序推进：先装 Chrome 扩展在真实页面上玩半小时，体会指令怎么写更稳；然后照着快速开始文档跑通第一个 SDK 脚本；最后把一条你目前最头疼的用例迁移过来，对比一下维护成本的变化。源码就在仓库的 packages 目录下，核心逻辑在 packages/core 里，遇到想深入了解的机制可以直接翻。

当你的测试不再因为一个 class 名改动就全线飘红时，你会明白什么叫"让 AI 替你看着屏幕干活"。测试代码终于可以关注"产品该是什么样"，而不是"页面内部长什么样"了。

【免费下载链接】midsceneAI-powered, vision-driven UI automation for every platform.项目地址: https://gitcode.com/GitHub_Trending/mid/midscene