Midscene.js 上手指南10 分钟用自然语言驱动跨端 GUI 自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene给一个电商后台写回归测试时最磨人的往往不是断言而是用例里那串改一次 UI 就断一次的 CSS 选择器。Midscene.js 是字节跳出的 GUI 自动化框架GUI Agent for E2E Testing它只依赖截图和自然语言用视觉 AI 定位并操作界面Web、Android、iOS、HarmonyOS 和桌面应用共用一套 API。它到底能帮你做什么回归用例不再追着选择器跑。传统浏览器自动化脚本里button.login-btn这类定位一改版就全挂Midscene 里你写点击顶部导航栏右侧的购物车图标DOM 结构怎么变都无所谓只要页面长得还是那个样子。没有 DOM 语义的界面也能碰。只有图标的按钮、canvas画的应用、跨域 iframe 里的控件Playwright 选择器根本够不着但人眼看得见的东西它都能定位——因为整个决策链路只看截图。能验证用户实际看到的样子。aiAssert可以断言颜色、高亮、布局这类视觉状态而不只是某个节点存在。比如验证搜索结果第一行有价格标签这种描述。顺带说一句Web、Android、iOS、HarmonyOS、桌面共用同一套 API同一段流程不用为每个平台重写。下面是 Android Playground 的界面左侧是自然语言指令区右侧 Device 面板展示设备信息场景看明白了接下来装个依赖就能动手。10 分钟跑通第一个浏览器自动化脚本第 1 步装依赖。在任意 Node 项目里执行npm install midscene/web playwright playwright/test tsx --save-dev npx playwright install第 2 步配模型环境变量。Midscene 需要一个有 UI 定位能力的多模态模型官方文档以火山引擎豆包 Seed 2.1 为例其他模型见 模型配置export MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 export MIDSCENE_MODEL_API_KEYyour-api-key export MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 export MIDSCENE_MODEL_FAMILYdoubao-seed第 3 步写最小脚本。保存为demo.tsimport { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; const browser await chromium.launch({ headless: false }); const page await browser.newPage(); await page.setViewportSize({ width: 1280, height: 768 }); await page.goto(https://www.bing.com); await page.waitForLoadState(networkidle); const agent new PlaywrightAgent(page); await agent.aiTap(页面顶部的搜索框); await agent.aiInput(页面顶部的搜索框, { value: 今日天气 }); await agent.aiTap(搜索按钮); const items await agent.aiQuery({name: string, price: number}[], 页面中的商品); console.log(items); await browser.close();第 4 步跑起来。执行npx tsx demo.ts浏览器会自己打开、输入、点击。跑完后控制台打印Midscene - report file updated: ...指向midscene_run/report/下的 HTML 报告每步操作的截图和元素标注都在里面直接丢给同事就能回放整个执行过程。脚本跑通了日常写用例其实就绕不开三个方法。三个最常用的高频 APIaiTap——描述元素点击它。await agent.aiTap(购物车中的结账按钮);先定位再点击元素只要长那样就行不用关心它在哪个 div 里。aiQuery——从界面里提取结构化数据。const items await agent.aiQueryArray{ name: string; price: number }( 购物车中的商品{name: string, price: number}[] );在提示词里用 TypeScript 类型把期望结构说清楚返回的就是类型化数组可以直接拿来断言。aiAssert——用自然语言检查界面状态。await agent.aiAssert(购物车中有一件商品并且页面显示了小计金额);条件不成立时抛错错误信息里带模型给出的失败原因报告里能看到购物车数量应为 1这种失败描述比断言选择器好维护得多。API 之外跑脚本前有几类报错新手几乎都会碰上一次。这些坑提前知道现象点击位置偏了或者每次点的位置都不一样。原因提示词只写了功能描述模型不知道那个图标长什么样aiTap(个人中心)就是典型。解决改成位置 视觉特征的描述如页面右上角的人形头像图标元素很小或容易混淆时调用加{ deepLocate: true }多跑一轮定位。现象Chrome 插件模式报错Cannot access a chrome-extension:// URL of different extension。原因另一个扩展向页面注入了 iframe 或 script跟 Midscene 冲突。解决开发者工具里找到以chrome-extension://开头的标签复制 ID 到chrome://extensions禁用对应扩展再刷新重试。现象aiAct执行又慢又烧 token。原因aiAct是多轮观察—规划—执行的自主模式天然比单步操作贵。解决步骤确定的单步操作改用aiTap、aiInput这类即时 API速度差很多调试阶段再开缓存避免重复调模型。坑绕开了最后说说它适合放在什么位置。适合谁什么时候别用选择器维护成本高、UI 迭代快的项目是它的主场能直接省掉改选择器的时间。需要同时覆盖 Web 和 Android/iOS或测试对象里有 canvas、跨域 iframe、原生 App传统方案够不着的地方一套 API 能打通。反过来高频批量、单次成本和延迟极度敏感的场景别用每次跑几千次、每次都点同一个固定位置的采集任务直接写 Playwright 选择器更便宜也更稳。纯数据抓取同理aiQuery方便但速度和 token 成本都明显高于选择器加解析结构化数据还是传统方案划算。知道边界之后按下面顺序看文档最省时间。从这开始快速开始Chrome 插件带你零代码跑通第一条指令三个 API 的界面效果直接可见。集成到 Playwright把 Agent 接进现有测试项目的完整步骤从装依赖到看报告。常见问题模型配置、定位偏移的排查步骤都在这配模型或点不准时先翻一遍。建议先在插件里拿手边的管理页面跑三条自然语言指令试水顺手了再写进脚本。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
