Midscene.js 跨平台 UI 自动化实战指南三步跑通自然语言测试脚本【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个基于视觉模型的开源 AI 自动化框架。你用自然语言描述操作它就能看懂屏幕画面并驱动 Web、Android、iOS、HarmonyOS 和桌面端界面。下面结合仓库里的真实命令和脚本讲清它的工作原理、上手步骤和踩坑点。传统脚本脆在哪它差在哪选择器写 UI 自动化脚本代价是持续的维护成本。页面一重构XPath 和 CSS 选择器就可能集体失效。而且靠 DOM 结构的工具天生看不见纯图标按钮、canvas 渲染内容、原生应用界面和跨域 iframe。Midscene.js 换了思路它不看页面结构只看截图。视觉定位就像人盯着屏幕找按钮——只要人眼能看到它就能点。你像真人测试那样用大白话描述目标和校验条件即可。对比维度基于 DOM / 无障碍树Midscene.js 纯视觉定位依据页面结构截图 多模态模型图标按钮、canvas、跨域 iframe通常不可达可见即可操作界面变化后维护重写选择器用例通常无需改动它是怎么工作的核心链路只有三步截屏、理解、操作。每一步执行前Midscene 先截一张当前屏幕的图把图和你的自然语言指令一起交给多模态视觉模型模型返回要操作元素的坐标和动作再由设备层执行点击、输入或滚动。三个最常用的 API 覆盖了大部分场景aiAct给出目标它自己规划多步操作直到完成aiQuery从界面上按指定结构提取数据比如商品列表aiAssert用自然语言断言界面状态不通过就报错模型方面它支持 Qwen3.x、Doubao-Seed-2.1、GLM-4.6V、gemini-3.5-flash、UI-TARS 等也支持自托管的开源模型。三步跑通第一个自动化脚本装 CLI。确认 Node.js 是 20.19、22.12 或 24然后全局安装命令行工具npm i -g midscene/cli配模型。在脚本运行目录创建.env以豆包为例换模型就改这四行MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 MIDSCENE_MODEL_API_KEY你的APIKey MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 MIDSCENE_MODEL_FAMILYdoubao-seed跑脚本。写一个bing-search.yaml并执行命令完成后会直接生成可视化报告page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息midscene ./bing-search.yaml不用写浏览器代码脚本里每个自然语言步骤都会先截屏、再交给模型理解和执行。核心能力盘点YAML 声明式脚本。整个用例就是一个 YAML 文件ai执行操作、sleep等待、aiQuery提取数据、aiAssert校验结果。仓库里的 Android 示例脚本 展示了完整的组合方式。跨平台统一 API。Web、Android、iOS、HarmonyOS、桌面端共用同一套接口换平台主要是换设备连接配置脚本主体基本不动。Android 端设备控制实现在 packages/android/。视觉断言。aiAssert校验的是用户实际看到的效果——颜色、高亮、布局而不只是某个节点存不存在这对回归测试很有价值。每次运行都有报告。执行完成后自动生成 HTML 报告可逐步回放截图和操作过程失败时定位原因不用翻日志真实场景电商搜索加购回归以搜索商品并加入购物车的回归用例为例流程可以写成打开商品页aiAct完成搜索蓝牙耳机点击第一件商品加入购物车aiAssert校验购物车角标数量增加 1aiQuery提取{name: string, price: number}[]核对商品数据aiAct进入购物车断言结算按钮可见如果页面中间弹出登录或营销弹窗在aiAct的提示词里加一句如出现弹窗先关闭即可不需要为弹窗单独写处理分支。复杂任务还可以开启deepThink加强任务拆解和deepLocate更精确的元素定位用少量额外调用换稳定性。避坑指南adb devices看不到设备现象是 Android 用例直接报连不上设备。先确认手机已开 USB 调试并允许了调试授权再确认 adb 版本与手机系统匹配必要时执行一次adb kill-server后重试。Ollama 模型报 403本地模型服务默认不允许扩展访问设置环境变量OLLAMA_ORIGINS*后重启服务即可。元素定位偶尔失败目标元素小、和周围元素长得很像时给aiTap等即时交互 API 加上deepLocate: true多一次模型调用换更准的坐标。报Cannot access a chrome-extension:// URL通常是其他 Chrome 扩展向页面注入了冲突的脚本。在开发者工具里找到以chrome-extension://开头的注入节点按扩展 ID 在扩展列表里禁用它再刷新页面。Rspack 报Unsupported Node.js versionCLI 的部分执行路径要求 Node 20.19、22.12 或 24升级 Node 后重装midscene/cli。适合谁下一步看什么如果你在用 Playwright 或 Appium 写 UI 测试、被选择器维护折磨或者要覆盖DOM 工具够不到的原生应用和 canvas 场景Midscene.js 值得直接试。建议路径先读中文文档目录里的基本概念和快速开始用 Chrome 扩展零代码体验一遍再接入现有测试工程需要细看实现时核心引擎是入口。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考