Midscene.js 实战指南4 个场景跑通 AI 视觉 UI 自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一套 AI 视觉 UI 自动化框架用 VLM 读截图直接驱动 Web、Android、iOS 和桌面端不依赖 DOM 定位器。先说个真实痛点一次 A/B 实验把弹窗的 class 前缀改了整条基于 CSS 选择器的回归流水线红了一半而弹窗本身没有任何行为变化。视觉路线的价值就在这——它看的是屏幕上有什么不是源码里叫什么名字。五分钟跑通你的第一次视觉自动化装 CLI、配模型环境变量、写一个 8 行的 YAML一条命令就能跑起来。CLI 要求 Node 20.19 / 22.12 / 24。npm i -g midscene/cliMIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY你的API_KEY MIDSCENE_MODEL_NAME模型名称 MIDSCENE_MODEL_FAMILY模型系列page: url: https://example.com tasks: - name: 冒烟 flow: - ai: 点击页面上的登录入口 - sleep: 2000 - aiAssert: 页面出现了用户名输入框midscene ./smoke.yaml跑完终端输出进度./midscene_run/output下会生成一份 HTML 报告每个步骤带截图和模型决策过程后面调试一节会细讲。它到底怎么看懂屏幕的——从截图到操作的内部链路每一步视觉任务的执行链路固定为四步没有第五步截屏按当前平台适配器抓一帧当前画面归一化尺寸后作为输入模型理解把任务指令 截图发给 VLM视觉语言模型返回目标元素坐标或结构化数据复杂指令会先规划成多步子任务执行动作坐标交给平台驱动层——Web 走 CDP 注入点击、移动端走input tap、桌面走系统输入事件验证回环aiAssert/ 下一步的截屏对比确认状态变化不满足就按错误类型回退重试。这条链路的核心实现在 packages/core/src/agent/各平台只是替换了截图和执行动作两个端点中间的理解层完全复用。所以同一句自然语言指令在 Web 和 Android 上能触发几乎相同的决策。能力边界多端适配架构一览同一套 Agent API五个平台各自有独立适配器底层驱动技术不同选型时先确认你的端在这里面平台适配器包底层技术WebPuppeteer / Playwrightpackages/web-integration/CDP 注入点击输入另支持 Chrome 扩展 Bridge 模式接管你正在用的桌面浏览器Androidpackages/android/adb scrcpy 屏幕流iOSpackages/ios/WebDriverAgent MJPEG 画面HarmonyOSpackages/harmony/hdc 设备桥桌面Win / macOS / Linuxpackages/computer/原生输入驱动RDP 可接管远程 Windows 桌面注意两点各端能力不是完全对齐的比如 XPath 定位缓存目前只在 Web 生效移动端要先把设备接好——Android 走 USB 调试iOS 要先起 WebDriverAgent这部分前置成本比 Web 高不少。三个生产级场景场景一CI 流水线中的跨端冒烟验证YAML 天然适合当 CI 的契约文件一份脚本同时描述 Web 和 App 的关键路径每次合入都跑。page: url: https://staging.example.com tasks: - name: 登录主链路 flow: - ai: 打开登录页使用测试账号完成登录 - aiAssert: 顶部出现用户头像 - name: 核心页可达 flow: - ai: 进入订单页面 - aiAssert: 订单列表区域可见没有报错弹窗midscene ./ci-smoke.yaml # 产出 ./midscene_run/output 报告适用条件主链路步骤少而关键登录、下单、核心页可达容忍单步 2~5 秒的模型耗时不适合用来替代细粒度的断言密集型用例集。场景二竞品页面定时巡检与数据抽取把看页面变成结构化数据源cron 定时跑抽取结果落盘供对比。import { PuppeteerPageAgent } from midscene/web; const browser await import(puppeteer).then(m m.default.launch({ headless: true })); const page await (await browser.newPage()).goto(https://competitor.example.com/hot); const agent new PuppeteerPageAgent(page); const rows await agent.aiQuery( 抓取前 10 个商品返回 JSON: {name: string, price: number, tag: string}[] ); await page.screenshot({ path: patrol-${Date.now()}.png }); await browser.close(); console.log(JSON.stringify(rows, null, 2));适用条件页面结构多变、写选择器维护成本高于直接抽数据数据量小一次几个字段、对成本不敏感。大规模高频抓取请先算模型账单或只对疑似有变化的页面触发抽取。场景三与 Playwright 混合驱动的存量测试迁移不用推倒重来Playwright 负责它擅长的确定步骤Midscene 负责定位器容易碎的动态部分。// playwright/test 用例内 import { PlaywrightAiFixture } from midscene/web; test(登录流程, async ({ page, ai, aiQuery }) { await page.goto(https://app.example.com/login); await ai(在账号框输入 testexample.com密码框输入正确密码点击登录); const banner await aiQuery(当前页面顶部 banner 的文案, { schema: { type: object, properties: { text: { type: string } } }, }); expect(banner.text).toMatch(/欢迎|Hello/); });适用条件存量 Playwright 用例中动态 UI 步骤占比 20%~50%——全是静态元素就别引入全在频繁变的组件上收益最大。迁移节奏建议按页面逐个替换别一次性全切。别急着上生产让脚本真正可靠的 5 个工程实践重试前先做幂等检查——按钮可能已经点掉了别对着旧截图盲重试。async function tapIfPresent(agent, desc) { if (!(await agent.aiBoolean(${desc} 按钮可见))) return false; await agent.aiTap(desc); return true; }生产用只读缓存别边跑边写——官方文档给的效果示例同一脚本缓存命中后从 51 秒降到 28 秒写入时机要自己控制。const agent new PuppeteerPageAgent(page, { cache: { strategy: read-only, id: smoke-login }, }); // 本地验证通过后再手动 agent.flushCache() 写回缓存模型按任务复杂度分级——简单断言走便宜快的模型复杂规划走更强的不同任务创建 Agent 时传入不同模型配置即可。const fast new PuppeteerPageAgent(page, { model: { name: 小模型, family: 对应系列 } }); const smart new PuppeteerPageAgent(page, { model: { name: 大模型, family: 对应系列 } }); await fast.aiAssert(出现登录成功提示); // 判断类小模型 await smart.ai(完成整个注册流程); // 规划类大模型并发要限流跑完必回收——多设备并行时限制同时发起的模型请求数结束时关浏览器和缓存的 agent 实例。const sem new Semaphore(4); // 最多 4 个并发模型任务 await Promise.all(targets.map(t sem.run(() runCase(t)))); await Promise.allSettled(agents.map(a a.destroy?.())); await browser.close();失败告警与报告归档要挂在流水线钩子上——CLI 跑完自动在./midscene_run/output生成 HTML 报告把它归档成 artifact、失败时推送链接比截一堆图发到群里有用得多。midscene: script: midscene ./ci-smoke.yaml artifacts: when: always paths: [midscene_run/output]调试不止于看截图报告系统与 Playground报告是执行过程自动落盘的不用额外调接口report-generator会把每步的截图、prompt、模型返回坐标和耗时写进单文件 HTML。两个关键用法本地调试直接浏览器打开报告时间轴上能逐步回放模型看到了什么、点了哪里配合 Playground 的实时指令面板快速验证措辞CI 归档把midscene_run/output作为 artifact 上传报告文件名按任务名生成失败时告警里带上 artifact 链接点开就是完整现场。artifacts: paths: [midscene_run/output] when: always expire_in: 7 days报告体积主要由截图数量决定长任务建议控制sleep时长减少无效帧而不是删步骤——删了步骤现场就丢了。生态拼图MCP 工具暴露与框架集成先给结论MCP server 在 v1.10 已下线官方推荐用Skills 各平台 CLI让 AI 编程助手直接驱动 Midscene旧项目可固定 1.9.8 继续用 MCP。也就是说让 AI 助手操作你的界面这件事现在走 CLI 入口而不是自建 MCP 服务。v1.9.8 时代的典型工具定义长这样可以作为你理解暴露面粒度的参照{ name: tap, description: 点击描述匹配的界面元素, inputSchema: { type: object, properties: { desc: { type: string, description: 元素的自然语言描述 }, deepLocate: { type: boolean, description: 启用深度定位 } }, required: [desc] } }和测试框架的集成则以 Playwright fixture 形式内置在 packages/web-integration/src/playwright/8 行接入import { test, expect } from playwright/test; import { PlaywrightAiFixture } from midscene/web; test(混合驱动, async ({ page, ai, aiBoolean }) { await page.goto(https://app.example.com); await ai(点击登录输入测试账号并登录); expect(await aiBoolean(已处于登录态)).toBe(true); });选型决策什么时候该用 / 什么时候别用✅ 适合⚠️ 谨慎动态 UI / Canvas / 频繁改版定位器维护成本高高并发批量回归千级用例模型时延和费用压不住Web App 桌面多端一致性验证想共用一套语义化用例强确定性、毫秒级时延敏感的关键路径自动化存量 Playwright/Appium 用例中定位器碎片化严重想渐进迁移纯静态内部系统写一次选择器十年不变——直接用传统方案更省竞品/多站点页面巡检与结构化数据抽取数据抓取规模大、频率高成本核算没跑通一句话收束Midscene.js 解决的是定位器写不动的那部分问题把它当作传统自动化之上的补偿层而不是全量替换是目前最稳的姿势。先从一条 CI 冒烟脚本和一份 artifact 报告开始跑两周再谈规模化。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene.js 实战指南：4 个场景跑通 AI 视觉 UI 自动化
Midscene.js 实战指南4 个场景跑通 AI 视觉 UI 自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一套 AI 视觉 UI 自动化框架用 VLM 读截图直接驱动 Web、Android、iOS 和桌面端不依赖 DOM 定位器。先说个真实痛点一次 A/B 实验把弹窗的 class 前缀改了整条基于 CSS 选择器的回归流水线红了一半而弹窗本身没有任何行为变化。视觉路线的价值就在这——它看的是屏幕上有什么不是源码里叫什么名字。五分钟跑通你的第一次视觉自动化装 CLI、配模型环境变量、写一个 8 行的 YAML一条命令就能跑起来。CLI 要求 Node 20.19 / 22.12 / 24。npm i -g midscene/cliMIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY你的API_KEY MIDSCENE_MODEL_NAME模型名称 MIDSCENE_MODEL_FAMILY模型系列page: url: https://example.com tasks: - name: 冒烟 flow: - ai: 点击页面上的登录入口 - sleep: 2000 - aiAssert: 页面出现了用户名输入框midscene ./smoke.yaml跑完终端输出进度./midscene_run/output下会生成一份 HTML 报告每个步骤带截图和模型决策过程后面调试一节会细讲。它到底怎么看懂屏幕的——从截图到操作的内部链路每一步视觉任务的执行链路固定为四步没有第五步截屏按当前平台适配器抓一帧当前画面归一化尺寸后作为输入模型理解把任务指令 截图发给 VLM视觉语言模型返回目标元素坐标或结构化数据复杂指令会先规划成多步子任务执行动作坐标交给平台驱动层——Web 走 CDP 注入点击、移动端走input tap、桌面走系统输入事件验证回环aiAssert/ 下一步的截屏对比确认状态变化不满足就按错误类型回退重试。这条链路的核心实现在 packages/core/src/agent/各平台只是替换了截图和执行动作两个端点中间的理解层完全复用。所以同一句自然语言指令在 Web 和 Android 上能触发几乎相同的决策。能力边界多端适配架构一览同一套 Agent API五个平台各自有独立适配器底层驱动技术不同选型时先确认你的端在这里面平台适配器包底层技术WebPuppeteer / Playwrightpackages/web-integration/CDP 注入点击输入另支持 Chrome 扩展 Bridge 模式接管你正在用的桌面浏览器Androidpackages/android/adb scrcpy 屏幕流iOSpackages/ios/WebDriverAgent MJPEG 画面HarmonyOSpackages/harmony/hdc 设备桥桌面Win / macOS / Linuxpackages/computer/原生输入驱动RDP 可接管远程 Windows 桌面注意两点各端能力不是完全对齐的比如 XPath 定位缓存目前只在 Web 生效移动端要先把设备接好——Android 走 USB 调试iOS 要先起 WebDriverAgent这部分前置成本比 Web 高不少。三个生产级场景场景一CI 流水线中的跨端冒烟验证YAML 天然适合当 CI 的契约文件一份脚本同时描述 Web 和 App 的关键路径每次合入都跑。page: url: https://staging.example.com tasks: - name: 登录主链路 flow: - ai: 打开登录页使用测试账号完成登录 - aiAssert: 顶部出现用户头像 - name: 核心页可达 flow: - ai: 进入订单页面 - aiAssert: 订单列表区域可见没有报错弹窗midscene ./ci-smoke.yaml # 产出 ./midscene_run/output 报告适用条件主链路步骤少而关键登录、下单、核心页可达容忍单步 2~5 秒的模型耗时不适合用来替代细粒度的断言密集型用例集。场景二竞品页面定时巡检与数据抽取把看页面变成结构化数据源cron 定时跑抽取结果落盘供对比。import { PuppeteerPageAgent } from midscene/web; const browser await import(puppeteer).then(m m.default.launch({ headless: true })); const page await (await browser.newPage()).goto(https://competitor.example.com/hot); const agent new PuppeteerPageAgent(page); const rows await agent.aiQuery( 抓取前 10 个商品返回 JSON: {name: string, price: number, tag: string}[] ); await page.screenshot({ path: patrol-${Date.now()}.png }); await browser.close(); console.log(JSON.stringify(rows, null, 2));适用条件页面结构多变、写选择器维护成本高于直接抽数据数据量小一次几个字段、对成本不敏感。大规模高频抓取请先算模型账单或只对疑似有变化的页面触发抽取。场景三与 Playwright 混合驱动的存量测试迁移不用推倒重来Playwright 负责它擅长的确定步骤Midscene 负责定位器容易碎的动态部分。// playwright/test 用例内 import { PlaywrightAiFixture } from midscene/web; test(登录流程, async ({ page, ai, aiQuery }) { await page.goto(https://app.example.com/login); await ai(在账号框输入 testexample.com密码框输入正确密码点击登录); const banner await aiQuery(当前页面顶部 banner 的文案, { schema: { type: object, properties: { text: { type: string } } }, }); expect(banner.text).toMatch(/欢迎|Hello/); });适用条件存量 Playwright 用例中动态 UI 步骤占比 20%~50%——全是静态元素就别引入全在频繁变的组件上收益最大。迁移节奏建议按页面逐个替换别一次性全切。别急着上生产让脚本真正可靠的 5 个工程实践重试前先做幂等检查——按钮可能已经点掉了别对着旧截图盲重试。async function tapIfPresent(agent, desc) { if (!(await agent.aiBoolean(${desc} 按钮可见))) return false; await agent.aiTap(desc); return true; }生产用只读缓存别边跑边写——官方文档给的效果示例同一脚本缓存命中后从 51 秒降到 28 秒写入时机要自己控制。const agent new PuppeteerPageAgent(page, { cache: { strategy: read-only, id: smoke-login }, }); // 本地验证通过后再手动 agent.flushCache() 写回缓存模型按任务复杂度分级——简单断言走便宜快的模型复杂规划走更强的不同任务创建 Agent 时传入不同模型配置即可。const fast new PuppeteerPageAgent(page, { model: { name: 小模型, family: 对应系列 } }); const smart new PuppeteerPageAgent(page, { model: { name: 大模型, family: 对应系列 } }); await fast.aiAssert(出现登录成功提示); // 判断类小模型 await smart.ai(完成整个注册流程); // 规划类大模型并发要限流跑完必回收——多设备并行时限制同时发起的模型请求数结束时关浏览器和缓存的 agent 实例。const sem new Semaphore(4); // 最多 4 个并发模型任务 await Promise.all(targets.map(t sem.run(() runCase(t)))); await Promise.allSettled(agents.map(a a.destroy?.())); await browser.close();失败告警与报告归档要挂在流水线钩子上——CLI 跑完自动在./midscene_run/output生成 HTML 报告把它归档成 artifact、失败时推送链接比截一堆图发到群里有用得多。midscene: script: midscene ./ci-smoke.yaml artifacts: when: always paths: [midscene_run/output]调试不止于看截图报告系统与 Playground报告是执行过程自动落盘的不用额外调接口report-generator会把每步的截图、prompt、模型返回坐标和耗时写进单文件 HTML。两个关键用法本地调试直接浏览器打开报告时间轴上能逐步回放模型看到了什么、点了哪里配合 Playground 的实时指令面板快速验证措辞CI 归档把midscene_run/output作为 artifact 上传报告文件名按任务名生成失败时告警里带上 artifact 链接点开就是完整现场。artifacts: paths: [midscene_run/output] when: always expire_in: 7 days报告体积主要由截图数量决定长任务建议控制sleep时长减少无效帧而不是删步骤——删了步骤现场就丢了。生态拼图MCP 工具暴露与框架集成先给结论MCP server 在 v1.10 已下线官方推荐用Skills 各平台 CLI让 AI 编程助手直接驱动 Midscene旧项目可固定 1.9.8 继续用 MCP。也就是说让 AI 助手操作你的界面这件事现在走 CLI 入口而不是自建 MCP 服务。v1.9.8 时代的典型工具定义长这样可以作为你理解暴露面粒度的参照{ name: tap, description: 点击描述匹配的界面元素, inputSchema: { type: object, properties: { desc: { type: string, description: 元素的自然语言描述 }, deepLocate: { type: boolean, description: 启用深度定位 } }, required: [desc] } }和测试框架的集成则以 Playwright fixture 形式内置在 packages/web-integration/src/playwright/8 行接入import { test, expect } from playwright/test; import { PlaywrightAiFixture } from midscene/web; test(混合驱动, async ({ page, ai, aiBoolean }) { await page.goto(https://app.example.com); await ai(点击登录输入测试账号并登录); expect(await aiBoolean(已处于登录态)).toBe(true); });选型决策什么时候该用 / 什么时候别用✅ 适合⚠️ 谨慎动态 UI / Canvas / 频繁改版定位器维护成本高高并发批量回归千级用例模型时延和费用压不住Web App 桌面多端一致性验证想共用一套语义化用例强确定性、毫秒级时延敏感的关键路径自动化存量 Playwright/Appium 用例中定位器碎片化严重想渐进迁移纯静态内部系统写一次选择器十年不变——直接用传统方案更省竞品/多站点页面巡检与结构化数据抽取数据抓取规模大、频率高成本核算没跑通一句话收束Midscene.js 解决的是定位器写不动的那部分问题把它当作传统自动化之上的补偿层而不是全量替换是目前最稳的姿势。先从一条 CI 冒烟脚本和一份 artifact 报告开始跑两周再谈规模化。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考