Midscene.js 使用指南如何用一句自然语言驱动跨平台 UI 自动化测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个 GUI Agent for E2E TestingGUI Agent 即会看界面并动手操作的 AI 智能体。你用自然语言描述每一步它靠一张界面截图理解页面然后在 Web、Android、iOS、HarmonyOS 和桌面端替你完成点击、输入与断言。最大亮点全程不写选择器同一句话跨平台直接复用。一、它是什么30 秒建立整体认知一句话定位Midscene 是纯视觉驱动的 UI 自动化测试框架输入是截图 一句自然语言输出是一次真实的界面操作。核心卖点纯视觉不依赖选择器传统方案靠 DOM网页的结构树或无障碍树定位结构一改脚本就挂Midscene 只看截图人能看到的元素它就能操作包括 canvas 和原生 App。跨平台同一套 APIWeb、Android、iOS、HarmonyOS、桌面端共用aiAct、aiQuery、aiAssert等接口。两种写法JS SDK 接入现有 Playwright/Vitest 测试套件或者用 YAML 脚本直接写流程。零代码先体验Chrome 扩展和各平台 Playground 让你不写代码就能验证指令效果。二、工作原理它是怎么做到的核心机制是一个截图 → 思考 → 执行的循环输入你的自然语言指令 当前界面截图。处理多模态大模型能看懂图片的大模型阅读截图把任务拆成原子操作序列并为每个操作在图上标出目标元素的包围盒。输出平台适配层把定位结果转成真实事件——Web 走 CDPChrome 远程调试协议、Android 走 ADB、iOS 走 WebDriverAgent执行后再截一张图循环直到目标达成。工程上核心引擎在 packages/core/模型调用、元素定位、Agent 逻辑都在packages/core/src/ai-model/与packages/core/src/agent/各平台包负责截图与输入的接入如 packages/web-integration/、packages/android/、packages/ios/。需要远程操控已有浏览器时还可以用 bridge 模式让本地脚本和浏览器双向通信实现位于 apps/chrome-extension/三、核心功能逐个看aiAct让 AI 自己规划整个流程价值多步骤、路径不确定的任务你只描述目标拆解交给模型。// 任务会被拆成搜索 → 点击 → 核对逐步执行 await agent.aiAct(搜索耳机把第一件商品加入购物车并确认购物车数量变为 1);收益不关心页面结构和步数目标说清楚就能跑。aiQuery / aiAssert读数据、断言用户看到的// 提取结构化数据 const products await agent.aiQuery({name: string, price: number}[], 页面中的商品); // 断言界面可见状态而不只是 DOM 节点存在 await agent.aiAssert(页面顶部显示导航栏);收益颜色、高亮、布局这些渲染态都能验证这是纯选择器方案做不到的。YAML 脚本把测试流程写成配置文件page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - aiAssert: 结果中展示了天气信息收益零测试框架流程即脚本适合快速验证关键用户路径。四、快速上手从零到跑起来环境要求Node.js 环境 一个有 UI 定位能力的多模态模型 API KeyQwen、Doubao-Seed、GLM-4.6V、Gemini、UI-TARS 等含可自部署的开源模型。三步跑通最小示例npm install midscene/web playwright --save-dev// demo.ts import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; const browser await chromium.launch(); const page await browser.newPage(); await page.goto(https://www.bing.com); const agent new PlaywrightAgent(page); await agent.aiAct(在搜索框中输入 Headphones 并回车); console.log(await agent.aiString(第一个结果的标题));运行前设置模型环境变量具体取值见 快速开始文档export MIDSCENE_MODEL_BASE_URL模型服务地址 export MIDSCENE_MODEL_API_KEY你的key export MIDSCENE_MODEL_NAME模型名 export MIDSCENE_MODEL_FAMILY模型族想先不碰代码安装 Chrome 扩展把模型配置粘贴进设置页即可在侧边栏直接输入指令体验再逐步迁移到 Agent API。五、进阶调优让效果更好的 3 个技巧技巧 1开启缓存砍掉重复的模型调用const agent new PlaywrightAgent(page, { cache: { id: my-task }, // 相同指令命中缓存时直接复用不再调模型 });为什么有效缓存存的是任务规划 元素 XPath 定位命中即跳过 AI 调用。官方文档中有真实案例执行耗时从 51 秒降到 28 秒。缓存文件落在./midscene_run/cache策略细节见 缓存文档。技巧 2难任务加 deepThink / deepLocateawait agent.aiAct(完成结账表单在下单前停止, { deepThink: true, // 规划与定位拆成独立模型调用 deepLocate: true, // 元素小、易混淆时多一轮精确定位 });为什么有效复杂任务里规划和定位分开调用能减少理解偏差代价是更多调用和延迟建议只在困难任务上开。技巧 3用 setAIActContext 补充业务背景// 后续所有 aiAct 都会带上这段背景知识 agent.setAIActContext(如果出现 Cookie 授权弹窗请先关闭。价格单位是美元。);为什么有效一句背景知识解决弹窗、歧义这类AI 卡壳点比把规则写进每条指令更省。六、选型参考适合谁、不适合谁适合多端覆盖同一流程要跑 Web、Android、桌面动态界面UI 频繁改版或含 canvas、自定义渲染断言真实呈现要验证颜色、布局、高亮而非节点存在不适合纯后端 API 测试没有界面可交互毫秒级延迟的实时系统多模态模型调用有固定耗时完全离线环境无法访问 AI 模型服务维度选择器方案无障碍树方案Midscene纯视觉无语义标记的元素难命中难命中可见即可操作原生 App / 跨域 iframe基本不支持部分支持支持UI 改版后维护成本高选择器失效中低只需指令语义不变断言视觉渲染状态不支持不支持支持单次操作成本低无需模型低无需模型需模型调用可用缓存摊薄七、总结 延伸资源Midscene 用读截图替代找元素用自然语言替代选择器让跨平台 UI 自动化测试的维护成本大幅下降。如果你的场景是动态界面、多端覆盖或断言真实呈现值得先花半小时跑通最小示例。指令语义写得越精确它表现越稳定。延伸资源快速开始配置模型、安装扩展、跑第一条指令基本概念aiAct、aiQuery、aiAssert 等 API 全解模型配置 与 缓存机制README.md项目概览、showcase 案例与社区入口想深入读源码可克隆仓库git clone https://gitcode.com/GitHub_Trending/mid/midscene【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考