Midscene.js 完整教程用自然语言驱动 AI 自动化测试浏览器与手机【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene每次前端重构一次测试脚本就跟着崩一次选择器到处改、原生 App 根本摸不到、canvas 上的内容谁也看不见——这是 UI 自动化最磨人的地方。Midscene.js 换了一条路让 AI 只看截图干活你用一句人话告诉它点什么、查什么它就替你点。这套视觉驱动的 E2E 测试框架下面带你从零跑通。Midscene.js 能替你干的活从 Web 到手机桌面先搞懂它的核心思路。传统自动化依赖 DOM 和无障碍树页面结构一改选择器就失效。Midscene 不看结构只看屏幕截图。只要人眼能看到的按钮它就能定位。它提供三个核心动作覆盖你日常 90% 的测试需求aiAct用自然语言描述交互比如点击登录按钮AI 自己规划并执行aiQuery从界面提取结构化数据比如把所有商品和价格抓成 JSONaiAssert校验用户真正看到的效果颜色、高亮、布局都能断言更关键的是同一套 API 覆盖 Web 浏览器、Android、iOS、HarmonyOS 和桌面端。你在浏览器里验证过的指令换到手机上几乎原样可用。前置准备拉代码、装依赖、确认版本打开终端先拿到项目代码git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene然后用 pnpm 安装依赖pnpm install装之前先确认版本满足要求Node 需要 20.19.0 以上或 22.12.0 以上、24 以上pnpm 需要 9.3.0 以上。用node -v和pnpm -v各看一眼不满足就先升级否则后面构建会莫名其妙报错。配好模型给 Midscene 装上 AI 大脑Midscene 本身不内置模型需要你给它指一个具备 UI 定位能力的多模态模型。通过四个环境变量配置MIDSCENE_MODEL_BASE_URL服务地址、MIDSCENE_MODEL_API_KEY密钥、MIDSCENE_MODEL_NAME模型名、MIDSCENE_MODEL_FAMILY模型家族。以豆包 Seed 为例把 Base URL 填成火山引擎的地址模型名填doubao-seed-2-1-turbo系列family 填doubao-seed即可。想换千问、GLM、Gemini 或自托管开源模型如 UI-TARS也行具体取值查支持的模型与配置。一个实用建议调试阶段先用响应快的轻量模型跑通流程后再换成精度更高的模型做正式测试。第一次跑通在 Chrome 插件里输入第一句指令最快的上手方式不是写代码而是装 Chrome 插件把任意网页变成 Playground。去 Chrome 应用商店安装 Midscene 插件打开扩展列表里的 Midscene浏览器右侧会弹出侧边栏。点侧边栏的设置图标把前面那组模型配置粘贴进去保存。然后打开任意网页在侧边栏输入符合当前页面的指令比如点击登录按钮。AI 会先看一眼页面截图理解布局然后替你执行。这一步验证的就是aiAct能力跑通了说明模型配置没问题。插件里验证过的指令之后都能原封不动搬进脚本agent.aiAct(点击登录按钮)一行代码搞定。实战场景让 AI 在安卓手机上自动查商品浏览器跑通后试试真机。以 Android 为例整个过程分三步。第一步连好设备。手机开启开发者选项里的 USB 调试有的机型还有USB 调试安全设置一并打开数据线连上电脑。终端里跑adb devices -l看到设备序列号就说明 adb 认得它。第二步启动 Playground。一条命令npx --yes midscene/android-playground窗口里点齿轮按钮粘贴你的 API Key 配置保存。现在你可以在界面上用自然语言驱动手机不用写一行代码。第三步升级成可复用脚本。安装midscene/android和dotenv两个依赖后写一个脚本先通过getConnectedDevices()拿到设备创建AndroidAgent然后依次aiAct打开浏览器、aiQuery提取商品和价格、aiAssert断言列表存在。最后npx tsx demo.ts运行。Android 端的环境变量配置入口长这样脚本跑完控制台会提示报告文件已生成。用浏览器打开那个 HTML每个步骤的截图、耗时、操作结果都能回看进阶用桥接模式控制你正在用的真实浏览器前面两种方式要么开新浏览器、要么依赖插件侧边栏。还有一种更贴近真实使用场景的玩法桥接模式。本地 Node 脚本通过 Chrome 插件直接接管桌面版 Chrome 的标签页。好处是复用你浏览器里已有的 cookies、登录态和插件脚本不用再走一遍登录流程。做法安装midscene/web脚本里创建AgentOverChromeBridge调用connectNewTabWithUrl指定要打开的地址剩下的aiAct、aiAssert和普通 Agent 完全一样。运行后插件会弹一次确认窗点 Allow 即可以后可以选始终允许。注意模型配置要写在 Node 侧的环境变量里不是浏览器侧。新手最容易踩的四个坑一次讲清坑一adb 认不出手机。九成是 USB 调试没开全或者电脑缺驱动。先开USB 调试安全设置再跑adb devices -l复验。手机上如果弹出授权框记得点允许。坑二插件报Cannot access a chrome-extension:// URL of different extension。这是别的扩展和 Midscene 抢页面了。打开开发者工具找到 URL 以chrome-extension://开头的注入脚本复制扩展 ID到扩展管理页禁用它刷新页面重试。坑三响应慢、调用贵。两个思路。一是把ai(Click Login Button)换成即时操作aiTap(Login Button)少一轮规划二是开缓存。配置cache: { id: my-cache-id }后相同指令在相似页面会直接复用上次结果案例里执行时间从 51 秒降到 28 秒缓存文件落在midscene_run/cache目录命中失败会自动回退到重新调模型不影响正确性。详见缓存文档。坑四点了个寂寞坐标偏移。某些模型服务商比如 Azure 上的 GPT-5会缩放大图导致定位偏移调 Agent 的screenshotShrinkFactor预先缩小截图即可规避。下一步先把最小示例跑起来别急着搭完整体系先做一件最小的事今天就装好 Chrome 插件配置好模型输入一句点击登录按钮看 AI 替你点下去。跑通之后再按顺序推进按快速开始把第一条指令验证到位选一个平台Web 或 Android写一个三行的aiAct脚本看报告回放把重复跑的流程配上缓存观察耗时变化更多能力iOS、HarmonyOS、桌面端、YAML 脚本都在官方文档里照着平台指南一步步做就行。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考