Midscene.js 完整指南：用自然语言写 Web 与移动端的 E2E 测试

Midscene.js 完整指南用自然语言写 Web 与移动端的 E2E 测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个面向 E2E 测试的开源 GUI AgentGUI 即图形界面Agent 指能自主规划并执行操作的智能体它用截图驱动多模态模型去理解和操作界面。你用自然语言描述任务它就能在 Web、Android、iOS、鸿蒙和桌面上做 UI 自动化。它到底能干什么Midscene.js 是一个视觉驱动的 UI 测试与自动化 SDK。它不依赖 DOM 结构或选择器而是基于截图理解界面核心能力有三点自然语言操作界面aiAct接收搜索耳机把第一个加入购物车这样的目标Agent 自己规划步骤、定位元素并执行完整个流程。一套 API 跨平台Web、Android、iOS、HarmonyOS、桌面端使用同一组aiAct、aiQuery、aiAssert等 API脚本基本可迁移。断言用户真正看到的内容颜色、高亮、布局、渲染状态都可以直接断言而不只是某个 DOM 节点存在与否。10 分钟跑通第一次 Midscene.js 自然语言指令最省事的入口是 Chrome 扩展官方称 Playground不需要初始化项目。第 1 步装扩展。从 Chrome Web Store 安装 Midscene 扩展打开后浏览器右侧出现侧边栏。第 2 步配模型。准备一个具备 UI 定位能力的多模态模型把配置粘贴到扩展设置里。以阿里云 Qwen 为例export MIDSCENE_MODEL_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 export MIDSCENE_MODEL_API_KEYyour-api-key export MIDSCENE_MODEL_NAMEqwen3.7-plus export MIDSCENE_MODEL_FAMILYqwen3仓库文档中列出的可用模型包括 Qwen、Doubao-Seed、GLM、Gemini、UI-TARS 等也支持自托管开源模型。第 3 步输入自然语言指令。打开任意页面在侧边栏输入三类指令之一操作Click the login button提取数据Products on the page, {name: string, price: number}[]检查界面A navigation bar appears at the top of the page执行后模型完成操作或返回结果运行过程会以报告形式逐步呈现。功能特写 桥接模式让本地脚本控制你正在使用的浏览器解决什么问题自动化启动的浏览器没有你的 cookies 和登录态测不了需要登录的场景。能做到什么本地 Node.js 脚本直连桌面版 Chrome复用全部 cookies、插件和页面状态属于典型的人在回路man-in-the-loop用法。怎么做到脚本发起连接时扩展弹出确认框点 Allow 后脚本里用的还是同一套 Agent APIimport { AgentOverChromeBridge } from midscene/web/bridge-mode; const agent new AgentOverChromeBridge(); await agent.connectNewTabWithUrl(https://www.bing.com); await agent.aiAct(type AI 101 and hit Enter);缓存机制把重复的 AI 调用省下来解决什么问题同一条指令反复执行时每次都调模型又慢又贵。能做到什么Midscene 以 prompt 为 key 缓存 AI 规划步骤Web 端还会缓存元素 XPath。官方文档给出的真实案例中一次任务执行时间从 51 秒降到 28 秒。怎么做到创建 Agent 时一行配置缓存文件落在./midscene_run/cacheconst agent new PuppeteerAgent(page, { cache: { id: my-cache-id }, // 默认 read-write 模式 });两个边界要注意aiQuery、aiAssert等查询类结果从不缓存保证实时性XPath 定位缓存对 Canvas、跨域 iframe、关闭模式的 Shadow DOM、WebGL 不可用缓存失效时会自动回退到 AI 定位不需要你手动兜底。一个真实场景三行 YAML 跑通搜索 E2E 测试 Midscene 自带 YAML 脚本格式和 CLI不写一行代码。先建.env放在运行命令的目录下写入模型四件套MIDSCENE_MODEL_BASE_URL你的模型服务URL/v1 MIDSCENE_MODEL_API_KEY你的API Key MIDSCENE_MODEL_NAME你的模型名 MIDSCENE_MODEL_FAMILY你的模型系列再写bing-search.yamlpage: url: https://www.bing.com tasks: - name: Search for weather flow: - ai: Search for todays weather - sleep: 3000 - aiAssert: The results show weather information然后执行npm i -g midscene/cli midscene ./bing-search.yamlCLI 实时打印执行进度结束后在midscene_run/report/目录生成可视化报告逐步回放每步截图与断言结果。YAML 里还能用${变量名}引用环境变量用 glob 批量执行一组脚本。想换平台把page:块换成android:配deviceId或ios:配wdaPort即可任务流写法不变。卡住了高频问题CLI 报Unsupported Node.js versionRspack 工具链拒绝了较旧的 Node 20 补丁版本。解法升级到 Node.js 20.19、22.12 或 24 后重装依赖。扩展报Cannot access a chrome-extension:// URL of different extension通常是别的扩展向页面注入了 iframe 或 script 造成冲突。解法在开发者工具里按扩展 ID 找到来源扩展禁用后刷新页面。Ollama 本地模型返回 403扩展访问被 Ollama 默认来源策略拦住了。解法设置环境变量OLLAMA_ORIGINS*。CI 上缓存不命中缓存文件没随仓库走。解法把midscene_run/cache提交进仓库并确认页面结构与缓存生成时一致。数据与边界仓库文档中公布的真实基准数据基准结果评测配置AndroidWorldPass1 93.10%Midscene 1.9.5Gemini-3.5-FlashMobileWorldPass1 78.63%92/117Midscene 1.10.3Gemini-3.6-Flash缓存案例同一任务执行时间从 51 秒降至 28 秒。也要清楚它不适合的场景追求单步毫秒级响应的流水线aiAct每次执行都要调模型规划耗时和 token 成本更高动作确定的单步操作应改用aiTap、aiInput这类即时交互 API。截图不能外发的敏感环境Midscene 的核心输入就是截图个别场景还会附带 DOM需评估数据隐私或使用可自托管的开源模型。要求成本绝对确定缓存只是加速手段DOM 变化会使其失效并回退到 AI模型调用预算仍需保留。下一步去哪快速上手与扩展配置apps/site/docs/en/quick-start.mdxPlaywright 集成指南apps/site/docs/en/integrate-with-playwright.mdx缓存完整配置与 FAQapps/site/docs/en/caching.mdx核心引擎 Agent 层源码packages/core/src/agent/先按上面的 Bing 搜索 YAML 在真实页面跑通一遍再把同样的三步配模型、写脚本、看报告搬到你自己的测试目标上就是最顺的上手路线。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考