Midscene.js 新手指南：3 分钟用自然语言跑通跨平台 UI 自动化

Midscene.js 新手指南3 分钟用自然语言跑通跨平台 UI 自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene维护 UI 自动化脚本的人大概率都被选择器消耗过时间一次前端重构几十条locator集体失效。Midscene.js 的思路是直接绕开 DOM——它是一个开源的 GUI Agent通过视觉模型看截图来定位元素你只用自然语言写测试步骤Web、Android、iOS、HarmonyOS 和桌面应用都能跑天然适配 Midscene.js 自然语言 UI 自动化、跨平台 UI 测试这类诉求。 价值速览它替谁省了什么活前端重构脚本不动。传统方案靠选择器找元素类名一改全线崩Midscene.js 靠截图识别元素有没有 id、有没有语义标记都不重要人眼看得见的东西它都能点。够得着看不见的元素。纯图标的按钮、canvas画布里的控件、跨域 iframe 内部的内容、原生 App 界面——这些对 DOM 方案来说要么是盲区要么要换一套技术栈对它来说只是截图里的一块区域。断言的是用户真正看到的东西。除了节点存不存在你还可以直接断言页面顶部显示导航栏价格标签高亮为红色这类渲染层面的状态这在传统工具里很难表达。⚙️ 环境准备Midscene.js 安装与模型配置步骤1. 安装 CLI终端环境要求 Node.js20.19、22.12或24然后全局安装命令行工具即可无需搭建任何测试框架npm i -g midscene/cli如果打算从源码开始仓库为只读仅供阅读参考git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene pnpm install2. 配置 AI 模型Midscene.js 依赖一个具备 UI 定位能力的多模态模型。在运行目录下建一个.env文件注意.env必须放在工具运行目录而不是 YAML 文件所在目录MIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAME模型名称 MIDSCENE_MODEL_FAMILY模型系列豆包、千问、GLM、Gemini、GPT 等主流模型均可接入支持的模型与配置示例见 model-common-config.mdx。3. 在 Chrome 里体验可选但推荐Chrome 扩展是 Midscene 面向 Web 的 Playground无需写代码。在chrome://extensions/安装扩展后打开任意网页在侧边栏输入一句自然语言比如点击登录按钮即可看到执行效果 核心能力解析能力一基于截图的视觉定位元素定位只依赖截图不依赖 DOM 结构。这意味着右下角的蓝色提交按钮这样的描述可以直接成为定位依据配合aiAct执行交互、aiQuery提取结构化数据、aiAssert断言界面状态三个核心 API 覆盖绝大多数测试动作。更多方法名可以在 basics.mdx 中对照学习。能力二一套 API 跑遍多平台同一个 Agent 接口下切换的只是驱动目标浏览器用page/browser配置手机用android:/ios:配置电脑用computer配置HarmonyOS 同理。每个平台都配有 Playground 调试环境移动端界面如下各平台的设备环境准备adb 配置、iOS 证书等见 platforms/ 目录下的分平台指南。能力三Bridge 模式接管你正在用的浏览器这是辨识度很高的一项本地脚本可以附着到你当前登录状态、装好插件的真实 Chrome 上执行任务。脚本复用的是浏览器里现成的 cookies 和页面状态等于你手动登录脚本自动跑流程完整接入方式见 bridge-mode.mdx示例约十行代码就能连接新标签页并执行指令。 真实场景走查一条命令完成搜索并验证假设你想验证打开 Bing 搜索今日天气结果页确实展示天气信息。按 yaml-script-runner.mdx 的写法脚本bing-search.yaml只有几行page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息操作在终端执行midscene ./bing-search.yaml。结果命令行实时输出执行进度每步都附带截图和 AI 的理解过程结束后自动生成可视化报告失败时可以直接看到AI 当时看到了什么、为什么判断失败不用再去翻一堆 console 日志。把page:换成android:并填上adb devices里的设备号同一段流程就能驱动真机执行。 实用小贴士Node 版本别踩坑。CLI 底层会用到 Rspack 工具链旧版 Node 20 patch如 20.17.0会直接报Unsupported Node.js version先node -v确认再安装。.env放错目录是最常见的模型没配置假象。它跟随命令执行目录走与 YAML 文件位置无关调试变量加载逻辑可以加--dotenv-debug参数。扩展冲突有固定排查路径。若报Cannot access a chrome-extension:// URL of different extension通常是另一个扩展往页面注入了 iframe/script——从报错 URL 里找到扩展 ID在扩展管理页禁用它即可。模型配置写错一侧。Bridge 模式下模型环境变量要写在终端Node.js 侧而不是浏览器侧。以上问题与更多排查手段都收录在 faq.md 中遇到报错先查这里通常能省不少时间。写在最后Midscene.js 把 UI 测试的维护重心从追着选择器改挪到了用一句话描述预期上手路径就是装 CLI、配.env、写 YAML、跑报告。建议从 快速开始 读起再按需进入 Playwright 集成 或 YAML 脚本详解把第一份脚本跑通后跨平台扩展只是换配置行的事。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考