Midscene.js 完整指南：AI 视觉 UI 自动化工具，5 分钟跑通跨平台 E2E 测试

Midscene.js 完整指南AI 视觉 UI 自动化工具5 分钟跑通跨平台 E2E 测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个开源的 GUI Agent for E2E Testing它用 AI 视觉识别代替传统 DOM 选择器——只凭一张截图就能在 Web、Android、iOS、HarmonyOS 和桌面上执行 UI 自动化测试。本教程带你从零配置到真正跑起一段自然语言自动化脚本全程 5 分钟起步。它的思路很直接把屏幕截图交给多模态大模型模型看懂界面上有什么再按你写的人类语言指令去点击、输入、读取数据、校验结果。你不需要维护#login-btn这类选择器页面怎么重构只要人眼能认出按钮脚本就能继续工作。Midscene.js 是什么一个看屏幕的 UI 自动化引擎传统自动化工具依赖页面的 DOM 结构或无障碍树来定位元素这带来三个天然短板选择器一改就失效纯图标按钮、canvas 画布、原生 App、跨域 iframe 对它们隐形而且它们无法判断界面上看起来对不对只能确认某个节点存在。Midscene 换了一条路元素定位只基于截图。一套 API 覆盖所有平台核心动作就三类交互aiAct自主规划多步操作、aiTap/aiInput等即时操作观察aiQuery提取结构化数据、aiAssert断言界面状态平台无关Web、Android、iOS、HarmonyOS、桌面共用同一套语义驱动它的是具备 UI 定位能力的多模态模型官方支持 Qwen、Doubao-Seed、GLM、Gemini 系列也包括 UI-TARS、Qwen-VL 这类可自托管的开源模型。最快上手路径5 分钟跑通第一个 AI 自动化任务最短路线是 Chrome 扩展——它就是 Midscene 的 Web Playground不用建项目就能试核心能力。安装 Midscene 的 Chrome 扩展打开任意网页右侧会出现操作侧边栏在设置里粘贴模型配置API 地址、Key、模型名、模型系列完整配置项见模型配置文档在侧边栏输入自然语言指令比如Click the login button执行即可看到 AI 理解页面并完成动作验证完指令后就可以把同样的能力写进代码或 YAML 脚本进入正式自动化流程。如果想从命令行开始克隆仓库阅读源码与示例也是好选择git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene pnpm install这一步把项目拉到本地pnpm install安装全部工作区依赖之后可以随时阅读源码或直接构建各平台 SDK。能力拆解自然语言能驱动的四件事aiAct让 AI 自己规划多步操作aiAct接收一个自然语言目标它会持续观察最新界面、规划下一步、定位元素并执行直到目标完成。适合步骤多、有分支、路径不确定的任务。- ai: Search for todays weatherYAML 里的ai就是aiAct的简写AI 会自动拆解搜索天气背后的点击搜索框、输入关键词、提交等动作。aiQuery 与 aiAssert取数据、验界面- aiQuery: Products on the page, {name: string, price: number}[] - aiAssert: The results show weather information第一行让 AI 把页面上的商品读成结构化 JSON第二行断言结果区确实显示了天气信息不满足就报错。断言看的是渲染出来的画面所以颜色、高亮、布局这类用户真实所见也能校验。一套 API 打通 Web、Android、iOS、HarmonyOS 和桌面同一个tasks写法换掉开头的目标段就能切换平台。Android 示例需要 adb 连接设备android: deviceId: s4ey59 tasks: - name: Maps Navigation flow: - ai: Open the Maps app - ai: Click Start button to start navigationdeviceId换成adb devices里查到的设备号即可Android Playground 提供完整的预览界面iOS 走 WebDriverAgentios: wdaPort: 8100桌面端支持 Windows、macOS、Linuxcomputer: {}HarmonyOS 通过 HDC 连接各平台环境要求以平台入门文档为准。Bridge 模式把脚本接到你正在用的浏览器脚本默认启动无头浏览器但有时你需要复用已登录的 Cookie、插件和状态。装上 Chrome 扩展后在脚本里加一行bridgeModeYAML 脚本就会直接驱动桌面上真实运行的浏览器这也是日常调试最舒服的方式手动和脚本操作的是同一个浏览器。完整示例一条 YAML 脚本完成一次端到端冒烟测试把前面能力串起来就是一个真实的执行流程建脚本 → 配模型 → 跑命令 → 看报告。第 1 步写脚本bing-search.yamlpage: url: https://www.bing.com tasks: - name: Search for weather flow: - ai: Search for todays weather - sleep: 3000 - name: Check results flow: - aiAssert: The results show weather informationpage段声明操作目标tasks段按顺序执行先让 AI 搜天气等 3 秒再断言结果区出现了天气信息——一个最小但完整的 E2E 用例。第 2 步配置模型环境在项目目录放一个.envMIDSCENE_MODEL_BASE_URL你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY你的API Key MIDSCENE_MODEL_NAME模型名 MIDSCENE_MODEL_FAMILY模型系列CLI 通过 dotenv 自动加载这四个变量指向任何 OpenAI 兼容的多模态模型服务即可。第 3 步安装 CLI 并运行npm i -g midscene/cli midscene ./bing-search.yaml命令行实时打印执行进度结束后自动生成一份可视化 HTML 报告每一步的截图、耗时、断言结果都能回看。仓库里还有现成脚本可照着改内置测试脚本、YAML 脚本完整写法。批量跑脚本时支持 glob 通配和并发midscene ./scripts/**/*.yaml --concurrent 4 --retry 2失败的脚本会自动重试适合接入 CI。常见卡点新手最容易踩的三个坑坑一Node 版本过低直接报错。CLI 要求 Node.js20.19、22.12或24遇到Unsupported Node.js version先升级 Node而不是怀疑脚本。坑二扩展装上却报Cannot access a chrome-extension:// URL of different extension。这通常是另一个 Chrome 扩展向页面注入了脚本造成冲突打开开发者工具找到 URL 以chrome-extension://开头的 iframe 或 script按 ID 到chrome://extensions/禁用对应扩展即可。坑三脚本跑得慢误以为卡死。aiAct是自主规划模式每步都重新截图分析多步任务天然比aiTap、aiInput这类即时操作耗时耗 token。经验法则路径确定的单步操作用即时 API路径不确定的整段流程才交给aiAct目标元素小或容易和相邻元素混淆时加deepLocate: true提升定位精度。下一步与资源入口快速入门Chrome 扩展 全平台YAML 脚本写法与 CLI 参数详解核心概念aiAct / aiQuery / aiAssert 全解API 参考手册模型选择策略仓库内各平台源码web-integration、android、ios、computer、core 引擎适合谁做 E2E 测试的工程师、被选择器维护折磨的 QA、想快速验证AI 到底能不能操作 App的开发者以及需要在移动端、桌面端复用同一套测试逻辑的团队。从一条 YAML 开始试比读十页文档更有感觉。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考