Midscene三步跑通视觉驱动 UI 自动化面向 E2E 测试的 GUI Agent 保姆级上手【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene 是一个面向 E2E 测试的 GUI Agent用视觉理解来操控界面的程序你用自然语言描述操作目标它看屏幕定位元素并自动点击、输入、校验覆盖 Web、Android、iOS 和桌面端。本文先带你跑通第一个视觉驱动测试再讲清原理最后给出两招省时省钱的调优做法。脚本跑到一半找不到按钮你可能踩了这些坑如果你做过 UI 自动化大概被两种失败折磨过选择器写死成#login-btn .submit某天前端重命名了类名脚本凌晨在 CI 上集体报element not found。坐标在 1920×1080 上调好换个窗口尺寸或显示器分辨率一半点击全偏了。问题的根源是元素在哪和元素长什么样被绑在了一起。Midscene 的思路不一样它不要选择器要截图。你用自然语言描述任务由多模态模型看屏幕判断该点哪里、输入什么。三步跑通第一个视觉自动化脚本 第一步准备环境上手走的是官方 CLI不需要克隆源码仓库。前提只有两个# 检查 Node 版本需要 20.19 / 22.12 / 24 node -v # 全局安装 Midscene 命令行工具 npm i -g midscene/cli 如果终端里看到Unsupported Node.js version先把 Node 升到上面的版本再重试。然后准备模型。Midscene 自身不内置模型需要你自己提供一个有视觉定位能力的多模态模型。以官方文档示例的豆包 Seed 2.1 Turbo 为例在运行命令的目录下建一个.env填入配置# .env注意没有 export 前缀这是 dotenv 的约定 MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 MIDSCENE_MODEL_FAMILYdoubao-seed如果你用 Qwen、GLM、Gemini 等模型变量名不变只换取值具体以模型配置文档为准。 第二步写脚本新建bing-search.yaml整个打开页面 → 搜索 → 断言流程就是三句自然语言page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息 第三步运行并查看报告# --headed 会打开浏览器窗口方便观察操作过程 midscene ./bing-search.yaml --headed 预期现象命令行滚动输出执行进度结束后生成一份 HTML 报告。打开它能逐帧回放 Agent 点了哪里、每一步看到什么、断言是否通过。若报 401/403先查 API Key若提示扩展冲突先禁用其他 Chrome 插件再试。跑通之后为什么换界面它也不会挂像个会看屏幕的新同事为什么截图就能干活打个比方。这像雇了一个会看屏幕的新同事。你只说搜一下今天的天气他不看 DOM而是看画面先规划步骤打开搜索框 → 输入 → 回车执行时再定位搜索框在屏幕的哪个位置点完还要校验结果对不对。Midscene 做的正是这套循环截图 → 模型规划步骤 → 定位目标元素的坐标 → 调浏览器或设备接口执行点击、输入 → 再截图验证。全程不依赖选择器所以纯图标按钮、自定义控件、canvas、跨域 iframe 里的东西都能点到。下图左侧就是 Android 场景下的真实决策链每一步都经过 Planning → Insight/Locate → Action/Tap 三种状态执行到哪一步一目了然。官方公开的基准成绩可以给个参考AndroidWorld Pass1 93.1%、MobileWorld 78.6%、AppControlBench 96.7%各自对应不同评测模型。记住一句话就够了界面越常改看屏幕干活越稳因为屏幕本身不会改。场景实战从单脚本到跨平台测试并入 Playwright变成回归用例适用情况团队已有 Playwright 测试工程想加一条选择器写不出来的断言比如选中套餐带蓝色边框和勾选标记。在项目里安装依赖npm i midscene/web playwright playwright/test tsx --save-dev核心代码只有三行import { PlaywrightAgent } from midscene/web/playwright; const agent new PlaywrightAgent(page); // page 是 Playwright 的页面实例 // 一句话完成多步流程等状态最后做视觉断言 await agent.aiAct(搜索耳机然后将结果筛选为价格低于 100 美元); await agent.aiWaitFor(筛选后的搜索结果已显示); await agent.aiAssert(搜索结果中的每件商品价格都低于 100 美元); 接入测试运行器时在playwright.config.ts的 reporter 里加一条midscene/web/playwright-reporter多个用例可以合并成一份报告效果就是前面那张时间线回放图。同一套 YAML 驱动 Android 真机适用情况测试对象是手机 App不想 Web 和移动端各维护一套脚本。先执行adb devices拿到设备 IDYAML 的第一段从page换成android即可android: deviceId: s4ey59 # adb devices 输出里的设备 ID tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索按钮 - ai: 点击 开始 按钮开始导航后面的交互步骤和 Web 写法完全一致自然语言不用改变的只是驱动对象从浏览器换成了真机。用桥接模式复用登录态适用情况被测系统需要登录、有验证码新开一个无头浏览器根本进不去。在page段加一行配置Midscene 通过 Chrome 扩展驱动你已登录的浏览器复用现有 Cookie 和插件状态page: url: https://www.bing.com bridgeMode: newTabWithUrl # 桥接模式接管本地已登录的浏览器 这个能力还有个副作用脚本跑到验证码处停下你手工完成验证脚本接着往下走——人 机器混合流程由此变成配置项。调优与避坑用缓存和批处理把耗时、成本压下去[!TIP] 打开缓存重复执行不再调模型给 agent 加一段cache配置Midscene 会把规划步骤和元素定位结果写入./midscene_run/cache目录.cache.yaml文件。下次相同指令在相似页面执行时直接命中缓存跳过模型调用缓存失效会自动回退到模型重新分析不会卡死。agent: cache: id: my-cache-test官方文档里有一组实测同一个案例开启缓存后执行时间从 51 秒降到 28 秒。[!TIP] 批量执行加自动重试专治偶发失败CLI 支持通配符批量选择脚本--concurrent控制并发--retry只重试失败的脚本默认 0 次。网络抖动、模型输出偶发不稳定都靠它兜底。midscene ./scripts/**/*.yaml --concurrent 4 --retry 2 --continue-on-error一个容易误解的坑aiQuery、aiAssert这类查询/断言 API从不缓存结果——查的是实时数据缓存了等于造假。发现断言数据不对时先想清楚是不是这条设计限制在起作用。[!WARNING].env必须放在运行命令的目录它和 YAML 文件所在目录无关。在scripts/下执行midscene.env就必须也在scripts/里否则模型配置不会加载直接报 401。正确做法是统一在项目根目录运行命令、.env也放根目录需要排查时加--dotenv-debug看加载日志。把数字摆在一起看方案典型耗时模型成本维护复杂度手写选择器最快无 AI 调用0高页面结构一变就挂视觉驱动不开缓存51s官方文档示例值每步都要调模型低视觉驱动 缓存28s官方文档示例值首次之后大幅降低低成本方面还有一笔账AppControlBench 用 Doubao Seed 2.1 Turbo 跑完 60 个任务模型调用总费用 0.59 美元其中 58 个通过。看屏幕干活的主要开销是图像推理配合单价较低的模型整体账单比想象中友好。下一步可以做什么 想继续深入按顺序挑一件做先在 Playground 里验证指令用 Chrome 扩展或移动端 Playground 试跑自然语言指令确认措辞有效后再搬进脚本少在 CI 里反复试错。给回归套件建缓存生产环境用cache: { strategy: read-only }测试通过后手动flushCache()避免把偶发的错误定位固化进缓存。给存量用例补视觉断言选择器写不出来的效果高亮颜色、布局、canvas 内容先在最关键的页面加一条aiAssert。学会看报告定位失败失败后先打开 HTML 报告回放决策链区分模型看错了和页面状态不对两类原因。横向扩平台Web 流程稳定后把 YAML 首段换成android或ios同一套指令复用到移动端。延伸阅读YAML 脚本运行器文档、AI 规划与定位缓存文档、CLI 源码。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 3:39:57 · 阅读 1.2k Midscene：三步跑通视觉驱动 UI 自动化｜面向 E2E 测试的 GUI Agent 保姆级上手
Midscene三步跑通视觉驱动 UI 自动化面向 E2E 测试的 GUI Agent 保姆级上手【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene 是一个面向 E2E 测试的 GUI Agent用视觉理解来操控界面的程序你用自然语言描述操作目标它看屏幕定位元素并自动点击、输入、校验覆盖 Web、Android、iOS 和桌面端。本文先带你跑通第一个视觉驱动测试再讲清原理最后给出两招省时省钱的调优做法。脚本跑到一半找不到按钮你可能踩了这些坑如果你做过 UI 自动化大概被两种失败折磨过选择器写死成#login-btn .submit某天前端重命名了类名脚本凌晨在 CI 上集体报element not found。坐标在 1920×1080 上调好换个窗口尺寸或显示器分辨率一半点击全偏了。问题的根源是元素在哪和元素长什么样被绑在了一起。Midscene 的思路不一样它不要选择器要截图。你用自然语言描述任务由多模态模型看屏幕判断该点哪里、输入什么。三步跑通第一个视觉自动化脚本 第一步准备环境上手走的是官方 CLI不需要克隆源码仓库。前提只有两个# 检查 Node 版本需要 20.19 / 22.12 / 24 node -v # 全局安装 Midscene 命令行工具 npm i -g midscene/cli 如果终端里看到Unsupported Node.js version先把 Node 升到上面的版本再重试。然后准备模型。Midscene 自身不内置模型需要你自己提供一个有视觉定位能力的多模态模型。以官方文档示例的豆包 Seed 2.1 Turbo 为例在运行命令的目录下建一个.env填入配置# .env注意没有 export 前缀这是 dotenv 的约定 MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 MIDSCENE_MODEL_FAMILYdoubao-seed如果你用 Qwen、GLM、Gemini 等模型变量名不变只换取值具体以模型配置文档为准。 第二步写脚本新建bing-search.yaml整个打开页面 → 搜索 → 断言流程就是三句自然语言page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息 第三步运行并查看报告# --headed 会打开浏览器窗口方便观察操作过程 midscene ./bing-search.yaml --headed 预期现象命令行滚动输出执行进度结束后生成一份 HTML 报告。打开它能逐帧回放 Agent 点了哪里、每一步看到什么、断言是否通过。若报 401/403先查 API Key若提示扩展冲突先禁用其他 Chrome 插件再试。跑通之后为什么换界面它也不会挂像个会看屏幕的新同事为什么截图就能干活打个比方。这像雇了一个会看屏幕的新同事。你只说搜一下今天的天气他不看 DOM而是看画面先规划步骤打开搜索框 → 输入 → 回车执行时再定位搜索框在屏幕的哪个位置点完还要校验结果对不对。Midscene 做的正是这套循环截图 → 模型规划步骤 → 定位目标元素的坐标 → 调浏览器或设备接口执行点击、输入 → 再截图验证。全程不依赖选择器所以纯图标按钮、自定义控件、canvas、跨域 iframe 里的东西都能点到。下图左侧就是 Android 场景下的真实决策链每一步都经过 Planning → Insight/Locate → Action/Tap 三种状态执行到哪一步一目了然。官方公开的基准成绩可以给个参考AndroidWorld Pass1 93.1%、MobileWorld 78.6%、AppControlBench 96.7%各自对应不同评测模型。记住一句话就够了界面越常改看屏幕干活越稳因为屏幕本身不会改。场景实战从单脚本到跨平台测试并入 Playwright变成回归用例适用情况团队已有 Playwright 测试工程想加一条选择器写不出来的断言比如选中套餐带蓝色边框和勾选标记。在项目里安装依赖npm i midscene/web playwright playwright/test tsx --save-dev核心代码只有三行import { PlaywrightAgent } from midscene/web/playwright; const agent new PlaywrightAgent(page); // page 是 Playwright 的页面实例 // 一句话完成多步流程等状态最后做视觉断言 await agent.aiAct(搜索耳机然后将结果筛选为价格低于 100 美元); await agent.aiWaitFor(筛选后的搜索结果已显示); await agent.aiAssert(搜索结果中的每件商品价格都低于 100 美元); 接入测试运行器时在playwright.config.ts的 reporter 里加一条midscene/web/playwright-reporter多个用例可以合并成一份报告效果就是前面那张时间线回放图。同一套 YAML 驱动 Android 真机适用情况测试对象是手机 App不想 Web 和移动端各维护一套脚本。先执行adb devices拿到设备 IDYAML 的第一段从page换成android即可android: deviceId: s4ey59 # adb devices 输出里的设备 ID tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索按钮 - ai: 点击 开始 按钮开始导航后面的交互步骤和 Web 写法完全一致自然语言不用改变的只是驱动对象从浏览器换成了真机。用桥接模式复用登录态适用情况被测系统需要登录、有验证码新开一个无头浏览器根本进不去。在page段加一行配置Midscene 通过 Chrome 扩展驱动你已登录的浏览器复用现有 Cookie 和插件状态page: url: https://www.bing.com bridgeMode: newTabWithUrl # 桥接模式接管本地已登录的浏览器 这个能力还有个副作用脚本跑到验证码处停下你手工完成验证脚本接着往下走——人 机器混合流程由此变成配置项。调优与避坑用缓存和批处理把耗时、成本压下去[!TIP] 打开缓存重复执行不再调模型给 agent 加一段cache配置Midscene 会把规划步骤和元素定位结果写入./midscene_run/cache目录.cache.yaml文件。下次相同指令在相似页面执行时直接命中缓存跳过模型调用缓存失效会自动回退到模型重新分析不会卡死。agent: cache: id: my-cache-test官方文档里有一组实测同一个案例开启缓存后执行时间从 51 秒降到 28 秒。[!TIP] 批量执行加自动重试专治偶发失败CLI 支持通配符批量选择脚本--concurrent控制并发--retry只重试失败的脚本默认 0 次。网络抖动、模型输出偶发不稳定都靠它兜底。midscene ./scripts/**/*.yaml --concurrent 4 --retry 2 --continue-on-error一个容易误解的坑aiQuery、aiAssert这类查询/断言 API从不缓存结果——查的是实时数据缓存了等于造假。发现断言数据不对时先想清楚是不是这条设计限制在起作用。[!WARNING].env必须放在运行命令的目录它和 YAML 文件所在目录无关。在scripts/下执行midscene.env就必须也在scripts/里否则模型配置不会加载直接报 401。正确做法是统一在项目根目录运行命令、.env也放根目录需要排查时加--dotenv-debug看加载日志。把数字摆在一起看方案典型耗时模型成本维护复杂度手写选择器最快无 AI 调用0高页面结构一变就挂视觉驱动不开缓存51s官方文档示例值每步都要调模型低视觉驱动 缓存28s官方文档示例值首次之后大幅降低低成本方面还有一笔账AppControlBench 用 Doubao Seed 2.1 Turbo 跑完 60 个任务模型调用总费用 0.59 美元其中 58 个通过。看屏幕干活的主要开销是图像推理配合单价较低的模型整体账单比想象中友好。下一步可以做什么 想继续深入按顺序挑一件做先在 Playground 里验证指令用 Chrome 扩展或移动端 Playground 试跑自然语言指令确认措辞有效后再搬进脚本少在 CI 里反复试错。给回归套件建缓存生产环境用cache: { strategy: read-only }测试通过后手动flushCache()避免把偶发的错误定位固化进缓存。给存量用例补视觉断言选择器写不出来的效果高亮颜色、布局、canvas 内容先在最关键的页面加一条aiAssert。学会看报告定位失败失败后先打开 HTML 报告回放决策链区分模型看错了和页面状态不对两类原因。横向扩平台Web 流程稳定后把 YAML 首段换成android或ios同一套指令复用到移动端。延伸阅读YAML 脚本运行器文档、AI 规划与定位缓存文档、CLI 源码。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考