视觉UI自动化测试终极入门：如何用一句话驱动 Web、Android 与 iOS 的界面操作？

视觉UI自动化测试终极入门：如何用一句话驱动 Web、Android 与 iOS 的界面操作？

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

你有没有过这样的经历：写好的 UI 测试用例，因为前端改了个 class 名、按钮挪了个位置，第二天就全线飘红；或者遇到一个纯图标按钮、一段 canvas 绘制的图表，怎么也定位不到；再或者，你想测的是原生 App，却发现传统自动化工具根本够不着。维护选择器的时间，比写测试的时间还长，很多人最后干脆放弃了自动化。

如果你正在被这类问题折磨，那么Midscene.js 这款开源的视觉UI自动化测试工具，很可能是你需要的答案。它的思路很特别：不读 DOM、不看结构树，只看截图，用自然语言让多模态模型理解界面、规划操作，实现真正意义上的"所见即可测"。

一句话认识它：3 秒判断适不适合你

Midscene.js 是一个纯视觉驱动的跨平台自动化测试 SDK。你用中文（或英文）描述"做什么"，它通过截图 + 多模态模型自行理解界面并执行操作，覆盖 Web、Android、iOS、HarmonyOS 与桌面应用。

亮点速览：

• 🧠自然语言驱动测试：aiAct、aiQuery、aiAssert三个核心 API 覆盖操作、提取、断言
• 🔭纯截图工作：不依赖选择器，元素重构不再导致用例失效
• 📱跨平台自动化测试工具：同一套 API 跑遍浏览器、手机、桌面
• 🎬可视化报告：每次运行生成可逐步回放的报告，AI 行为不再是黑盒
• 🔌零代码体验：Chrome 插件即装即用，不写一行代码就能试
• 🆓开源免费：MIT 协议，支持 Qwen、GLM、Gemini、UI-TARS 等多种模型

实操演示：8 步跑通你的第一个自然语言自动化脚本

我们以最常用的 Web 场景（Playwright 驱动）为例，带你把第一个脚本完整跑起来。整个过程只需几分钟。

第一步：创建项目并安装依赖

npm init -y npm install @midscene/web playwright tsx dotenv --save-dev

第二步：配置 AI 模型

Midscene 的元素定位依赖多模态模型的视觉能力，所以这一步很关键。以 OpenAI 兼容接口为例，写入.env文件：

export MIDSCENE_MODEL_PROVIDER=openai export MIDSCENE_MODEL_API_KEY=你的密钥 export MIDSCENE_MODEL_NAME=qwen3-vl-plus export MIDSCENE_MODEL_FAMILY=qwen

不同服务商（Doubao、GLM、Gemini、UI-TARS 等）的配置略有差异，官方文档的"支持的模型与配置"页面可以直接复制对应配置。

第三步：编写脚本

