Midscene.js 完整上手指南用自然语言驱动 E2E 自动化测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene回归一个搜索页时前端重构换了 class二十多行选择器一夜全红你只能挨个重新定位。Midscene.js 是面向 E2E 测试的视觉驱动 GUI Agent它看截图、听懂自然语言你说在搜索框输入耳机并搜索它自己找到搜索框、输入、点击再校验结果。从选择器地狱到一句话脚本Midscene 改写了哪些日常 本节回答一个实际问题哪些测试工作会因 Midscene 而变简单。Web 回归不再怕前端重构。传统 Playwright 脚本把选择器写死页面 class 一改整条用例失效CSS 和 XPath 越攒越多。Midscene 让你用自然语言描述页面顶部的搜索框它按截图的视觉特征定位元素页面 class 全部更换只要长相不变脚本通常照常工作。纯图标的按钮、canvas 绘制的内容、跨域 iframe 里的元素都不需要选择器或语义标注。一套 API 打通 Web 与移动端。传统做法里 Android 走 UIAutomator2、iOS 走 WebDriverAgent两套 API、两套元素描述各自维护。Midscene 在同一组 Agent API 下覆盖 Web、Android、iOS、HarmonyOS 和桌面端YAML 脚本里把目标段从page换成android指令本身一个字不用改。Midscene.js 快速上手 ⚡4 步跑通第一个 YAML 脚本本节给你最短路径从空环境到一条可运行、可查报告的 E2E 脚本。1. 装 CLI。需要 Node.js 20.19、22.12 或 24一条命令npm i -g midscene/cli。若报 Unsupported Node.js version先升级 Node。2. 配模型。在工具运行目录创建.env指向任一具备 UI 定位能力的多模态模型豆包 Seed、Qwen-VL、Gemini、GPT 等MIDSCENE_MODEL_BASE_URLhttps://your-model-service/v1 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAMEyour-model-name MIDSCENE_MODEL_FAMILYyour-model-family注意没有export前缀且.env必须放在工具运行目录、而非 YAML 所在目录。支持模型的完整清单见模型配置文档。3. 写脚本。新建bing-search.yamlpage: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息ai是aiAct的简写一句指令即可不用拆解点哪个框、输什么字。4. 运行并看报告。执行midscene ./bing-search.yaml终端实时打印进度结束后在midscene_run/report/生成 HTML 报告浏览器打开即可看到每步截图、AI 决策过程和断言结果。报告里点不开、断言莫名失败时先看对应步骤的截图基本能区分是没找到元素还是找到但点错。Midscene 核心用法指令、数据与桥接本节讲三个日常最高频的功能每个都给出价值 → 用法 → 例子。一句话驱动多步操作 它能帮你把登录、进设置、改主题这类多步流程压成一句目标Agent 自动拆解为点击、输入、滚动失败时自动重新规划。用法是在 task 的flow里直接写目标例如官方 Android 示例里的- ai: 在搜索栏输入 杭州西湖然后点击搜索按钮。复杂路径可拆成多句ai每句一个检查点报告回放时更容易定位断在哪一步。把页面变成数据和断言 aiQuery从页面直接抽结构化数据aiAssert用视觉判断屏幕是否长该长的样子。传统做法要 querySelector 加 JSON.parse 抓价格、expect 断言文本这里一句话描述结构和预期即可。- aiQuery: 搜索结果中的商品{title: string, price: number}[]返回可直接使用的数组- aiAssert: 界面左侧有类目筛选功能在界面不符时让任务失败并保留失败截图。给步骤加name字段结果会写入 JSON 输出方便下游脚本消费。桥接模式脚本接管你正在用的浏览器 需要登录态、依赖浏览器插件的内网系统无头脚本往往进不去。桥接模式通过 Chrome 扩展把本地脚本连上桌面 Chrome复用 cookies、插件和页面状态支持新建标签页或附着当前标签页。YAML 的page段加一个字段midscene命令即可驱动已有浏览器page: url: https://www.bing.com bridgeMode: newTabWithUrl脚本运行时扩展会弹确认窗点 Allow 后接管。newTabWithUrl新开标签页currentTab附着当前页注意userAgent、cookie等浏览器配置在桥接模式下会被忽略因为直接复用你本机的浏览器环境。进阶配置与常见报错排查本节解决两件事让脚本跑得更快更稳以及出问题时去哪里查。提速缓存 并发 缓存会保存 AI 规划结果与元素定位重复执行直接命中。官方示例中同一任务耗时从 51 秒降到 28 秒。YAML 里只需四行agent: cache: id: my-cache strategy: read-write缓存文件在midscene_run/cache/未命中会自动回退模型分析完整策略只读、只写、手动清理见缓存文档。多个互不依赖的脚本则交给 CLI 并发midscene ./scripts/search-*.yaml --concurrent 4 --continue-on-error --retry 2全部参数说明在脚本运行器文档。症状 → 排查思路 点击偏移、点到相邻元素先核对MIDSCENE_MODEL_FAMILY是否配错把提示词改成视觉描述加位置页面右上角的人形头像图标并给该步骤开deepLocate: true。下拉选项点不到原生select的选项由操作系统渲染不会出现在截图里。先查报告截图里是否真的没有选项Midscene 默认开启forceChromeSelectRendering强制 Chrome 渲染若你改过配置请恢复。截图超时报错含page.screenshot: Timeout ... waiting for fonts to load时是 Playwright 卡在字体加载CI 和容器环境常见export PW_TEST_SCREENSHOT_NO_FONTS_READY1后重跑即可。首次运行下载浏览器太慢Playwright 在npm install时默认不下载浏览器先单独执行npx playwright install --with-deps chromium或配置镜像加速。下一步Midscene.js 用截图 自然语言替代选择器 固定步骤把第一条可用 E2E 脚本的落地成本压到了半天以内。建议接下来做三件事用 CLI 跑一个真实页面把报告回放流程走一遍熟悉报告结构挑 2~3 条最高频的回归路径迁移成 YAML替换掉最脆弱的那批选择器开启缓存与并发执行对比耗时和模型调用次数再决定哪些任务纳入常规调度【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene.js 完整上手指南：用自然语言驱动 E2E 自动化测试
Midscene.js 完整上手指南用自然语言驱动 E2E 自动化测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene回归一个搜索页时前端重构换了 class二十多行选择器一夜全红你只能挨个重新定位。Midscene.js 是面向 E2E 测试的视觉驱动 GUI Agent它看截图、听懂自然语言你说在搜索框输入耳机并搜索它自己找到搜索框、输入、点击再校验结果。从选择器地狱到一句话脚本Midscene 改写了哪些日常 本节回答一个实际问题哪些测试工作会因 Midscene 而变简单。Web 回归不再怕前端重构。传统 Playwright 脚本把选择器写死页面 class 一改整条用例失效CSS 和 XPath 越攒越多。Midscene 让你用自然语言描述页面顶部的搜索框它按截图的视觉特征定位元素页面 class 全部更换只要长相不变脚本通常照常工作。纯图标的按钮、canvas 绘制的内容、跨域 iframe 里的元素都不需要选择器或语义标注。一套 API 打通 Web 与移动端。传统做法里 Android 走 UIAutomator2、iOS 走 WebDriverAgent两套 API、两套元素描述各自维护。Midscene 在同一组 Agent API 下覆盖 Web、Android、iOS、HarmonyOS 和桌面端YAML 脚本里把目标段从page换成android指令本身一个字不用改。Midscene.js 快速上手 ⚡4 步跑通第一个 YAML 脚本本节给你最短路径从空环境到一条可运行、可查报告的 E2E 脚本。1. 装 CLI。需要 Node.js 20.19、22.12 或 24一条命令npm i -g midscene/cli。若报 Unsupported Node.js version先升级 Node。2. 配模型。在工具运行目录创建.env指向任一具备 UI 定位能力的多模态模型豆包 Seed、Qwen-VL、Gemini、GPT 等MIDSCENE_MODEL_BASE_URLhttps://your-model-service/v1 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAMEyour-model-name MIDSCENE_MODEL_FAMILYyour-model-family注意没有export前缀且.env必须放在工具运行目录、而非 YAML 所在目录。支持模型的完整清单见模型配置文档。3. 写脚本。新建bing-search.yamlpage: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息ai是aiAct的简写一句指令即可不用拆解点哪个框、输什么字。4. 运行并看报告。执行midscene ./bing-search.yaml终端实时打印进度结束后在midscene_run/report/生成 HTML 报告浏览器打开即可看到每步截图、AI 决策过程和断言结果。报告里点不开、断言莫名失败时先看对应步骤的截图基本能区分是没找到元素还是找到但点错。Midscene 核心用法指令、数据与桥接本节讲三个日常最高频的功能每个都给出价值 → 用法 → 例子。一句话驱动多步操作 它能帮你把登录、进设置、改主题这类多步流程压成一句目标Agent 自动拆解为点击、输入、滚动失败时自动重新规划。用法是在 task 的flow里直接写目标例如官方 Android 示例里的- ai: 在搜索栏输入 杭州西湖然后点击搜索按钮。复杂路径可拆成多句ai每句一个检查点报告回放时更容易定位断在哪一步。把页面变成数据和断言 aiQuery从页面直接抽结构化数据aiAssert用视觉判断屏幕是否长该长的样子。传统做法要 querySelector 加 JSON.parse 抓价格、expect 断言文本这里一句话描述结构和预期即可。- aiQuery: 搜索结果中的商品{title: string, price: number}[]返回可直接使用的数组- aiAssert: 界面左侧有类目筛选功能在界面不符时让任务失败并保留失败截图。给步骤加name字段结果会写入 JSON 输出方便下游脚本消费。桥接模式脚本接管你正在用的浏览器 需要登录态、依赖浏览器插件的内网系统无头脚本往往进不去。桥接模式通过 Chrome 扩展把本地脚本连上桌面 Chrome复用 cookies、插件和页面状态支持新建标签页或附着当前标签页。YAML 的page段加一个字段midscene命令即可驱动已有浏览器page: url: https://www.bing.com bridgeMode: newTabWithUrl脚本运行时扩展会弹确认窗点 Allow 后接管。newTabWithUrl新开标签页currentTab附着当前页注意userAgent、cookie等浏览器配置在桥接模式下会被忽略因为直接复用你本机的浏览器环境。进阶配置与常见报错排查本节解决两件事让脚本跑得更快更稳以及出问题时去哪里查。提速缓存 并发 缓存会保存 AI 规划结果与元素定位重复执行直接命中。官方示例中同一任务耗时从 51 秒降到 28 秒。YAML 里只需四行agent: cache: id: my-cache strategy: read-write缓存文件在midscene_run/cache/未命中会自动回退模型分析完整策略只读、只写、手动清理见缓存文档。多个互不依赖的脚本则交给 CLI 并发midscene ./scripts/search-*.yaml --concurrent 4 --continue-on-error --retry 2全部参数说明在脚本运行器文档。症状 → 排查思路 点击偏移、点到相邻元素先核对MIDSCENE_MODEL_FAMILY是否配错把提示词改成视觉描述加位置页面右上角的人形头像图标并给该步骤开deepLocate: true。下拉选项点不到原生select的选项由操作系统渲染不会出现在截图里。先查报告截图里是否真的没有选项Midscene 默认开启forceChromeSelectRendering强制 Chrome 渲染若你改过配置请恢复。截图超时报错含page.screenshot: Timeout ... waiting for fonts to load时是 Playwright 卡在字体加载CI 和容器环境常见export PW_TEST_SCREENSHOT_NO_FONTS_READY1后重跑即可。首次运行下载浏览器太慢Playwright 在npm install时默认不下载浏览器先单独执行npx playwright install --with-deps chromium或配置镜像加速。下一步Midscene.js 用截图 自然语言替代选择器 固定步骤把第一条可用 E2E 脚本的落地成本压到了半天以内。建议接下来做三件事用 CLI 跑一个真实页面把报告回放流程走一遍熟悉报告结构挑 2~3 条最高频的回归路径迁移成 YAML替换掉最脆弱的那批选择器开启缓存与并发执行对比耗时和模型调用次数再决定哪些任务纳入常规调度【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考