Midscene.js 视觉驱动端到端测试终极指南：用自然语言搞定跨平台UI自动化

Midscene.js 视觉驱动端到端测试终极指南用自然语言搞定跨平台UI自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene如果你维护过一套传统的 UI 自动化测试大概率经历过这样的场景页面改了一个按钮的 class二十条用例同时报元素找不到想点一个纯图标的按钮翻遍 DOM 都找不到可用的选择器产品要求验证界面看起来是否正确可你的断言只能判断这个节点存不存在。这些痛点的根源在于传统方案依赖页面结构DOM 或无障碍树来定位元素而结构天生脆弱且不完整。Midscene.js 就是冲着这个问题来的。它是一个定位为GUI Agent for E2E Testing的开源 SDK核心思路只有一句话不再读结构只读截图。它让多模态模型直接看界面截图你用自然语言描述操作目标它来规划、定位和执行覆盖 Web、Android、iOS、HarmonyOS、桌面应用甚至canvas场景。下面这份指南将带你从零上手这套视觉驱动的自动化测试方案并讲清楚它和传统工具的本质区别。传统自动化测试的四大痛点你中了几个先别急着看方案我们把问题拆清楚。几乎所有基于选择器的自动化工具——包括一些宣称智能的 AI 测试工具——都绕不开这四个坑选择器地狱#app div.main .btn-primary[data-idx]这类表达式前端一重构就全线失效维护成本居高不下。看不见的无语义元素纯图标按钮、自定义渲染控件、canvas里的图形没有语义标注结构类工具根本无法触达。平台边界原生 App 没有 DOM跨域 iframe 结构不可见这些场景传统工具要么做不了要么要做大量桥接。验证不了视觉效果结构断言只能回答元素在不在回答不了颜色对不对、高亮有没有、布局歪不歪。Midscene.js 的答案是只要人眼能看到它就能定位。它从截图出发用自然语言驱动模型完成理解界面→规划动作→执行操作的完整链路。这不是对传统工具的修修补补而是换了一条赛道。与传统方案相比的三个关键差异如果你只记三点请记下面这三个输入不同自然语言取代选择器。aiAct(点击登录按钮)、aiAssert(错误提示显示为红色)写用例像在写测试计划而不是在写 DOM 查询。媒介不同截图取代 DOM 树。Midscene 把界面截图交给多模态模型处理因此它天然理解原生应用、iframe、canvas也能感知颜色、布局这类看起来是否正确的属性。边界不同一套 API 覆盖多端。Web 用 Playwright/Puppeteer移动端用 ADB、WebDriverAgent桌面端用原生控制能力但对开发者暴露的是同一套 Agent 接口学习一次到处复用。需要说明的是Midscene 在数据提取、页面理解类任务上依然可以按需引入 DOM 信息例如aiQuery传domIncluded但在最核心的元素定位环节它坚持纯视觉路线——这既是它的特色也是它准确性的来源。三分钟跑通第一个用例三个入口任你选Midscene 的上手路径非常灵活按场景分成三个入口你不需要全部掌握。入口一Chrome 扩展零代码体验推荐新手先试安装 Chrome 扩展后在设置里粘贴一段模型配置包含 Base URL、API Key、模型名称和MIDSCENE_MODEL_FAMILY四个环境变量打开任意网页在侧边栏输入一句自然语言即可规划并交互点击登录按钮提取结构化数据页面中的商品{name: string, price: number}[]检查界面页面顶部显示导航栏扩展会当场执行并给出结果。这一步的价值在于你可以在不写任何代码的情况下验证 Midscene 的定位效果和你的模型配置是否合适然后再决定是否引入工程化。入口二集成到 Playwright写第一个自动化脚本安装依赖后用十几行代码就能跑通搜索→提取→断言的完整流程npm install midscene/web playwright playwright/test tsx --save-devimport { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; const browser await chromium.launch({ headless: true }); const page await browser.newPage(); await page.goto(https://www.bing.com); const agent new PlaywrightAgent(page); // 自然语言描述操作目标 await agent.aiAct(type AI 101 in search box, hit Enter); // 提取结构化数据 const results await agent.aiQueryArray{ title: string; url: string }( 搜索结果的标题和链接{title: string, url: string}[], ); console.log(results); await agent.aiAssert(页面上展示了至少一条搜索结果); await browser.close();运行npx tsx demo.ts控制台会打印出结构化数据同时生成一份可回放的 HTML 报告——这一点后面还会细说。入口三YAML 脚本 CLI不写代码也能自动化如果只是想跑通几条关键路径连测试框架都可以省掉。Midscene 提供 YAML 格式的脚本和对应的命令行工具npm i -g midscene/cli# bing-search.yaml page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息midscene ./bing-search.yaml命令执行后会自动输出进度并生成可视化报告。注意 CLI 对 Node 版本有要求建议使用20.19、22.12或24。核心能力拆解从一句话操作到结构化数据掌握了入口我们再深入 Midscene 的 Agent API。它把能力分为三类各有各的适用场景。规划型交互aiActaiAct接收一个自然语言目标模型会自行观察界面、规划步骤、定位元素并执行直到任务完成。它适合多步骤、有分支、路径不确定的任务await agent.aiAct(搜索耳机将第一件商品加入购物车并确认购物车数量变为 1);它还能配合setAIActContext注入业务背景比如如果出现 Cookie 弹窗请先关闭这样所有后续操作都会带上这条上下文。即时交互一次只做一件事aiTap、aiInput、aiHover、aiScroll、aiLongPress等属于即时交互类每次定位一个元素、执行一个动作不负责规划多步骤。它们响应更快、token 消耗更少适合流程确定的场景await agent.aiTap(购物车中的结账按钮); await agent.aiInput(邮箱地址输入框, { value: userexample.com }); // 其他输入模式typeOnly 保留原内容追加、clear 仅清空界面理解只观察不操作aiAssert检查条件不满足则抛错、aiQuery提取结构化数据、aiBoolean/aiNumber/aiString返回标量结果await agent.aiAssert(购物车中有一件商品并且显示了小计金额); const items await agent.aiQuery Array{ name: string; price: number } (购物车中的商品{name: string, price: number}[]); // items 示例[{ name: 无线耳机, price: 99.9 }]两种编排方式怎么选Midscene 同时支持交给 Agent 规划aiAct和用 JavaScript 编排两种方式。官方给出的选择原则很实用默认用aiAct它根据最新界面状态动态决策天然适应页面变化流程明确且稳定时用 JavaScript 编排执行路径完全由你控制确定性更强当 JavaScript 编排越来越难维护或成功率持续下降时改回aiAct。一句话总结aiAct把怎么走交给模型JavaScript 编排把怎么走攥在自己手里两者互补而非互斥。一份脚本跑遍 Web、Android、iOS 与桌面Midscene 的多平台能力不是各自为政而是同一套语义、同一套脚本结构。YAML 脚本把目标环境和任务步骤分开描述切换平台只需改头部配置# Android驱动已连接 adb 的设备 android: deviceId: s4ey59 # 通过 adb devices 获取 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索按钮 - ai: 点击第一个搜索结果进入详情页 - ai: 点击 开始 按钮开始导航# iOS通过 WebDriverAgent 驱动 ios: wdaPort: 8100 tasks: - name: 修改系统设置 flow: - ai: 打开设置应用 - ai: 点击 显示与亮度 - ai: 开启 深色模式 - aiAssert: 深色模式已开启桌面端Windows/macOS/Linux同样支持底层通过原生键盘鼠标控制实现。值得单独一提的是Chrome 桥接模式Bridge Mode它允许你用本地脚本控制桌面版 Chrome复用浏览器里的 cookies、插件和登录状态相当于让自动化脚本和真人共用同一个浏览器环境import { AgentOverChromeBridge } from midscene/web/bridge-mode; const agent new AgentOverChromeBridge(); await agent.connectNewTabWithUrl(https://www.bing.com); await agent.ai(type AI 101 and hit Enter); await agent.aiAssert(there are some search results); await agent.destroy();这种人机协同的方式对需要登录态、验证码或真实插件的场景尤其好用。三个实战场景从电商到金融到跨平台一致性场景一电商购物全流程回归用 YAML 把搜索→进详情→加购→结算整条链路写成脚本作为每次发版前的冒烟用例。因为不再依赖选择器前端即使调整了布局和样式脚本也不需要改动page: url: https://example-shop.com tasks: - name: 购物主流程 flow: - ai: 在搜索框输入智能手机并搜索 - ai: 选择第一个商品进入详情页 - ai: 点击加入购物车按钮 - ai: 进入购物车页面并点击结算 - aiAssert: 订单确认页显示正确的商品信息和价格场景二金融应用的安全与异常路径用 JavaScript 编排可以精确控制分支逻辑非常适合输错密码三次→验证锁定提示这类确定性流程await agent.aiInput(密码输入框, { value: wrong-password }); await agent.aiTap(登录按钮); // 循环验证失败提示直到触发锁定 const locked await agent.aiBoolean(页面显示账户已锁定提示); console.log(lock verified:, locked);场景三跨平台一致性检查同一份测试意图分别在 Web、iOS、Android 上各跑一遍用aiAssert验证登录按钮位置一致、输入框占位符一致、错误提示样式一致把视觉层面的回归交给 Midscene人只需要看报告。常见问题与避坑要点把大家踩过的坑汇总成清单能帮你少走弯路模型配置四件套不能少MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_FAMILY。家族字段决定 Midscene 如何适配模型填错会导致定位异常。支持的模型包括 Qwen 系列、豆包 Seed 系列、GLM、Gemini 以及可自托管的开源模型 UI-TARS。CLI 与 Node 版本midscene/cli依赖较新的工具链老版本 Node 20 patch 会直接报错升级到20.19即可。元素定位不准先升级再看模型优先升级到最新版本其次考虑换成定位能力更强的模型小元素或易混淆元素可以用deepLocate增加一次定位调用复杂的多步任务可以用deepThink加强任务拆解。Chrome 扩展冲突报错Cannot access a chrome-extension:// URL通常是被其他扩展注入的 iframe/script 干扰去开发者工具里找出对应扩展 ID 并禁用即可。用 Ollama 本地模型遇到 403设置环境变量OLLAMA_ORIGINS*放行浏览器访问。数据隐私心里有数Midscene 默认把截图发送给模型只有aiAsk/aiQuery传domIncluded: true时才会带上 DOM。对隐私敏感的项目优先选择自托管的开源模型。运行产物去哪了报告、日志、缓存统一放在midscene_run目录可用MIDSCENE_RUN_DIR重定向其中report/是 HTML 报告cache/是调试缓存记得加入.gitignore。最佳实践与优化技巧想让 Midscene 跑得又快又稳这几个技巧值得收藏按场景选 API别什么都用aiAct确定性的单步操作用aiTap/aiInput这类即时交互接口速度更快、token 更省只有多步骤、带分支的任务才交给aiAct规划。适当降低截图分辨率分辨率越高图片 token 成本越高。在不影响定位的前提下用更低的截图尺寸可以显著降本。善用缓存加速调试配置cacheread-write等策略后重复执行相似步骤会命中缓存调试迭代效率大幅提升。用aiActContext注入领域知识弹窗处理、价格单位、默认收货地址这类隐性规则写进上下文后模型就不再反复试错。重视报告回放每次运行都会生成逐步可回放的可视化报告断言失败时先看报告定位到具体步骤比看日志高效得多。选模型有讲究官方在 Android Agent benchmarkAndroidWorld、MobileWorld上公开了各模型的实测成绩选型时可以参照这些数据一般原则是定位速度与准确性并重。未来展望与总结回到开篇的痛点选择器易碎、无语义元素不可达、原生应用难覆盖、视觉效果无法验证。Midscene.js 用纯视觉 自然语言把这些问题一次性绕了过去并且通过Chrome 扩展零代码体验 → Playwright 集成 → YAML 脚本 → 多平台统一 API这条渐进路径让不同背景的使用者都能找到合适的切入点。从项目定位看它先是面向 UI 测试但同一套视觉驱动引擎天然适用于更广泛的 UI 自动化任务配合 Skills 生态AI Agent 也能借助它自主操作界面未来在智能体落地、车载与物联网等场景还有更大的想象空间。如果你正被选择器维护和跨平台测试折磨下一步建议很明确先去 Chrome 扩展里体验一次自然语言驱动界面再花十分钟把 Playwright 集成跑通最后把你的核心业务路径改写成 YAML 脚本交给 CI。项目使用 MIT 协议仓库地址为 https://gitcode.com/GitHub_Trending/mid/midscene 克隆下来即可动手实验。视觉驱动的自动化时代已经来了这一次你的用例终于不用再追着前端重构跑了。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考