新建demo.ts，你会发现整段代码里几乎没有选择器——所有关键步骤都是大白话：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; import 'dotenv/config'; const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)); (async () => { const browser = await chromium.launch({ headless: false }); // 实时观察运行 const page = await browser.newPage(); await page.goto('https://www.ebay.com'); await sleep(3000); const agent = new PlaywrightAgent(page); // 用自然语言执行操作 await agent.aiAct('在搜索框输入 "Headphones"，然后回车'); await agent.aiWaitFor('列表中至少出现一个耳机商品'); // 提取结构化数据 const items = await agent.aiQuery( '{ title: string, price: number }[], 列表中的耳机商品', ); console.log('headphones in stock:', items); // 用自然语言做断言 await agent.aiAssert('页面左侧有一个分类筛选栏'); await browser.close(); })();

第四步：运行

npx tsx demo.ts

第五步：查看报告

运行结束后，控制台会打印一行类似midscene_run/report/xxx.html的路径。用浏览器打开它，就能看到每一步操作的截图、AI 的规划思路、执行耗时与最终结果，可以像看录像一样逐帧回放。这个报告也是排查"AI 为什么点错了"的核心工具。

第六步：试试零代码路径（可选）

如果你连脚本都不想写，可以直接安装 Chrome 扩展，打开任意网页，在侧边栏输入"点击搜索框并输入 xxx"，就能立即看到效果。插件与 SDK 共用同一套核心引擎，在插件里验证通过的指令，写进脚本后行为一致。

第七步：换个平台继续跑

跑通 Web 之后，你会发现 Android、iOS 的玩法几乎一样——换一个 Agent 实现，API 完全不变。文档里给出了各平台的接入指南，Android 通过 ADB 连接设备，iOS 借助 WebDriverAgent，均无需 root 或越狱。

第八步：接入你的测试套件

Midscene 可以嵌入现有的 Playwright 测试用例中，作为测试代码的一部分来使用，与常规断言协同工作。比如"用 AI 完成登录 → 用普通断言校验数据"这种混合写法，是很多团队喜欢的模式。

进阶技巧：让 AI 更聪明、更快、更省钱的 5 个技巧

跑通之后，下面几个技巧能明显提升你的使用体验：

1. 用"即时操作 API"替代通用ai()。agent.aiTap('登录按钮')、agent.aiQuery(...)这类即时接口把"规划 + 定位 + 执行"拆得更细，每一步目的单一，成功率比笼统的ai('点击登录按钮并进入主页')更高，也更省 token。

2. 开启缓存加速调试。重复调试同一脚本时，AI 每次重新规划很费时间。给 Agent 配置cache: { id: 'my-test' }后，规划与元素定位结果会被缓存到midscene_run/cache，官方实测同类任务耗时可从 51 秒降到 28 秒。注意：查询与断言类操作不会被缓存，保证结果总是新鲜的。

3. 定位不准时试试deepLocate。如果 AI 大致点对了目标、但总偏几个像素，可以在定位操作上加deepLocate: true，对边界敏感的小元素有明显改善。

4. 用 JavaScript 拆分复杂任务。与其让 AI 一次干十件事，不如把它拆成多步循环。例如先用aiQuery拿到列表，再用for循环逐条判断、逐条点击。可控性更强，出错了也知道是哪一步的问题。

5. 善用 YAML 脚本与报告播放器。复杂流程可以写成 YAML 结构化脚本，交给 CLI 执行；报告页面还支持player-only=1之类的参数嵌入到你的内部平台，团队评审时直接看回放。

横向对比：和传统方案比，它赢在哪里、输在哪里

为了让你判断得清楚，我把它和两类常见方案放在一起看：

结论很直白：如果你的界面高度稳定、追求极致的执行速度与零成本，传统选择器依然是性价比之王；但如果你受够了选择器维护、要覆盖原生应用与复杂 UI、或者想验证"用户真正看到的效果"，纯视觉方案的优势是碾压性的。Midscene 也允许你在同一脚本里混合两种风格——稳定路径用普通断言，复杂交互交给 AI，两头的好处都拿到。

适用人群：这几类人最该立刻上手

• 测试工程师：写用例像写需求文档，重构不再背锅
• 前端开发者：自测、跨浏览器验证、canvas/图表场景一把梭
• 做 AI Agent 的开发者：通过 Skills 让 AI 编程助手直接驱动各平台界面
• 想零成本验证产品的人：装个 Chrome 插件就能让 AI 帮你走查页面
• 中小团队：没有专职测试基建，用自然语言快速搭建可复用的自动化脚本

避坑指南：新手最常见的 5 个坑

坑 1：模型没有视觉能力，或MIDSCENE_MODEL_FAMILY配错。元素定位完全依赖多模态模型，务必选支持视觉的模型，并核对 family 配置与文档一致，否则可能出现诡异的定位失败。

坑 2：提示词只写功能、不写视觉特征。aiTap('个人中心')模型可能不知道图标长什么样；改成aiTap('人形头像 icon')或aiTap('页面右上角的人形头像图标')，命中率立刻提升。多用"位置 + 视觉特征"描述。

坑 3：Chrome 插件与其它扩展冲突。报错Cannot access a chrome-extension:// URL of different extension时，多半是别的插件注入了 iframe/script。到chrome://extensions/找到对应 ID 的插件禁用即可。

坑 4：截图分辨率太低导致小元素定位偏移。网页里可以把 devicePixelRatio 调到 2，画面更清晰、定位更准（代价是多耗 token）；也可以用小分辨率截图降低成本，按场景取舍。

坑 5：用旧版本踩新坑。定位算法随版本持续优化，遇到奇怪问题先npm install @midscene/web@latest升级再排查。

下一步行动：从 30 分钟体验开始

别急着写复杂脚本。我的建议是：先装 Chrome 插件，花 10 分钟在你自己最常用的网页上玩几条指令；感受过"一句话操作界面"的爽感后，再照着官方快速开始文档把 demo 脚本跑一遍，然后挑一个你正在维护的页面，写一条真实用例。

Midscene.js 目前的想象空间很值得期待：多模态模型越来越强，意味着定位精度、复杂任务规划能力会持续提升；社区已出现 Python、Java 等语言 SDK，以及面向车机、PC 的扩展方案；当"视觉 + 自然语言"成为 UI 自动化的默认范式，测试工程师的工作重心将从"维护定位符"转向"设计更贴近用户的验收描述"——这大概就是自动化测试的下一个十年。现在开始，成本不过是一个周末的下午。

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