Midscene.js 视觉 UI 自动化实战指南不写选择器用自然语言跑通 Web、Android 与 iOS 测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene提到 Midscene.js绕不开的核心词就是视觉 UI 自动化它是一个面向端到端测试的 GUI Agent靠屏幕截图加一句自然语言就能在网页、Android 真机、iOS 模拟器上完成点击、输入、数据提取和断言。这篇文章从选择器为什么总坏讲起带你看清视觉路线的取舍然后依次覆盖安装配置、两种指令模式、模型选型、跨端控制与报告调试最后用三个真实场景收尾。先看问题选择器为什么让你反复返工传统 UI 自动化脚本高度依赖页面结构#login-btn、.item-card:nth-child(3)这类定位串是脚本和界面之间最薄的那层膜。选择器维护的三笔账一次重构全线报红前端改个 class 名、调个 DOM 层级依赖选择器的脚本就要跟着改回归成本全花在追选择器上。看不见的元素脚本也点不到只有图标的按钮、自定义画布控件、canvas渲染的界面、原生 App 和跨域 iframe对读 DOM 或无障碍树的工具来说都是盲区。验证不了看起来对不对断言只能确认某个节点存在却回答不了高亮色渲染出来了吗、布局错位了吗这类用户真实感知的问题。视觉路线截图即接口Midscene.js 的做法是彻底放弃对页面结构的依赖只消费屏幕截图你在截图上描述点一下登录按钮模型负责把这句话落到具体像素坐标上。收益很直接——只要人眼能看见的东西脚本就能操作图标按钮、画布、原生控件一视同仁断言也可以基于渲染后的画面而不只是节点是否存在。GUI Agent 是什么把这类看截图、理解意图、执行操作的程序通常叫 GUI Agent。你可以把它理解为一个不知疲倦的远程操作员它不关心界面怎么实现只关心屏幕上现在长什么样、该做什么。这正是 packages/core/src/agent/agent.ts 里那套aiTap、aiType、aiQuery、aiAct方法的运行时载体。痛点讲清楚了接下来把它装起来。Midscene.js 安装与快速上手 方式一装核心包写脚本用 pnpm 或 npm 安装 Web 端核心包即可它对应仓库中的 packages/web-integration/ 模块npm install midscene/web如果想直接阅读源码或跑示例项目也可以克隆仓库git clone https://gitcode.com/GitHub_Trending/mid/midscene然后在根目录执行pnpm install。方式二Chrome 扩展零代码体验不想先写一行代码的话安装仓库里的 Chrome 扩展源码位于 apps/chrome-extension/是最快的路径装好扩展、按引导配置好模型直接在当前打开的网页上用自然语言下指令AI 就会替你操作页面。适合先建立视觉定位到底靠不靠谱的直观感受。跑通第一段脚本确定扩展的体验符合预期后把同样的交互搬进代码。下面是完整的 Web 自动化最小示例import { createWebAgent } from midscene/web const agent await createWebAgent({ model: qwen3-vl }) await agent.goto(https://example.com) await agent.aiTap(搜索框) await agent.aiType(Midscene.js 自动化教程, 搜索输入框) const results await agent.aiQuery(搜索结果列表包含标题和描述)aiTap点击、aiType输入、aiQuery提取结构化数据——整个流程没有出现一个选择器。跑通脚本只是起点真正决定脚本好坏的是指令的组织方式。两种自动化模式一次规划 vs 逐步组合aiAct让模型自主规划完整流程把一段多步任务整句交给aiAct由模型自己拆解、自己执行、自己处理中间状态await agent.aiAct(点击列表中的每条记录如果记录包含已完成则跳过)适合流程相对线性、允许模型自由发挥的任务代码量最少。逐步组合把控制流拿回自己手里复杂业务里你往往想自己掌控分支和循环此时用aiQuery、aiBoolean这类原子动作手动编排const records await agent.aiQuery(记录列表字符串数组) for (const record of records) { const done await agent.aiBoolean(检查记录${record}是否包含已完成) if (!done) await agent.aiTap(record) }aiQuery负责把画面内容变成程序可用的数据aiBoolean负责问一个是/否问题两者配合就能写出任何 if/for 逻辑。此外还有aiAssert做视觉断言、aiWaitFor等待条件成立完整方法签名见 API 参考文档。怎么选一句话流程简单用aiAct图省事需要精确控制、复用和测试断言就用逐步组合。两种方式可以在同一个 Agent 里混用先规划后校验也是常见搭配。指令怎么组织之外还有一件直接影响成本和速度的事模型怎么选。Midscene.js 视觉模型配置与选型支持的模型清单Midscene.js 定位元素只看截图因此对模型的要求是UI 定位能力强。官方支持的视觉语言模型包括 Qwen3-VL开源、可自托管适合控制成本、UI-TARS字节开源、专为 UI 自动化优化、Doubao 系列视觉模型和 Gemini 系列闭源模型。需要说明的是虽然动作定位走纯视觉但在数据提取和页面理解环节你也可以按需选择让 DOM 信息一并参与提升结构化抽取的稳定性。用环境变量完成配置模型名、API Key、Base URL 等参数都走环境变量如MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_API_KEY解析逻辑在 packages/shared/src/env/ 中实现。好处是同一套脚本在 CI 和本地之间切换模型只改配置不改代码本地部署自托管模型时把 Base URL 指向自己的推理服务即可。缓存机制重复执行不再重复花钱视觉模型的每次调用都有真金白银的开销Midscene.js 内置了缓存开关MIDSCENE_CACHE环境变量控制相同指令、相同页面状态下可以直接命中缓存、跳过模型调用批量跑同类页面时提速和省钱都很明显。模型和成本理顺之后看看同一套 API 能管住多少平台。Midscene.js 跨端控制方法Web、Android、iOSWebPlaywright / Puppeteer 双集成Web 端提供两条集成路线在 packages/web-integration/src/playwright/ 中把 Midscene 以 fixture 形式挂进现有 Playwright 测试套件Puppeteer 集成则位于 packages/web-integration/src/puppeteer/。另有一条 Bridge 模式不新起无头浏览器而是直接接管你桌面上已登录、已登录态齐全的 Chrome 实例本地终端里的脚本操作的就是眼前这个窗口。Android一条 API 打到底通过midscene/android源码在 packages/android/src/控制真机或模拟器底层走 ADB 与 scrcpy 投屏。除了通用的aiTap、aiType还提供launchApp直接拉起指定包名的应用、aiScrollTo滚动寻找目标import { createAndroidAgent } from midscene/android const agent await createAndroidAgent({ deviceId: your-device-id }) await agent.launchApp(com.example.app) await agent.aiTap(设置图标) await agent.aiScrollTo(关于手机)仓库还配套了 Android Playground可以在浏览器里投屏真机、手动点按和下发 AI 指令调试链路非常直观。iOS 与 HarmonyOSiOS 端由 packages/ios/src/ 承载支持模拟器与真机基于 WebDriverAgentaiTap、aiType等接口与 Web 端完全一致迁移脚本几乎零成本HarmonyOS 则由 packages/harmony/ 提供同类能力。也就是说一套ai*方法签名横跨 Web、Android、iOS、HarmonyOS切换平台只换创建 Agent 的那一行。平台能力齐了剩下的问题是任务跑完之后我怎么知道它当时到底干了什么报告与调试每一步都有据可查可视化执行报告每次运行Midscene.js 都会生成一份自包含的 HTML 报告每一步的截图、下发的自然语言指令、模型返回的定位坐标、耗时全部按时间轴排列。定位偶发失败时不用再猜直接翻到那一步看当时的画面。报告页面本身是一个独立应用组件位于 apps/report/src/components/包含时间轴交互、步骤详情面板和实时预览等模块。Playground浏览器里的交互式试验场调试阶段更顺手的是 Playground入口代码见 apps/playground/src/App.tsx左侧输入一句指令右侧实时看到 Agent 在当前页面上的操作点击、查询、断言都可以反复试。它相当于把写脚本—跑测试—看报告的循环压缩成了输一句话—看结果找 prompt 的最佳措辞时效率最高。工具链齐备下面用三个贴近日常的例子检验一下这套东西的成色。场景验证表单批量处理、内容巡检与价格监控场景一表单批量处理运营后台要逐条处理几百条待办表单。用逐步组合模式aiQuery拉出待办列表循环里aiBoolean判断状态、aiTap操作、aiType填写备注最后用aiAssert确认每条都出现处理成功提示——整个过程不需要针对表单控件写任何选择器后台改版也无需改脚本。场景二内容巡检把一组关键页面首页、活动页、商品页交给脚本依次访问每页一句aiAssert页面没有白屏、没有报错弹窗、价格区域渲染正常。巡检脚本关注的是用户看见的东西这恰恰是读 DOM 的传统断言最难覆盖的部分。场景三竞品价格监控周期性打开竞品列表页提取结构化快照与上次结果比对const snapshot await agent.aiQuery(当前商品列表包含名称、价格、促销标签) const changed await agent.aiBoolean(与上次快照相比是否有商品价格上涨) await agent.aiAssert(列表页无空白卡片或加载失败占位图)aiQuery返回的结构化数据直接进你的数据库或告警管道aiBoolean负责回答业务层面的有没有变化异常时再aiAssert留存现场。三个场景跑熟之后可以把 Midscene.js 的能力边界再往外推一推。进阶生态MCP、自定义技能与提取器MCP 连接任意上层智能体Midscene.js 的原子操作定位、点击、查询、断言可以封装为 MCPModel Context Protocol一种让外部程序调用工具的标准协议工具暴露出去。接上之后编码助手、工作流编排器这类上层 Agent 不必自己懂 UI用自然语言就能驱动 Midscene 操作界面适合把查一下这个页面上写了什么这类子任务委托出去。Agent 工具层的实现见 packages/shared/src/agent-tools/。注册自定义技能packages/core/src/skill/ 提供了技能注册入口把你反复使用的组合逻辑比如登录后进入指定频道封装成一个命名技能脚本里按名字调用即可既减少重复代码也方便团队共享。提取器模块扩展动作定位走纯视觉但数据提取环节可以选择让 DOM 参与。packages/shared/src/extractor/ 中的web-extractor及相关工具负责把页面结构整理成模型可消费的形态当你发现纯截图抽取某类表格不够稳时可以从这里入手调整提取策略。执行过程的日志则统一走 packages/shared/src/logger.ts 输出方便排查偶发问题。下一步建议今天就动手装好 Chrome 扩展挑一个你最熟悉的内部系统用一句话让它帮你完成一次登录——五分钟就能建立对视觉定位的直觉。继续深入阅读 apps/site/docs/ 下的官方文档快速入门、Playwright/Puppeteer 集成、Android/iOS/HarmonyOS 平台指南和 API 参考都有独立章节仓库根目录的 README.zh.md 也汇总了展示案例和社区项目索引。加入社区有使用问题或踩坑经验可以通过项目 Discord 社区交流也可以在仓库提 Issue——报告格式的改进、新平台支持这类需求都在这里排期。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考