Midscene.js 上手3 行自然语言驱动 E2E UI 测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene每次改完前端页面测试脚本里的选择器又全炸了——改个 className一连串 E2E 用例跟着红。Midscene.js 走的是另一条路它是一套视觉驱动的 GUI Agent你用自然语言写搜索耳机把价格筛到 100 美元以下它自己截图、看懂屏幕、找到该点的位置再动手操作。一句话定位它是看屏幕而不是读 DOM的自动化框架。传统 E2E 框架靠 CSS 选择器定位页面一重构脚本就跟着死Midscene.js 把截图交给多模态模型由模型回答该点哪里、该填什么。纯图标按钮、canvas 画出来的内容、跨域 iframe 里的元素只要人眼看得见它就摸得到。同一套 API 覆盖 Web、Android、iOS、HarmonyOS 和桌面应用。跑通第一个最小示例 三步就能跑起来。第一步安装依赖npm install midscene/web playwright tsx --save-dev。第二步在.env里写一组模型配置MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_FAMILY模型选一个带视觉能力的。第三步写个demo.ts用npx tsx demo.ts运行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 the search box and hit Enter); await agent.aiWaitFor(there is at least one headphone item on page); await agent.aiAssert(there is a category filter on the left);三行agent.开头的代码就是核心aiAct规划并执行多步操作aiWaitFor等待页面状态aiAssert对着屏幕上看得见的东西做断言。跑完后midscene_run目录会生成一份 HTML 报告每一步做了什么、断言结果如何都能回放。如果想先不写代码试手感Chrome 插件是最快的入口装好插件把模型配置粘进设置在侧边栏直接输入自然语言看效果。指令措辞在插件里调顺了原样搬进脚本就行不用重新学一套说法。底层机制截图、识别、操作的循环它的循环和人用软件的方式很像截当前屏幕 → 多模态模型理解界面、给出目标元素的位置和外观描述 → Midscene 把位置换算成真实的点击、输入、滚动 → 操作完再截图检查是否符合预期。整个过程不把 DOM 树发给模型所以页面是 React 还是 Vue、类名多乱都不影响它工作视觉识别和任务规划的核心实现在packages/core/src/ai-model/目录。有一个细节值得说透模型返回的是坐标不是选择器。页面结构怎么改只要那个按钮还在、长得还像用例就不会挂。反过来说这套机制的上限取决于模型的视觉能力这也是后面踩坑部分的主要来源。实战用法桥接模式控制真实浏览器无头浏览器有两个场景不太够用需要登录态或者要复用你已装好的插件状态。桥接模式解决的正是这个——本地脚本附着到你实际在用的桌面 Chrome页面状态就是你眼前看到的样子自动化领域管这叫 man-in-the-loop。注意模型配置要写在 Node 侧的终端环境变量里而不是浏览器侧import { AgentOverChromeBridge } from midscene/web/bridge-mode; const agent new AgentOverChromeBridge(); await agent.connectNewTabWithUrl(https://www.bing.com); await agent.ai(type AI 101 and hit Enter); await agent.aiAssert(there are some search results);实现代码在packages/web-integration/src/bridge-mode/API 和普通 Agent 是同一套脚本可以放心来回切换。每次运行都会产出一份交互式 HTML 报告每一步的截图、元素定位框、AI 的决策过程、操作和断言结果都记下来了。用例挂了不用对着日志猜打开报告直接看是哪一步模型看错了。大概率会踩的坑 定位偏了点错地方。这是最常见的问题按顺序排查提示词从功能性描述改成视觉性描述。aiTap(个人中心)让模型猜哪个图标是它aiTap(页面右上角的人形头像图标)让模型按外观匹配后者稳定得多目标是小图标时开启deepLocate多花一次模型调用把位置磨准await agent.aiTap(登录按钮, { deepLocate: true });换更大、更新版本的视觉模型同时检查MIDSCENE_MODEL_FAMILY是否和实际模型一致配错了适配逻辑会整个跑偏。跑得太慢、token 太贵。流程固定且稳定时用aiTap、aiInput这类即时操作代替aiAct——后者每一步都在重新规划时间和 token 都更贵。对反复跑的脚本给 Agent 配置cache: { id: my-cache }开启缓存缓存文件落在midscene_run/cache命中时跳过模型调用官方案例里执行耗时从 51 秒降到 28 秒。但要明白缓存只是加速器页面一变它照样回退到 AI 重新分析。CI 里小元素认不出。CI 默认 dpr 往往是 1截图偏糊小图标容易失手。把浏览器 dpr 提到 2小元素定位通常会明显改善代价是 token 消耗变高。延伸与进阶 Web 上跑顺之后下一步通常是移动端。同一套 Agent API 可以直接搬到 Android、iOS、HarmonyOS 和桌面端对应源码在packages/android/、packages/ios/、packages/harmony/、packages/computer/每个平台都配了 Playground 可以先试再写脚本。几个公开的评测数字可以帮你建立预期AndroidWorld 的 Pass1 是 93.1%AppControlBench 60 个任务通过 58 个官方用 Doubao Seed 2.1 Turbo 跑完 AppControlBench 全程模型调用总费用 0.59 美元——成本这条基本可控。想把它当成工程来管可以看看 Midscene Testmidscene/testBetaUI 流程和预期结果写在 YAML 里API 调用、数据准备和清理封装成可复用的 TypeScript 节点框架自带重试、并发和生命周期钩子源码在packages/test/。中文文档在仓库的apps/site/docs/zh/下basics.mdx讲 API 选型faq.md覆盖了大部分常见问题。给个上手顺序先在 Chrome 插件里把指令措辞调顺再搬进 Playwright 脚本跑通最后才考虑缓存和工程化——这个顺序最省弯路。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考