Midscene.js快速上手指南用自然语言驱动跨平台UI自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene你每周都要验证一遍登录、搜索、下单这条核心链路而每次前端重构后总有一批基于 CSS 选择器的用例悄悄失效。Midscene.js 是另一个思路不碰页面结构只靠屏幕截图驱动多模态大模型执行操作、提取数据和断言结果Web、Android、iOS、HarmonyOS、桌面应用共用同一套 Agent API天然适配 E2E 测试场景。没有 Midscene.js 之前有了 Midscene.js 之后定位元素手写选择器重构后批量失效一句自然语言指向元素覆盖范围纯图标按钮、canvas、原生应用够不到人眼能看到的界面都能操作校验结果只能查 DOM 节点是否存在能断言颜色、高亮、布局等视觉状态换平台Web 和移动端两套技术栈同一套aiAct/aiQueryAPI 跨平台失败排查日志里一串断言失败信息可视化报告逐步回放每一步它的做法很直接给模型一张当前界面的截图加一句自然语言目标模型自己规划步骤、找到目标元素坐标并执行循环直到目标完成。等于把看懂屏幕这件事外包给了多模态模型。3步完成Midscene.js环境搭建环境准备只做三件事全程用 npm安装 CLI要求 Node.js 20.19 / 22.12 / 24npm i -g midscene/cli在运行目录放一个.env配置多模态模型。以通义千问为例MIDSCENE_MODEL_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAMEqwen3.7-plus MIDSCENE_MODEL_FAMILYqwen3写一个 YAML 脚本并执行page: url: https://www.bing.com tasks: - name: 搜索并验证 flow: - ai: 在搜索框搜索 todays weather - sleep: 3000 - aiAssert: 结果页展示了天气信息midscene ./smoke.yaml执行结束后终端会打印Midscene - report file updated: /path/to/report/xxx.html用浏览器打开这个文件可以逐步回放每一次操作、查询和断言失败时能直接定位到具体截图。按使用场景看Midscene.js能做什么三个贴近日常的场景先看它替你省了什么。场景一给经常改动的页面做回归冒烟页面每周都在改选择器用例维护成本最高。用 YAML 写冒烟脚本改动页面只改自然语言描述不用追选择器tasks: - name: 核心链路冒烟 flow: - ai: 点击右上角登录按钮 - aiInput: 测试账号 - aiAssert: 登录后显示用户名 - aiAssert: 顶部导航包含订单入口跑完后断言失败会直接抛错并带上模型的判断理由冒烟结论一目了然。场景二从渲染界面里提取结构化数据运营让你统计一屏商品的价格元素可能画在 canvas 里、没有任何 DOM 语义。aiQuery直接对着截图提数据返回类型由你在提示词里约束const items await agent.aiQuery { itemTitle: string; price: number }[] ( 页面列表中的商品字段为 {itemTitle: string, price: number}, ); console.log(items); // 直接得到结构化数组可写入表格注意aiQuery的结果永不被缓存每次都是实时读屏适合拿现在的数据。场景三驱动真机做移动端自动化同一套 Agent API 也作用于 Android 真机。下面这段脚本让设备打开浏览器并检查页面全程只靠自然语言import { AndroidAgent, AndroidDevice, getConnectedDevices } from midscene/android; const devices await getConnectedDevices(); const device new AndroidDevice(devices[0].udid); const agent new AndroidAgent(device); await device.connect(); await agent.aiAct(打开浏览器并访问 bing.com); await agent.aiAssert(页面显示了搜索框);运行后手机上会看到真实的点击与输入动作报告里同步记录每一步的设备截图。端到端案例一次可交付的登录流程验证以验证登录后落地页正确为例走完从配置到交付的闭环。第 1 步环境与脚本。按上面三步准备好.env和 YAML 脚本。⚠️ 注意.env由 dotenv 解析不要加export前缀值直接写KEYvalue否则整份配置会被静默跳过。第 2 步执行并观察。用midscene ./login-smoke.yaml跑脚本。AI 规划步骤默认不缓存调试阶段行为可预期确认稳定后在agent段加cache: { id: login-smoke }重复执行会命中缓存官方示例里同一场景执行时间从 51 秒降到 28 秒。第 3 步交付物就是报告。脚本产出的 HTML 报告无需任何额外配置把文件路径发给协作方即可双击就能逐步回放。// 需要嵌入现有工程时脚本里直接建 Agent 也可以 const agent new PlaywrightAgent(page, { cache: { id: login-smoke }, // 开启读写缓存 }); await agent.aiAct(在登录页输入账号密码并提交); await agent.aiAssert(页面显示欢迎回来); // 断言失败会抛出带理由的错误 关键转折报告不是生成成功/失败一句话而是每一步的截图、提示词与模型决策。评审用例争议时直接回放报告比口头争论快得多。高频问题速查现象根因解法启动即报Unsupported Node.js versionCLI 部分执行路径依赖 Rstest/Rspack 工具链拒绝了过旧的 Node 20 补丁版本升级 Node.js 到 20.19 / 22.12 / 24重装 CLI模型报错但配置看起来正确.env里写了export前缀dotenv 按自己的格式解析直接跳过删掉export写成MIDSCENE_MODEL_NAMExxx可用--dotenv-debug确认加载过程Android 点按报SecurityException: INJECT_EVENTS设备开发者选项未完全开启确认 USB 调试已开启且设备处于解锁状态重新执行device.connect()接入你的现有工具链接入 Playwright 用例用 fixture 扩展后现有用例里直接拿aiAct、aiQuery、aiAssertimport { test as base } from playwright/test; import { PlaywrightAiFixture } from midscene/web/playwright; import type { PlayWrightAiFixtureType } from midscene/web/playwright; export const test base.extendPlayWrightAiFixtureType(PlaywrightAiFixture());同时在playwright.config.ts的 reporter 里加上[midscene/web/playwright-reporter]多条用例会合并成一份可视化报告CI 里只需保留这个 HTML 产物。接入 CI/CDYAML 脚本天然适合流水线一条命令跑完并落报告midscene ./login-smoke.yaml把报告文件路径归档到 CI 制品即可团队成员无需装任何依赖就能查看回放。另外 Midscene 还提供 Chrome 扩展与 Bridge 模式在扩展里验证过的自然语言指令可以原样搬进 SDK 代码。延伸资源官方文档仓库内源码apps/site/docs/en/integrate-with-playwright.mdx与platforms/android.mdx值得优先读Agent API 参考apps/site/docs/en/reference/aiAct/aiQuery/aiAssert的全部参数核心 Agent 与模型适配实现packages/core/src/agent/与ai-model/两个目录Playwright/Puppeteer 集成层packages/web-integration/src/YAML 脚本执行器packages/cli/src/选一个你这周重复最多的界面操作花 5 分钟写一条ai:指令跑通它再决定要不要把整套用例迁过来。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考