Midscene.js 视觉驱动 UI 自动化实战从自然语言指令到跨平台 E2E 测试的完整落地指南【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene深夜十一点测试工程师老张盯着 CI 控制台里第 5 次红掉的用例发呆——前端刚重构了 DOM 结构几十条 XPath 选择器全部失效这个月的回归测试已经第三次推倒重写。如果你也经历过选择器天天改、canvas 点不到、原生 App 测不了的循环那么 Midscene.js 值得你花 20 分钟认真了解它是一个开源的 GUI Agent用视觉 AI 替代选择器让你用一句自然语言就能驱动 Web、Android、iOS、HarmonyOS 和桌面应用的端到端测试。本文不聊概念直接带你从一个真实场景出发走完验证指令→集成代码→YAML 脚本→生产优化的完整路径。️ 实战主线跟着老张跑通第一个视觉自动化测试老张接手的是一个电商网站的回归测试任务。他决定用 Midscene.js 从零搭建一套不依赖选择器的自动化流程整个链路只有四步。第一步用 Chrome 扩展零成本验证想法约 5 分钟Midscene 的 Chrome 扩展本身就是面向 Web 的 Playground无需搭建任何项目。安装扩展后在浏览器右侧的 Midscene 侧边栏中粘贴模型配置并保存MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 MIDSCENE_MODEL_API_KEY你的API-Key MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 MIDSCENE_MODEL_FAMILYdoubao-seed打开任意网页在侧边栏输入自然语言指令即可立即看到效果——比如在搜索框输入 Headphones 并点击搜索按钮。Midscene 会从截图理解页面、规划步骤并执行操作。老张把要回归的核心流程全部用这种方式先验证了一遍确认 AI 能看懂这个网站。第二步把验证过的指令沉淀成可复现的代码Playground 验证通过后指令就可以迁移到midscene/web的 Agent API 中。安装依赖并编写脚本npm i midscene/web playwright playwright/test tsx --save-dev// demo.ts import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; import dotenv/config; (async () { const browser await chromium.launch({ headless: true }); const page await browser.newPage(); await page.setViewportSize({ width: 1280, height: 768 }); await page.goto(https://www.ebay.com); const agent new PlaywrightAgent(page); // 自然语言交互输入关键词并搜索 await agent.aiAct(type Headphones in search box, hit Enter); // 结构化数据提取返回 JSON 数组 const items await agent.aiQueryArray{ itemTitle: string; price: number }( {itemTitle: string, price: Number}[], find item in list and corresponding price, ); console.log(headphones in stock, items); // 视觉断言验证用户真正看到的内容 await agent.aiAssert(There is a category filter on the left); // 点击列表中的第一个商品 await agent.aiTap(the first item in the list); await browser.close(); })();运行npx tsx demo.ts几秒后命令行就会打印出模型从截图里提取的商品标题和价格。注意脚本全程没有一个 XPath 或 CSS 选择器——这就是 Midscene 的核心所有元素定位都基于截图而非页面结构。第三步用 YAML 脚本去掉样板代码如果只是跑几个简单的冒烟流程连 Agent 代码都可以省掉。Midscene 提供了 YAML 脚本格式和命令行运行器全局安装后即可使用npm i -g midscene/cli在工具运行目录下放置.env配置模型四件套不带export前缀再写一个bing-search.yamlpage: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息执行midscene ./bing-search.yaml命令行会输出执行进度并在./midscene_run/report下生成可视化 HTML 报告。老张把上面 Playwright 里验证过的流程改写成 YAML十分钟就得到了第一套可提交到仓库的回归脚本。第四步跑起来看报告无论是 SDK 还是 CLI 方式运行Midscene 都会自动生成一份图文报告——包含每一步的截图、AI 的规划过程、元素定位结果和断言结论。CLI 执行完成后直接在浏览器打开报告中对应的 HTML 文件即可复盘每一轮交互。这份报告也是后续定位AI 为什么点错的第一手证据。️ 能力地图Midscene.js 能做什么能力模块适用场景一句话示例规划交互aiAct多步骤、有分支的复杂流程搜索耳机将第一件商品加入购物车并确认购物车数量变为 1即时交互aiTap/aiInput/aiScroll单步、确定性的操作点击右上角的购物车图标界面理解aiQuery/aiAssert/aiBoolean数据提取与视觉校验页面中的商品{name, price}[]页面顶部显示导航栏YAML 脚本轻量冒烟测试、CI 快速接入上面第 3 步的bing-search.yaml跨平台适配移动端与桌面端回归同一套 YAML 语法驱动 Android / iOS / HarmonyOS / 桌面Chrome 扩展 / Bridge 模式零代码体验、复用本机浏览器状态在侧边栏直接输入指令执行 进阶专题三个让 Midscene 真正好用的能力专题一aiAct 自动规划 vs 即时交互——选对 API 事半功倍Midscene 最容易被误解的一点是所有操作都用aiAct。实际上它提供两套交互哲学aiAct让 Agent 自主规划多步骤路径适合如果出现弹窗就关闭、然后点击结账按钮这类不确定流程而aiTap、aiInput等即时交互 API 每次只定位并执行一个固定动作路径明确、token 消耗小。判断原则很简单流程稳定用即时交互页面多变用aiAct。对于目标元素小、容易和周围元素混淆的场景还可以给即时交互加一个deepLocate: true选项让模型多花一次调用做深度定位准确率会明显提升。老张的回归脚本里购物车角标这种小目标就统一加了deepLocate。专题二YAML 脚本 CLI 参数把自动化塞进 CIYAML 脚本的真正威力在于命令行参数。midscene/cli支持用 glob 匹配多个脚本批量执行也支持并发、重试和共享登录态# 并发执行多个搜索脚本出错继续失败自动重试 2 次 midscene --files ./scripts/search-*.yaml --concurrent 4 --continue-on-error --retry 2对于需要先登录再跑用例的场景可以用setup前置脚本 shareBrowserContext: true共享登录态生产环境想让缓存结果保持一致则把缓存策略设为只读agent: cache: id: checkout-cache strategy: read-only缓存是 Midscene 优化执行成本的利器它会把 AI 的规划步骤和 Web 元素的 XPath 定位结果缓存到./midscene_run/cache官方数据显示相同用例的耗时可以从 51 秒降到 28 秒。查询类操作aiQuery/aiAssert永远不会被缓存不用担心结果过期。专题三一套 YAML跑遍所有平台Midscene 的能力边界不是网页而是能截图的界面。同一个 YAML 文件把page段换成android、ios或computer段就能驱动对应的设备android: deviceId: s4ey59 # 通过 adb devices 获取 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索按钮 - ai: 点击第一个搜索结果进入详情页 - ai: 点击 路线 按钮进入路线规划页面 - ai: 点击 开始 按钮开始导航Android 平台还额外提供了runAdbShell、launch、terminate等平台专属动作可以清除应用数据、启动指定应用甚至直接执行adb shell命令。桌面端Windows/macOS/Linux则通过截屏 原生键鼠控制实现自动化。 踩坑与避雷清单老张踩过的 6 个坑模型配了但一直报鉴权错误确认四个环境变量都齐全——MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_FAMILY。FAMILY决定 Midscene 如何适配模型漏配是最高频错误。用本地 Ollama 时还需设置OLLAMA_ORIGINS*否则浏览器侧访问会报 403。原生select下拉框点不到浏览器会用系统原生控件渲染下拉选项截图中根本看不到。Midscene 默认开启了forceChromeSelectRendering强制用 Chrome 渲染下拉框如果关闭了它或发现截图里没有下拉选项先检查这个开关。截图报waiting for fonts to load超时这是 Playwright 在 CI/容器环境里等字体加载导致的与 Midscene 无关。执行前加环境变量PW_TEST_SCREENSHOT_NO_FONTS_READY1即可绕过。浏览器界面持续闪动viewport 的deviceScaleFactor和系统像素比不匹配常见于 Retina 屏。把deviceScaleFactor设为与浏览器window.devicePixelRatio一致的值。Playwright 下载浏览器卡死npm install不会自动下载浏览器需执行npx playwright install网络慢时用镜像或只装 Chromiumnpx playwright install --with-deps chromium。Chrome 扩展运行报Cannot access a chrome-extension:// URL通常是其他扩展向页面注入了 iframe 或 script。在开发者工具里找到chrome-extension://开头的注入内容复制扩展 ID 去chrome://extensions/禁用冲突扩展。 落地建议三条立即可执行的行动今天就用 Chrome 扩展验证 5 条核心流程。不写一行代码把你们产品最高频的 5 条用户路径用自然语言指令在侧边栏跑一遍确认视觉 AI 能覆盖你们的产品。这一步成本最低也是判断这个工具适不适合我们的最快方式。用 YAML 脚本固化第一条冒烟用例并接入 CI。选一条每天必跑的路径比如登录→首页→退出写成 YAML 脚本加入流水线。配合--concurrent和--retry参数控制执行策略先让团队看到可视化报告的价值。再评估移动端场景。如果你们有 Android/iOS 产品先在对应平台的 Playground 里验证同一套指令迁移成本主要在设备环境adb、WebDriverAgent而不是脚本本身。总结从 Chrome 扩展里的一句自然语言到 Playwright 中的aiAct再到 CI 里批量执行的 YAML 脚本Midscene.js 用纯视觉 自然语言把 UI 自动化从维护选择器变成了描述目标。它没有银弹式地消灭所有问题——复杂元素仍建议deepLocate、生产环境缓存需谨慎配置——但它确实让只要人眼能看到的脚本就能操作成为现实。现在打开你的浏览器装上扩展输入第一句指令试试吧如果你已经在用选择器维护回归测试不妨从最痛的那条用例开始迁移。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene.js 视觉驱动 UI 自动化实战：从自然语言指令到跨平台 E2E 测试的完整落地指南
Midscene.js 视觉驱动 UI 自动化实战从自然语言指令到跨平台 E2E 测试的完整落地指南【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene深夜十一点测试工程师老张盯着 CI 控制台里第 5 次红掉的用例发呆——前端刚重构了 DOM 结构几十条 XPath 选择器全部失效这个月的回归测试已经第三次推倒重写。如果你也经历过选择器天天改、canvas 点不到、原生 App 测不了的循环那么 Midscene.js 值得你花 20 分钟认真了解它是一个开源的 GUI Agent用视觉 AI 替代选择器让你用一句自然语言就能驱动 Web、Android、iOS、HarmonyOS 和桌面应用的端到端测试。本文不聊概念直接带你从一个真实场景出发走完验证指令→集成代码→YAML 脚本→生产优化的完整路径。️ 实战主线跟着老张跑通第一个视觉自动化测试老张接手的是一个电商网站的回归测试任务。他决定用 Midscene.js 从零搭建一套不依赖选择器的自动化流程整个链路只有四步。第一步用 Chrome 扩展零成本验证想法约 5 分钟Midscene 的 Chrome 扩展本身就是面向 Web 的 Playground无需搭建任何项目。安装扩展后在浏览器右侧的 Midscene 侧边栏中粘贴模型配置并保存MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 MIDSCENE_MODEL_API_KEY你的API-Key MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 MIDSCENE_MODEL_FAMILYdoubao-seed打开任意网页在侧边栏输入自然语言指令即可立即看到效果——比如在搜索框输入 Headphones 并点击搜索按钮。Midscene 会从截图理解页面、规划步骤并执行操作。老张把要回归的核心流程全部用这种方式先验证了一遍确认 AI 能看懂这个网站。第二步把验证过的指令沉淀成可复现的代码Playground 验证通过后指令就可以迁移到midscene/web的 Agent API 中。安装依赖并编写脚本npm i midscene/web playwright playwright/test tsx --save-dev// demo.ts import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; import dotenv/config; (async () { const browser await chromium.launch({ headless: true }); const page await browser.newPage(); await page.setViewportSize({ width: 1280, height: 768 }); await page.goto(https://www.ebay.com); const agent new PlaywrightAgent(page); // 自然语言交互输入关键词并搜索 await agent.aiAct(type Headphones in search box, hit Enter); // 结构化数据提取返回 JSON 数组 const items await agent.aiQueryArray{ itemTitle: string; price: number }( {itemTitle: string, price: Number}[], find item in list and corresponding price, ); console.log(headphones in stock, items); // 视觉断言验证用户真正看到的内容 await agent.aiAssert(There is a category filter on the left); // 点击列表中的第一个商品 await agent.aiTap(the first item in the list); await browser.close(); })();运行npx tsx demo.ts几秒后命令行就会打印出模型从截图里提取的商品标题和价格。注意脚本全程没有一个 XPath 或 CSS 选择器——这就是 Midscene 的核心所有元素定位都基于截图而非页面结构。第三步用 YAML 脚本去掉样板代码如果只是跑几个简单的冒烟流程连 Agent 代码都可以省掉。Midscene 提供了 YAML 脚本格式和命令行运行器全局安装后即可使用npm i -g midscene/cli在工具运行目录下放置.env配置模型四件套不带export前缀再写一个bing-search.yamlpage: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息执行midscene ./bing-search.yaml命令行会输出执行进度并在./midscene_run/report下生成可视化 HTML 报告。老张把上面 Playwright 里验证过的流程改写成 YAML十分钟就得到了第一套可提交到仓库的回归脚本。第四步跑起来看报告无论是 SDK 还是 CLI 方式运行Midscene 都会自动生成一份图文报告——包含每一步的截图、AI 的规划过程、元素定位结果和断言结论。CLI 执行完成后直接在浏览器打开报告中对应的 HTML 文件即可复盘每一轮交互。这份报告也是后续定位AI 为什么点错的第一手证据。️ 能力地图Midscene.js 能做什么能力模块适用场景一句话示例规划交互aiAct多步骤、有分支的复杂流程搜索耳机将第一件商品加入购物车并确认购物车数量变为 1即时交互aiTap/aiInput/aiScroll单步、确定性的操作点击右上角的购物车图标界面理解aiQuery/aiAssert/aiBoolean数据提取与视觉校验页面中的商品{name, price}[]页面顶部显示导航栏YAML 脚本轻量冒烟测试、CI 快速接入上面第 3 步的bing-search.yaml跨平台适配移动端与桌面端回归同一套 YAML 语法驱动 Android / iOS / HarmonyOS / 桌面Chrome 扩展 / Bridge 模式零代码体验、复用本机浏览器状态在侧边栏直接输入指令执行 进阶专题三个让 Midscene 真正好用的能力专题一aiAct 自动规划 vs 即时交互——选对 API 事半功倍Midscene 最容易被误解的一点是所有操作都用aiAct。实际上它提供两套交互哲学aiAct让 Agent 自主规划多步骤路径适合如果出现弹窗就关闭、然后点击结账按钮这类不确定流程而aiTap、aiInput等即时交互 API 每次只定位并执行一个固定动作路径明确、token 消耗小。判断原则很简单流程稳定用即时交互页面多变用aiAct。对于目标元素小、容易和周围元素混淆的场景还可以给即时交互加一个deepLocate: true选项让模型多花一次调用做深度定位准确率会明显提升。老张的回归脚本里购物车角标这种小目标就统一加了deepLocate。专题二YAML 脚本 CLI 参数把自动化塞进 CIYAML 脚本的真正威力在于命令行参数。midscene/cli支持用 glob 匹配多个脚本批量执行也支持并发、重试和共享登录态# 并发执行多个搜索脚本出错继续失败自动重试 2 次 midscene --files ./scripts/search-*.yaml --concurrent 4 --continue-on-error --retry 2对于需要先登录再跑用例的场景可以用setup前置脚本 shareBrowserContext: true共享登录态生产环境想让缓存结果保持一致则把缓存策略设为只读agent: cache: id: checkout-cache strategy: read-only缓存是 Midscene 优化执行成本的利器它会把 AI 的规划步骤和 Web 元素的 XPath 定位结果缓存到./midscene_run/cache官方数据显示相同用例的耗时可以从 51 秒降到 28 秒。查询类操作aiQuery/aiAssert永远不会被缓存不用担心结果过期。专题三一套 YAML跑遍所有平台Midscene 的能力边界不是网页而是能截图的界面。同一个 YAML 文件把page段换成android、ios或computer段就能驱动对应的设备android: deviceId: s4ey59 # 通过 adb devices 获取 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索按钮 - ai: 点击第一个搜索结果进入详情页 - ai: 点击 路线 按钮进入路线规划页面 - ai: 点击 开始 按钮开始导航Android 平台还额外提供了runAdbShell、launch、terminate等平台专属动作可以清除应用数据、启动指定应用甚至直接执行adb shell命令。桌面端Windows/macOS/Linux则通过截屏 原生键鼠控制实现自动化。 踩坑与避雷清单老张踩过的 6 个坑模型配了但一直报鉴权错误确认四个环境变量都齐全——MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_FAMILY。FAMILY决定 Midscene 如何适配模型漏配是最高频错误。用本地 Ollama 时还需设置OLLAMA_ORIGINS*否则浏览器侧访问会报 403。原生select下拉框点不到浏览器会用系统原生控件渲染下拉选项截图中根本看不到。Midscene 默认开启了forceChromeSelectRendering强制用 Chrome 渲染下拉框如果关闭了它或发现截图里没有下拉选项先检查这个开关。截图报waiting for fonts to load超时这是 Playwright 在 CI/容器环境里等字体加载导致的与 Midscene 无关。执行前加环境变量PW_TEST_SCREENSHOT_NO_FONTS_READY1即可绕过。浏览器界面持续闪动viewport 的deviceScaleFactor和系统像素比不匹配常见于 Retina 屏。把deviceScaleFactor设为与浏览器window.devicePixelRatio一致的值。Playwright 下载浏览器卡死npm install不会自动下载浏览器需执行npx playwright install网络慢时用镜像或只装 Chromiumnpx playwright install --with-deps chromium。Chrome 扩展运行报Cannot access a chrome-extension:// URL通常是其他扩展向页面注入了 iframe 或 script。在开发者工具里找到chrome-extension://开头的注入内容复制扩展 ID 去chrome://extensions/禁用冲突扩展。 落地建议三条立即可执行的行动今天就用 Chrome 扩展验证 5 条核心流程。不写一行代码把你们产品最高频的 5 条用户路径用自然语言指令在侧边栏跑一遍确认视觉 AI 能覆盖你们的产品。这一步成本最低也是判断这个工具适不适合我们的最快方式。用 YAML 脚本固化第一条冒烟用例并接入 CI。选一条每天必跑的路径比如登录→首页→退出写成 YAML 脚本加入流水线。配合--concurrent和--retry参数控制执行策略先让团队看到可视化报告的价值。再评估移动端场景。如果你们有 Android/iOS 产品先在对应平台的 Playground 里验证同一套指令迁移成本主要在设备环境adb、WebDriverAgent而不是脚本本身。总结从 Chrome 扩展里的一句自然语言到 Playwright 中的aiAct再到 CI 里批量执行的 YAML 脚本Midscene.js 用纯视觉 自然语言把 UI 自动化从维护选择器变成了描述目标。它没有银弹式地消灭所有问题——复杂元素仍建议deepLocate、生产环境缓存需谨慎配置——但它确实让只要人眼能看到的脚本就能操作成为现实。现在打开你的浏览器装上扩展输入第一句指令试试吧如果你已经在用选择器维护回归测试不妨从最痛的那条用例开始迁移。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考