拓冰网站定制 
用 Midscene.js 跑通视觉 UI 自动化测试一份从零上手的完整指南【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene给一个界面天天在变的 App 写回归测试你可能经历过这种事发布前一天前端重构了一批类名两百条用例里有六十条在选择器上挂掉。Midscene.js 走的是另一条路——它让多模态大模型直接看截图来定位元素、执行操作你用自然语言写测试步骤不需要维护任何选择器。这是一套面向 E2E 场景的 GUI Agent 工具链覆盖 Web、Android、iOS、HarmonyOS 和桌面端适合正在被 UI 自动化维护成本困扰的测试工程师和开发者。三步跑通第一个视觉脚本装好 CLI先确认终端里 Node.js 是 20.19 以上、22.12 以上或 24 以上CLI 部分执行路径依赖的构建工具链会拒绝更旧的版本。然后全局安装npm i -g midscene/cli配好模型在运行目录放一个.env文件dotenv 约定不写export填入你的多模态模型配置MIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY你的API密钥 MIDSCENE_MODEL_NAME模型名称 MIDSCENE_MODEL_FAMILY模型系列注意.env必须放在工具运行目录下跟 YAML 文件在哪没关系。跑第一个脚本新建bing-search.yaml内容只有几行page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息执行midscene ./bing-search.yaml命令行实时输出进度结束后在输出目录生成 JSON 结果和 HTML 可视化报告。一张截图能替代多少选择器把 Midscene.js 想象成一个视觉测试员你递给他一张屏幕截图和一句点击登录按钮他扫一眼图就找到位置点下去全程不需要知道按钮的 class 叫什么。这就是纯视觉驱动的含义——元素定位只依赖截图DOM 结构和可访问性树完全不参与。为什么坚持这么做因为很多真实元素根本看不见在结构里没有语义标记的纯图标按钮、canvas 画出来的界面、跨域 iframe 里的内容对传统 DOM 方案都是盲区而对一张截图来说统统平等。另一个直接好处是测试语义变了断言验证的是用户实际看到的画面——颜色、高亮、布局而不只是某个 DOM 节点存在。看懂架构从模型调用到平台适配源码分几层各管各的事核心层packages/core/src/agent/目录是规划与执行的主脑ai-model/负责多模态模型的接入与解析。平台适配层packages/web-integration/Playwright、Puppeteer、packages/android/ADB scrcpy 投屏、packages/ios/WebDriverAgent、packages/computer/桌面键鼠与截图。CLI 层packages/cli/负责加载.env、批量执行 YAML、汇总结果与生成报告。可视化层apps/playground/、apps/report/、apps/studio/浏览器侧边栏、报告页面和桌面应用。写用例时你只接触最上面两层一段 YAML 或几个 Agent API 调用底下怎么切图、怎么问模型、怎么落到手指或鼠标不用关心。实测三种最常用的操作aiAct/ai规划执行、aiQuery结构化提取、aiAssert断言是日常用例的三板斧。用自然语言驱动点击和输入前面 Bing 的例子就是最小组合。同一个 YAML 结构换个开头就能切到真机比如 Androidandroid: deviceId: s4ey59 # adb devices 可查 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索按钮 - aiAssert: 显示了西湖的路线规划页面iOS 把开头的android:换成ios:配wdaPort即可任务主体一字不动。让模型吐出结构化数据aiQuery可以带类型声明返回的 JSON 直接进断言或落库。在 Playwright 项目里const agent new PlaywrightAgent(page); const items await agent.aiQuery( {itemTitle: string, price: number}[], 找出列表里的商品和价格, ); await agent.aiAssert(列表第一件商品显示在库存);注意点是描述里尽量给出字段和范围的约束模型返回的结构会更稳。断言验证用户看到的东西aiAssert是视觉断言适合验证高亮、颜色、布局这类看起来对不对的状态这些用 DOM 断言很难覆盖。调试时建议加--headed打开浏览器窗口或--keep-window结束后保留窗口肉眼对照执行过程比只看报告快得多。压低维护成本的两个常用手段问题重复执行太费模型调用怎么办做法给任务加缓存标识agent: { cache: { id: my-cache } }。相同的规划指令和元素定位会命中缓存、跳过模型调用官方文档里的实测案例执行耗时从 51 秒降到 28 秒。缓存文件落在./midscene_run/cache失效时自动回退到重新分析不会卡死查询类操作aiQuery、aiAssert等永远走实时结果不会被缓存。问题想把 Midscene.js 塞进现有 Playwright 项目做法把现有page对象直接交给PlaywrightAgent测试文件里的其余断言照旧写。集成细节见 集成 Playwright 文档。批量跑脚本则用通配符midscene ./scripts/**/*.yaml每个脚本各自生成报告另有汇总的 JSON 结果。四个高频问题快速排查现象装完 CLI 一运行就报 RspackUnsupported Node.js version。原因Node 版本低于 20.19。解法升级 Node 后重装全局 CLI。现象脚本报模型未配置明明.env里写了。原因.env放错了目录。解法它必须在工具运行目录下与 YAML 所在目录无关也可以用全局环境变量替代。现象结果忽对忽错像是用了旧数据。原因上次运行留下的规划或定位缓存命中了过期状态。解法调试期配cache: false或删掉./midscene_run/cache重来。现象Chrome 扩展里调 Ollama 本地模型报 403。原因浏览器侧请求被拦截。解法设置环境变量OLLAMA_ORIGINS*再重启浏览器。和传统方案放在一起对比选择器/DOM 方案Midscene.js 视觉方案界面重构后批量改选择器截图仍可读则照常通过纯图标按钮、canvas结构里定位不到截图里看得见就能点跨域 iframe基本不可达截图无跨域问题验证渲染效果只能验证节点存在能断言颜色、高亮、布局下一步Midscene.js 把找到元素这件事从代码搬到了模型里维护成本随之从选择器转移到了自然语言描述上而后者显然更接近界面本身。如果还想往下走克隆仓库 https://gitcode.com/GitHub_Trending/mid/midscene 跑一遍示例或先读 基本概念文档 把aiAct、aiQuery、aiAssert的边界弄透再挑一个现有用例试着用截图重写。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 Midscene.js 跑通视觉 UI 自动化测试：一份从零上手的完整指南
用 Midscene.js 跑通视觉 UI 自动化测试一份从零上手的完整指南【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene给一个界面天天在变的 App 写回归测试你可能经历过这种事发布前一天前端重构了一批类名两百条用例里有六十条在选择器上挂掉。Midscene.js 走的是另一条路——它让多模态大模型直接看截图来定位元素、执行操作你用自然语言写测试步骤不需要维护任何选择器。这是一套面向 E2E 场景的 GUI Agent 工具链覆盖 Web、Android、iOS、HarmonyOS 和桌面端适合正在被 UI 自动化维护成本困扰的测试工程师和开发者。三步跑通第一个视觉脚本装好 CLI先确认终端里 Node.js 是 20.19 以上、22.12 以上或 24 以上CLI 部分执行路径依赖的构建工具链会拒绝更旧的版本。然后全局安装npm i -g midscene/cli配好模型在运行目录放一个.env文件dotenv 约定不写export填入你的多模态模型配置MIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY你的API密钥 MIDSCENE_MODEL_NAME模型名称 MIDSCENE_MODEL_FAMILY模型系列注意.env必须放在工具运行目录下跟 YAML 文件在哪没关系。跑第一个脚本新建bing-search.yaml内容只有几行page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息执行midscene ./bing-search.yaml命令行实时输出进度结束后在输出目录生成 JSON 结果和 HTML 可视化报告。一张截图能替代多少选择器把 Midscene.js 想象成一个视觉测试员你递给他一张屏幕截图和一句点击登录按钮他扫一眼图就找到位置点下去全程不需要知道按钮的 class 叫什么。这就是纯视觉驱动的含义——元素定位只依赖截图DOM 结构和可访问性树完全不参与。为什么坚持这么做因为很多真实元素根本看不见在结构里没有语义标记的纯图标按钮、canvas 画出来的界面、跨域 iframe 里的内容对传统 DOM 方案都是盲区而对一张截图来说统统平等。另一个直接好处是测试语义变了断言验证的是用户实际看到的画面——颜色、高亮、布局而不只是某个 DOM 节点存在。看懂架构从模型调用到平台适配源码分几层各管各的事核心层packages/core/src/agent/目录是规划与执行的主脑ai-model/负责多模态模型的接入与解析。平台适配层packages/web-integration/Playwright、Puppeteer、packages/android/ADB scrcpy 投屏、packages/ios/WebDriverAgent、packages/computer/桌面键鼠与截图。CLI 层packages/cli/负责加载.env、批量执行 YAML、汇总结果与生成报告。可视化层apps/playground/、apps/report/、apps/studio/浏览器侧边栏、报告页面和桌面应用。写用例时你只接触最上面两层一段 YAML 或几个 Agent API 调用底下怎么切图、怎么问模型、怎么落到手指或鼠标不用关心。实测三种最常用的操作aiAct/ai规划执行、aiQuery结构化提取、aiAssert断言是日常用例的三板斧。用自然语言驱动点击和输入前面 Bing 的例子就是最小组合。同一个 YAML 结构换个开头就能切到真机比如 Androidandroid: deviceId: s4ey59 # adb devices 可查 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索按钮 - aiAssert: 显示了西湖的路线规划页面iOS 把开头的android:换成ios:配wdaPort即可任务主体一字不动。让模型吐出结构化数据aiQuery可以带类型声明返回的 JSON 直接进断言或落库。在 Playwright 项目里const agent new PlaywrightAgent(page); const items await agent.aiQuery( {itemTitle: string, price: number}[], 找出列表里的商品和价格, ); await agent.aiAssert(列表第一件商品显示在库存);注意点是描述里尽量给出字段和范围的约束模型返回的结构会更稳。断言验证用户看到的东西aiAssert是视觉断言适合验证高亮、颜色、布局这类看起来对不对的状态这些用 DOM 断言很难覆盖。调试时建议加--headed打开浏览器窗口或--keep-window结束后保留窗口肉眼对照执行过程比只看报告快得多。压低维护成本的两个常用手段问题重复执行太费模型调用怎么办做法给任务加缓存标识agent: { cache: { id: my-cache } }。相同的规划指令和元素定位会命中缓存、跳过模型调用官方文档里的实测案例执行耗时从 51 秒降到 28 秒。缓存文件落在./midscene_run/cache失效时自动回退到重新分析不会卡死查询类操作aiQuery、aiAssert等永远走实时结果不会被缓存。问题想把 Midscene.js 塞进现有 Playwright 项目做法把现有page对象直接交给PlaywrightAgent测试文件里的其余断言照旧写。集成细节见 集成 Playwright 文档。批量跑脚本则用通配符midscene ./scripts/**/*.yaml每个脚本各自生成报告另有汇总的 JSON 结果。四个高频问题快速排查现象装完 CLI 一运行就报 RspackUnsupported Node.js version。原因Node 版本低于 20.19。解法升级 Node 后重装全局 CLI。现象脚本报模型未配置明明.env里写了。原因.env放错了目录。解法它必须在工具运行目录下与 YAML 所在目录无关也可以用全局环境变量替代。现象结果忽对忽错像是用了旧数据。原因上次运行留下的规划或定位缓存命中了过期状态。解法调试期配cache: false或删掉./midscene_run/cache重来。现象Chrome 扩展里调 Ollama 本地模型报 403。原因浏览器侧请求被拦截。解法设置环境变量OLLAMA_ORIGINS*再重启浏览器。和传统方案放在一起对比选择器/DOM 方案Midscene.js 视觉方案界面重构后批量改选择器截图仍可读则照常通过纯图标按钮、canvas结构里定位不到截图里看得见就能点跨域 iframe基本不可达截图无跨域问题验证渲染效果只能验证节点存在能断言颜色、高亮、布局下一步Midscene.js 把找到元素这件事从代码搬到了模型里维护成本随之从选择器转移到了自然语言描述上而后者显然更接近界面本身。如果还想往下走克隆仓库 https://gitcode.com/GitHub_Trending/mid/midscene 跑一遍示例或先读 基本概念文档 把aiAct、aiQuery、aiAssert的边界弄透再挑一个现有用例试着用截图重写。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考