Midscene.js 跨平台自动化测试实战从零到可用的完整指南【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个用视觉驱动来做 UI 自动化的测试框架它不读 DOM、不写选择器而是把当前界面截图交给多模态模型理解再用自然语言指令完成点击、输入、断言和数据提取。同一套 API 可以跑在 Web、Android、iOS、HarmonyOS 和桌面端也兼容 Canvas 渲染、原生 App 和跨域 iframe 这类传统选择器够不到的场景。读完这篇你会知道怎么配好模型跑通第一条指令怎么接进 Playwright以及缓存、YAML 脚本、Chrome 桥接模式这几个最实用的玩法。理解视觉驱动Midscene.js 和选择器测试差在哪传统 UI 测试的每一步都绑在选择器上CSS 类名一改、重构一次结构用例就批量挂掉纯图标按钮、Canvas 画面、原生 App 里根本没有语义化的节点更谈不上验证「界面上看起来对不对」——DOM 里存在某个节点不代表用户真的看得到它。Midscene.js 的思路反过来每一步只依赖截图。你用中文描述目标比如「点击登录按钮」「页面顶部显示导航栏」框架负责把它变成对界面上的具体操作。好处是维护成本低、覆盖面广能断言用户真实看到的颜色、高亮和布局状态。配置模型跑通第一条自动化指令上手最短路径是先装 Chrome 插件仓库里apps/chrome-extension/就是它的源码在侧边栏设置页粘贴模型配置然后直接输入自然语言指令验证效果。模型配置只需要四个必选项详见 模型配置参考export MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 export MIDSCENE_MODEL_API_KEYyour-api-key export MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 export MIDSCENE_MODEL_FAMILYdoubao-seedMIDSCENE_MODEL_FAMILY决定坐标的处理方式换模型时别漏。可选的高阶项里常用的是MIDSCENE_MODEL_RETRY_COUNT默认失败后重试 1 次和MIDSCENE_MODEL_TIMEOUT默认 180 秒的硬超时。完整支持列表见 支持的模型与配置。核心就三类 API先记住名字await agent.aiAct(点击登录按钮); // 规划并执行操作 const items await agent.aiQuery({name: string, price: number}[], 页面中的商品); // 提取结构化数据 await agent.aiAssert(页面顶部显示导航栏); // 断言界面状态在插件里验证过的指令可以直接用同样的 API 写进代码行为一致。集成到 Playwright测试用例里怎么用在已有 Playwright 项目里装midscene/web后把 Agent 挂到 page 上即可import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; import dotenv/config; const browser await chromium.launch({ headless: true }); const page await browser.newPage(); await page.goto(https://www.ebay.com); const agent new PlaywrightAgent(page); await agent.aiAct(type Headphones in search box, hit Enter); const items await agent.aiQuery({itemTitle: string, price: Number}[], find item in list and corresponding price);Android 端同理用midscene/android的AndroidDeviceAndroidAgent先getConnectedDevices()找到设备再device.connect()。一个实用技巧是给 Agent 传aiActionContext把「遇到权限弹窗点同意、遇到登录页跳过」这类业务背景告诉模型能显著减少跑偏。脚本跑完后控制台会打印Midscene - report file updated: .../some_id.html浏览器打开就是带截图和步骤回放的报告排障时直接看报告比翻日志快。⚡ 启用缓存让重复执行更快Midscene.js 会缓存两类内容AI 规划出的步骤所有平台通用以及元素的 XPath 定位信息仅 Web。命中缓存时跳过模型调用官方文档给出的示例里同一段流程的耗时从 51 秒降到了 28 秒查询类操作aiQuery、aiAssert等永不缓存保证每次断言都是实时结果。缓存文件落在./midscene_run/cache目录缓存失效会自动回退到模型重新分析。策略按环境选YAML 里这样配agent: cache: id: my-cache-test strategy: read-write # 开发期自动读、自动更新read-write边跑边更新缓存适合日常开发read-only只读不写需要时手动agent.flushCache()适合生产write-only每次调模型并写缓存适合首次建库细节和回退机制见 缓存 AI 规划和定位。用 YAML 脚本描述跨端流程不想搭测试工程时一个.yaml文件就能跑完整流程page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - name: 检查结果 flow: - aiAssert: 结果中展示了天气信息目标端用page:或browser:声明换成android:、ios:、harmony:、computer:就是同一套tasks换平台执行agent段里还能配testId、aiActContext和上文说的缓存。完整字段说明在 使用 YAML 格式的自动化脚本。另外官方已推出面向未来的 Test RunnerBeta用自然语言驱动主线加可编程 Node新项目建议直接看 Test Runner 概览。桥接模式让本地脚本控制你正在用的 Chrome无头浏览器测试不了需要登录态、已有 cookies 或本机插件的页面。桥接模式让本地 Node 脚本通过 Midscene 插件接管桌面 Chrome——可以新建标签页也可以附着到当前标签页复用你浏览器里的一切状态。import { AgentOverChromeBridge } from midscene/web/bridge-mode; const agent new AgentOverChromeBridge(); await agent.connectNewTabWithUrl(https://www.bing.com); // 弹窗点 Allow 即可 await agent.ai(type AI 101 and hit Enter); await agent.aiAssert(there are some search results);注意模型环境变量要配在 Node 侧终端不是浏览器侧。YAML 脚本里只需给web段加bridgeMode: newTabWithUrl。因为复用了真实浏览器配置userAgent、viewportWidth、cookie等选项会被忽略跨机器使用时用allowRemoteAccess: true并自行做好网络隔离。完整说明见 Chrome 桥接模式。⚠️ 踩坑实录三个高频问题Android 已连接但点击报错SecurityException现象是adb devices里能看到设备执行tap却抛出INJECT_EVENTS permission相关异常。原因是手机上 USB 调试授权没给全。处理进开发者选项把「USB 调试」和「USB 调试安全设置」都打开重插数据线重新授权再adb devices -l确认。Chrome 插件报Cannot access a chrome-extension:// URL of different extension通常是另一个扩展往页面里注入了 iframe 或 script 与 Midscene 冲突。打开 DevTools 找到那个chrome-extension://开头的节点复制扩展 ID去chrome://extensions/禁用它刷新页面即可。本地 Ollama 模型返回 403插件跨源访问 Ollama 被拒。设置环境变量OLLAMA_ORIGINS*后重启 Ollama 即可。这三个问题的官方解答都在 快速开始 的 FAQ 里Android 连接排查见 Android 指南。下一步五条落地建议先在 Chrome 插件里把自然语言指令跑顺再写正式用例——指令措辞直接决定成功率开发期开read-write缓存同一流程第二次起执行明显变快CI 里换read-only给 Agent 加aiActContext把弹窗、登录页等常见干扰一次性交代清楚断言优先用aiAssert验证「用户看到的样子」颜色、高亮、布局而不是节点存在每次运行都打开生成的 HTML 报告步骤回放是定位偶发问题最快的入口平台差异和进阶能力自定义动作、与任意界面集成可以从 Android、与任意界面集成 两篇文档继续深入。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene.js 跨平台自动化测试实战：从零到可用的完整指南
Midscene.js 跨平台自动化测试实战从零到可用的完整指南【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个用视觉驱动来做 UI 自动化的测试框架它不读 DOM、不写选择器而是把当前界面截图交给多模态模型理解再用自然语言指令完成点击、输入、断言和数据提取。同一套 API 可以跑在 Web、Android、iOS、HarmonyOS 和桌面端也兼容 Canvas 渲染、原生 App 和跨域 iframe 这类传统选择器够不到的场景。读完这篇你会知道怎么配好模型跑通第一条指令怎么接进 Playwright以及缓存、YAML 脚本、Chrome 桥接模式这几个最实用的玩法。理解视觉驱动Midscene.js 和选择器测试差在哪传统 UI 测试的每一步都绑在选择器上CSS 类名一改、重构一次结构用例就批量挂掉纯图标按钮、Canvas 画面、原生 App 里根本没有语义化的节点更谈不上验证「界面上看起来对不对」——DOM 里存在某个节点不代表用户真的看得到它。Midscene.js 的思路反过来每一步只依赖截图。你用中文描述目标比如「点击登录按钮」「页面顶部显示导航栏」框架负责把它变成对界面上的具体操作。好处是维护成本低、覆盖面广能断言用户真实看到的颜色、高亮和布局状态。配置模型跑通第一条自动化指令上手最短路径是先装 Chrome 插件仓库里apps/chrome-extension/就是它的源码在侧边栏设置页粘贴模型配置然后直接输入自然语言指令验证效果。模型配置只需要四个必选项详见 模型配置参考export MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 export MIDSCENE_MODEL_API_KEYyour-api-key export MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 export MIDSCENE_MODEL_FAMILYdoubao-seedMIDSCENE_MODEL_FAMILY决定坐标的处理方式换模型时别漏。可选的高阶项里常用的是MIDSCENE_MODEL_RETRY_COUNT默认失败后重试 1 次和MIDSCENE_MODEL_TIMEOUT默认 180 秒的硬超时。完整支持列表见 支持的模型与配置。核心就三类 API先记住名字await agent.aiAct(点击登录按钮); // 规划并执行操作 const items await agent.aiQuery({name: string, price: number}[], 页面中的商品); // 提取结构化数据 await agent.aiAssert(页面顶部显示导航栏); // 断言界面状态在插件里验证过的指令可以直接用同样的 API 写进代码行为一致。集成到 Playwright测试用例里怎么用在已有 Playwright 项目里装midscene/web后把 Agent 挂到 page 上即可import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; import dotenv/config; const browser await chromium.launch({ headless: true }); const page await browser.newPage(); await page.goto(https://www.ebay.com); const agent new PlaywrightAgent(page); await agent.aiAct(type Headphones in search box, hit Enter); const items await agent.aiQuery({itemTitle: string, price: Number}[], find item in list and corresponding price);Android 端同理用midscene/android的AndroidDeviceAndroidAgent先getConnectedDevices()找到设备再device.connect()。一个实用技巧是给 Agent 传aiActionContext把「遇到权限弹窗点同意、遇到登录页跳过」这类业务背景告诉模型能显著减少跑偏。脚本跑完后控制台会打印Midscene - report file updated: .../some_id.html浏览器打开就是带截图和步骤回放的报告排障时直接看报告比翻日志快。⚡ 启用缓存让重复执行更快Midscene.js 会缓存两类内容AI 规划出的步骤所有平台通用以及元素的 XPath 定位信息仅 Web。命中缓存时跳过模型调用官方文档给出的示例里同一段流程的耗时从 51 秒降到了 28 秒查询类操作aiQuery、aiAssert等永不缓存保证每次断言都是实时结果。缓存文件落在./midscene_run/cache目录缓存失效会自动回退到模型重新分析。策略按环境选YAML 里这样配agent: cache: id: my-cache-test strategy: read-write # 开发期自动读、自动更新read-write边跑边更新缓存适合日常开发read-only只读不写需要时手动agent.flushCache()适合生产write-only每次调模型并写缓存适合首次建库细节和回退机制见 缓存 AI 规划和定位。用 YAML 脚本描述跨端流程不想搭测试工程时一个.yaml文件就能跑完整流程page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - name: 检查结果 flow: - aiAssert: 结果中展示了天气信息目标端用page:或browser:声明换成android:、ios:、harmony:、computer:就是同一套tasks换平台执行agent段里还能配testId、aiActContext和上文说的缓存。完整字段说明在 使用 YAML 格式的自动化脚本。另外官方已推出面向未来的 Test RunnerBeta用自然语言驱动主线加可编程 Node新项目建议直接看 Test Runner 概览。桥接模式让本地脚本控制你正在用的 Chrome无头浏览器测试不了需要登录态、已有 cookies 或本机插件的页面。桥接模式让本地 Node 脚本通过 Midscene 插件接管桌面 Chrome——可以新建标签页也可以附着到当前标签页复用你浏览器里的一切状态。import { AgentOverChromeBridge } from midscene/web/bridge-mode; const agent new AgentOverChromeBridge(); await agent.connectNewTabWithUrl(https://www.bing.com); // 弹窗点 Allow 即可 await agent.ai(type AI 101 and hit Enter); await agent.aiAssert(there are some search results);注意模型环境变量要配在 Node 侧终端不是浏览器侧。YAML 脚本里只需给web段加bridgeMode: newTabWithUrl。因为复用了真实浏览器配置userAgent、viewportWidth、cookie等选项会被忽略跨机器使用时用allowRemoteAccess: true并自行做好网络隔离。完整说明见 Chrome 桥接模式。⚠️ 踩坑实录三个高频问题Android 已连接但点击报错SecurityException现象是adb devices里能看到设备执行tap却抛出INJECT_EVENTS permission相关异常。原因是手机上 USB 调试授权没给全。处理进开发者选项把「USB 调试」和「USB 调试安全设置」都打开重插数据线重新授权再adb devices -l确认。Chrome 插件报Cannot access a chrome-extension:// URL of different extension通常是另一个扩展往页面里注入了 iframe 或 script 与 Midscene 冲突。打开 DevTools 找到那个chrome-extension://开头的节点复制扩展 ID去chrome://extensions/禁用它刷新页面即可。本地 Ollama 模型返回 403插件跨源访问 Ollama 被拒。设置环境变量OLLAMA_ORIGINS*后重启 Ollama 即可。这三个问题的官方解答都在 快速开始 的 FAQ 里Android 连接排查见 Android 指南。下一步五条落地建议先在 Chrome 插件里把自然语言指令跑顺再写正式用例——指令措辞直接决定成功率开发期开read-write缓存同一流程第二次起执行明显变快CI 里换read-only给 Agent 加aiActContext把弹窗、登录页等常见干扰一次性交代清楚断言优先用aiAssert验证「用户看到的样子」颜色、高亮、布局而不是节点存在每次运行都打开生成的 HTML 报告步骤回放是定位偶发问题最快的入口平台差异和进阶能力自定义动作、与任意界面集成可以从 Android、与任意界面集成 两篇文档继续深入。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考