Midscene.js AI视觉UI自动化测试：5分钟跑通你的第一个E2E用例

Midscene.js AI视觉UI自动化测试5分钟跑通你的第一个E2E用例【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene给前端项目做端到端测试选择器总在下一次改版后集体失效而 Canvas 画布、跨域 iframe 里的内容传统工具根本看不见。本文带你用 5 分钟上手 Midscene.js写一段 YAML让 AI 纯靠视觉驱动浏览器跑通你的第一条测试用例并讲清楚它背后的工作方式和常见坑。 为什么需要它选择器的尽头现状是选择器与 DOM 强绑定UI 一重构就要跟着改脚本维护量随版本滚雪球无语义标记的元素纯图标按钮、自绘控件、canvas对选择器完全不可见原生 App 和跨域 iframe 更是直接超纲。Midscene.js 的解法是把定位依据换成截图它不解析 DOM多模态模型直接看界面你只用自然语言描述每一步。换 UI 渲染技术、换平台脚本措辞基本不动还能校验用户实际看到的颜色、高亮和布局。对比项选择器/无障碍树路线Midscene 纯视觉路线元素定位依据DOM 结构界面截图无语义元素图标按钮、Canvas不可见人眼能看见就能点跨平台Web/Android/iOS/桌面各平台不同技术栈同一套 API视觉效果校验颜色、布局不支持支持依赖的模型能力普通 LLM 即可需支持 UI 定位的多模态模型 能力总览本节帮你判断它适不适合你的场景先扫一遍功能面再决定往哪深入。功能一句话说明适合场景aiAct自然语言操作描述目标AI 自主规划、定位并执行多步操作业务流程回归、复杂多步任务aiQuery/aiBoolean从界面提取结构化数据或布尔结论抓价、校验状态aiAssert用一句话断言界面呈现E2E 断言YAML 脚本运行器一条midscene xxx.yaml命令跑完整流程并出报告CI、无人值守测试多平台适配Web、Android、iOS、HarmonyOS、桌面共用一套 API多端同测⏱️ 五分钟上手安装 Midscene CLI 与写第一个 YAML 脚本本节目标装好命令行工具跑通一个浏览器用例。前提Node.js 20.19 / 22.12 / 24以及一个支持 UI 定位的多模态模型可自托管也可用云端服务。全局安装 CLI约 1 分钟npm i -g midscene/cli在运行命令的目录下建.env填好模型配置注意midscene命令读的是运行目录不是 YAML 所在目录MIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY你的Key MIDSCENE_MODEL_NAME模型名 MIDSCENE_MODEL_FAMILY模型系列新建search.yaml用自然语言描述用例page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息执行并查看报告midscene ./search.yaml跑完终端会打印进度并生成包含每步截图与耗时的可视化报告。如果不想写代码也可以先装 Chrome 扩展版 Playground 零配置体验⚙️ 它是怎么工作的截图进、操作出这一节帮你建立心智模型出问题时知道该怀疑哪一环。纯视觉定位执行每条指令前先截一张当前界面交给模型回答目标元素在哪。不读 DOM所以 Canvas、原生 App、跨域 iframe 都在射程内代价是模型必须选对——需要 UI 定位能力较强的多模态模型如 UI-TARS、Qwen 系列视觉模型普通文本 LLM 不行。模型组合策略见 packages/core/src/ai-model/。任务规划与执行Agent 把一句话指令拆成步骤定位后执行再用新的截图判断是否达成。多步任务会基于最新界面状态持续修正计划。核心循环在 packages/core/src/agent/入口agent.ts。脚本运行与报告CLI 把 YAML 编译成执行计划每步的截图、耗时、成败都会写进报告文件失败时可逐步回看AI 当时看到了什么。 实战3 个高频场景本节给你可直接套用的片段全部来自该项目自身的典型用法。场景 1接入现有 Playwright 项目。在现有用例里注入视觉能力不用重写整套框架import { PlaywrightAgent } from midscene/web/playwright; const agent new PlaywrightAgent(page); await agent.aiAct(type Headphones in search box, hit Enter); const items await agent.aiQuery( {itemTitle: string, price: number}[], 列出商品和价格, ); await agent.aiAssert(列表第一件商品价格低于 600);场景 2移动端真机测试。接好 adb 后同一个 YAML 换平台字段就能驱动 Android 设备例如查设置里的系统版本、在地图 App 发起导航Playground 与 API 写法一致文档见 apps/site/docs/zh/platforms/。场景 3视觉回归断言。传统断言只能判断节点存在Midscene 可以断言呈现侧栏导航高亮是否正确、空态插画是否出现、深色模式下配色是否正常——一句话aiAssert就是一条视觉回归用例。 进阶技巧与避坑指南本节收集新手最常踩的几个坑按现象→原因→做法给出对策。现象重复用例越来越慢模型账单上涨。原因每条指令都完整走一遍规划定位。做法给 Agent 开cache: true相同指令在相似页面会直接复用缓存的规划与定位结果官方文档案例里执行时间从 51 秒降到 28 秒缓存文件落在./midscene_run/cache失效时自动回退重新分析。现象小图标、密集列表点偏。原因默认单次定位在视觉特征弱的元素上不够稳。做法对单个调用传deepLocate: true多一轮模型调用换定位精度复杂多步任务再考虑deepThink。现象.env配好了命令仍提示没有模型。原因dotenv 只读运行命令的目录与 YAML 文件位置无关。做法确认.env和midscene命令在同一目录拿不准时加--dotenv-debug看加载过程。现象换了模型后定位乱飞或直接报错。原因模型本身不具备稳定的 UI 定位能力。做法按文档换回受支持的多模态模型先用 Playground 单条验证再上长流程。❓ 常见疑问本节回答新手问得最多的几个问题。Q1Midscene 必须联网吗不必须。接自托管的开源视觉模型如 UI-TARS可以离线跑用云端模型服务则联网。Q2YAML 脚本和 TypeScript API该选哪个无人值守、CI 批量执行选 YAML要嵌进已有测试框架、需要精细控制时选PlaywrightAgent等 API。Q3能直接替换现有 Playwright 用例吗不必替换。Playwright 继续负责打开页面、管理浏览器Midscene 负责看懂并操作两者在同一用例里混用即可。Q4执行速度怎么样每步都要截图调用模型比选择器点击慢缓存命中后重复执行明显变快。简单页面单步通常几秒到十几秒。Q5支持哪些平台浏览器、Android、iOS、HarmonyOS 和桌面端共用一套 API仓库里 packages/ 下按平台分了模块可对照查看。Q6失败了怎么排查打开生成的报告逐步看每步截图、耗时和 AI 的推理先把指令单独在 Playground 里跑通再放回长流程。✅ 结语三步行动清单今天装好midscene/cli配好.env用上面那个search.yaml让midscene命令跑通打开报告确认每步截图符合预期。本周在现有 Playwright 项目里挑一个最易碎的选择器用一条aiAct和一条aiAssert替换它开启cache: true对比前后耗时。之后从报告里挑一条 AI 没理解到位的指令改措辞重跑稳定后把 YAML 用例放进 CI。延伸阅读apps/site/docs/zh/quick-start.mdx、apps/site/docs/zh/test-runner-overview.mdx、apps/site/docs/zh/model-strategy.mdx。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考