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

告别选择器噩梦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、不用无障碍树、不用任何结构信息。再说错的部分它远不止随便点点而是一套工程化的自动化框架。它有明确的 APIaiAct操作、aiQuery取数据、aiAssert断言、aiWaitFor等待可以无缝嵌入你现有的 Playwright、Vitest、Puppeteer 测试套件跑完还会生成一份可逐步回放的可视化报告。换个更准确的说法它不是AI 帮你点两下玩玩而是把 AI 的眼睛和手装进你的测试框架。你的测试用例依然是结构化的、可断言的、可回归的只是找到元素这件事从查选择器变成了问模型。它要解决的从来不是能不能自动操作而是怎么让自动化测试不再被 UI 重构击垮。五分钟跑通第一个自动化脚本先把深究原理放一边我们直接用最短路径看到效果。你只需要三个步骤装依赖、配环境变量、跑一段脚本。第一步安装依赖。npm install midscene/web playwright tsx --save-dev第二步配置你的多模态模型。用环境变量告诉 Midscene.js 调用哪个模型服务export MIDSCENE_MODEL_PROVIDERopenai 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、设计师换图标测试代码一个字都不用动。场景传统选择器方案Midscene.js 视觉方案按钮文案修改报错需要改测试无需改动CSS 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考