Midscene.js 完整指南：如何用视觉AI写出跨平台UI测试的5分钟教程
【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene
昨天还能点中的按钮，今天前端一重构就全跑偏了。Midscene.js 是一款视觉 AI UI 自动化测试工具，它不读页面代码，只靠截图定位并操作界面元素，让你用自然语言编写 Web、Android、iOS、HarmonyOS 和桌面端的测试脚本，不用再维护一行选择器。
基于选择器的测试，为什么总是坏
先看一个最常见的场景：前端改了个 className，回归套件里三十多条用例接连变红。你只能挨个进代码里翻选择器，每次发版都像一场选择器抢修。
再看一类根本抓不到的元素：页面右上角只有一个齿轮图标，没有文字、没有 aria 标签；商品图整块画在<canvas>里。传统工具从这里拿不到任何语义信息，只剩记录像素坐标这一条路——分辨率一变、窗口一变，全废。
最后，被测对象如果根本不是网页呢？同一套逻辑要在 Android 和 iOS 上各测一遍，ADB、WebDriverAgent 各有各的工具链，跨域 iframe 浏览器工具也够不着。三个平台维护三份脚本，是这类项目的日常。
Midscene.js 的对策很直接：不看 DOM，只看屏幕。上面三件事本质都是"屏幕上的一堆像素"，用同一种办法就能处理。
一条命令跑通第一次自动化
前提只有一个：一个具备 UI 理解能力的多模态模型。把它的 Base URL、API Key 和模型名称写进运行目录的.env，共四个变量，完整格式见官方文档的支持的模型与配置：
MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628" MIDSCENE_MODEL_FAMILY="doubao-seed" MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" MIDSCENE_MODEL_API_KEY="换成你自己的key"然后安装 CLI，写一个七行的脚本：
npm i -g @midscene/cli midscene ./bing-search.yamlpage: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 "今日天气" - aiAssert: 结果显示天气信息命令会打印执行进度，结束后在midscene_run/report/下生成 HTML 报告，每一步的截图和断言结果都能点开看。脚本字段全集参考YAML 脚本运行器。
它是怎么做到的
把 Agent 想象成一个只会"看截图用软件"的新同事。你交代任务后，他永远走同一个循环：截图 → 模型判断屏幕上的内容和下一步动作 → 点击、输入或滚动 → 再截图确认是否完成 → 不满意就重来，直到目标达成。
这个设计带来两个好处。其一，发给模型的只是截图，不是整棵 DOM，单步 token 成本很低：官方报告的 AppControlBench 60 个任务，模型总花费 0.59 美元，通过 58 个，通过率 96.7%。其二，输入永远是同一类"屏幕画面"，所以同一套 API 在 Web、Android、iOS、HarmonyOS 和桌面端通用，不用换写法。
三个真实场景：从 Web 到移动端
场景一：Web 搜索与价格校验
目标：验证电商搜索页"100 美元以下"的筛选是否生效，并把结果页数据抽成结构化列表。
关键步骤：在现有 Playwright 的page上创建 Agent，整条流程用一句自然语言描述：
const agent = new PlaywrightAgent(page); await agent.aiAct('在搜索框输入 "Headphones" 并回车'); await agent.aiAssert('页面中的商品价格在 100 美元以下');验证点：断言判断的是截图里的视觉事实，不是 DOM 结构。价格超标的商品会让用例直接失败，不需要再写"字段缺失兜底"之类的补丁代码；后续还可以用aiQuery把商品和价格抽成对象数组。
场景二：Android 榜单组合筛选
目标：验证懂车帝 App 销量榜在"轿车 + 燃油 + 18–25 万"等组合筛选下，列表更新是否正确。
关键步骤：用 adb 连上真机，把逐条筛选动作写成 YAML 步骤执行，无需抓取原生应用的视图树。
验证点：每次切换筛选后，确认列表首项与所选条件匹配。官方样例报告显示，8 步脚本的用例平均消耗约 13 万输入 token、费用约 0.3 元。
场景三：iOS 系统设置验证
目标：验证设置页"深色模式"开关确实生效——这是 WebDriverAgent 连上 iOS 设备后的典型用例。
关键步骤：打开设置，进入"显示与亮度"，切换深色模式，回到桌面观察界面变化。
验证点：最终判断依据是"屏幕是否真的变暗了"。这种视觉断言是选择器方案写不出的；HTML 报告会留一张最终状态截图，通过或失败的原因一眼可见。
Midscene.js 与传统自动化工具对比
| 维度 | Midscene.js | 选择器方案（Selenium / Cypress 等） |
|---|---|---|
| 定位依据 | 截图 + 自然语言 | CSS / XPath / 可访问性树 |
| 重构后的影响 | 脚本通常不用改，跑一遍确认即可 | 选择器失效，需逐条修复 |
| 图标按钮、canvas、自定义控件 | 只要屏幕上可见就能操作 | 基本无法定位，只能退回坐标 |
| 原生应用与跨域 iframe | 同一套 API 覆盖 | 每个平台单独一套工具链 |
| 断言对象 | 屏幕上的视觉结果（颜色、布局、文案） | 主要面向 DOM 结构与文本 |
| 额外开销 | 按用例消耗模型费用（官方样例平均约 0.3 元/条） | 无模型费，但选择器维护成本高 |
高频疑问
它会往模型里发什么？
默认只发屏幕截图；DOM 信息只在你为数据提取等场景显式打开domIncluded时才会附带。界面涉及敏感内容的话，先确认这一点。
AI 每一步都要几秒，怎么提速？
两条实用路径：固定动作改用即时接口（aiTap/aiInput）代替完整规划，省掉不必要的思考环节；开启缓存，让已验证过的定位结果不重复计算。再调低截图分辨率也能省 token。
能用自托管的模型吗？
可以。支持 UI-TARS、Qwen-VL 等可自托管的开源模型，也支持 Doubao Seed、GLM-4.6V、gemini-3.5-flash 等商用服务；规划模型和视觉模型还能拆成两个，按成本取舍。
界面是英文的，脚本必须也用英文写吗？
不必。脚本就是自然语言，中文、英文、中英混着写都可以，不需要和界面语言对齐。
从哪开始
如果你的测试套件里还有一大堆选择器在跟着前端重构走，或者被测对象包含原生应用和桌面界面，Midscene.js 值得试。先装上 CLI 跑通上面的 bing-search.yaml，写正式用例前，可以先在 Chrome 扩展 Playground 里把话术跑顺。
【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
