Midscene.js 快速上手指南：视觉驱动的 AI 自动化测试，一套 API 搞定跨端自动化

Midscene.js 快速上手指南视觉驱动的 AI 自动化测试一套 API 搞定跨端自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene选择器脚本一改页面就失效同一流程还得为网页、安卓各写一遍。Midscene.js 是一款视觉驱动的 AI 自动化测试框架Agent 读屏幕截图用自然语言定位元素并执行操作同一套 API 跨平台可用跨端自动化不再依赖选择器。本文基于仓库真实模块与文档讲清环境搭建、跑通第一个用例、三种驱动方式选型与高频故障排查。一、上手前你需要什么1. 确认 Node 环境与包管理器准备 Node 18 环境包管理器用 npm 或 pnpm 均可。本仓库本身是 pnpm workspace根目录有pnpm-workspace.yaml若你要改源码在仓库根执行pnpm install若只是使用框架直接安装对应的 npm 包即可不需要构建整个 monorepo。2. 配置模型 API KeyMidscene 要求一个具备 UI 定位能力的多模态模型。最小配置是四个环境变量export MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 export MIDSCENE_MODEL_API_KEYyour-api-key export MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 export MIDSCENE_MODEL_FAMILYdoubao-seed以上以豆包为例your-api-key换成自己的密钥。Qwen、GLM、Gemini 等模型的环境变量写法见 model-common-config.mdx全部配置项见 model-config.mdx。3. 模型怎么选框架支持Qwen3.x、Doubao-Seed、GLM-4.6V、gemini-flash、UI-TARS等模型也支持自托管的开源模型。建议先固定一个模型跑通全流程再按需调整学习阶段选响应快的轻量模型正式回归选定位更稳的模型。规划模型与视觉模型是否拆开配置见 model-strategy.mdx。二、五分钟跑通第一个用例1. 克隆仓库并安装依赖git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene pnpm install2. Web 端最短路径Chrome 插件从 Chrome 应用商店安装 Midscene 插件打开扩展侧边栏把上一节的模型配置粘贴到设置页保存。之后在任意网页的侧边栏输入自然语言指令例如点击登录按钮Agent 会理解页面、规划并执行。完整步骤见 quick-start.mdx。3. 移动端最短路径启动 Android Playground先在手机开发者选项中开启 USB 调试用数据线连接电脑执行adb devices -l确认设备出现在列表中。然后启动 Playgroundnpx --yes midscene/android-playground在 Playground 窗口的齿轮按钮处粘贴 API Key 配置输入框里输入打开浏览器搜索 eBay。Playground 与midscene/android共享同一份实现在 Playground 验证通过的指令写进脚本后行为一致。4. 怎么判断跑通了执行成功后控制台会输出Midscene - report file updated: /path/to/report/id.html。用浏览器打开该 HTML即可回放每一步的截图与结果。到这一步环境搭建已完成。三、三种驱动方式怎么选方式适用场景入口Playground 交互验证指令措辞、新手上手Chrome 插件、npx midscene/android-playgroundAPI 驱动纳入测试工程、CI 定时回归midscene/web、midscene/android等 SDK跨端桥接模式复用本地浏览器的登录态与 cookiesmidscene/web/bridge-mode1. API 驱动把 Playground 验证过的指令写进代码import { PlaywrightAgent } from midscene/web/playwright; const agent new PlaywrightAgent(page); await agent.aiAct(Search for headphones, filter under $100); await agent.aiWaitFor(The filtered search results are displayed); await agent.aiAssert(Every product price is below $100);aiAct负责自主流程aiWaitFor等待界面状态aiAssert做视觉断言可与 Playwright、Puppeteer 或现有用例框架组合。2. 跨端桥接模式怎么配桥接模式让本地 Node 脚本直接控制桌面 Chrome能复用浏览器里已有的 cookies、插件和页面状态。脚本运行后插件会弹出确认窗口点击 Allow 即建立连接。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); await agent.destroy();YAML 脚本里只需加两行web下设置bridgeMode: currentTab附着当前标签页或newTabWithUrl新开标签页再执行midscene ./bing.yaml。注意桥接模式下模型配置要写在 Node.js 侧的终端环境变量里而不是浏览器扩展设置中。实现位于 bridge-mode 源码。四、从编写用例到查看报告1. 自然语言指令的四种写法aiAct(在搜索框输入 Headphones 并回车)规划并执行交互aiWaitFor(至少出现一个耳机商品)等待条件成立aiAssert(左侧有分类筛选)按视觉判断结果aiQuery({itemTitle: string, price: Number}[])提取结构化数据。四类 API 的用途区别见 basics.mdx完整参数见 API 参考。2. 运行用例npx tsx demo.ts # JavaScript SDK 脚本 midscene ./script.yaml # YAML 自动化脚本YAML 写法web声明目标地址、tasks描述流程见 automate-with-scripts-in-yaml.mdx。3. 执行轨迹怎么读运行结束后生成 HTML 报告按时间线展示每步的截图、元素定位框、AI 决策过程以及动作与断言结果每个 AI 步骤都记录输入、输出、耗时和状态。排查失败时先定位报告里失败的那一步再看该步截图与断言文案通常能直接判断是定位偏差还是业务逻辑不符合预期。报告生成逻辑在 report-generator.ts。五、调优与稳定性1. 用缓存压缩重复执行耗时给 Agent 传cache: { id: my-cache-id }即启用缓存默认 read-write 策略缓存文件落在./midscene_run/cache/*.cache.yaml。缓存覆盖aiAct的规划结果和 Web 端的元素 XPath 定位aiQuery、aiAssert等查询类操作永不缓存规划缓存执行失败时自动回退到模型重新规划。官方文档给出的对照同一用例从 51 秒降到 28 秒。策略细节read-only 需手动flushCache()、write-only 用于重建缓存见 caching.mdx。2. 多设备管理用adb devices -l核对在线设备脚本里通过getConnectedDevices()取设备列表连远程 adb 服务时设置MIDSCENE_ADB_PATH、MIDSCENE_ADB_REMOTE_HOST、MIDSCENE_ADB_REMOTE_PORT同一主机并发设备不宜过多按业务分配任务避免截图与模型调用争抢资源scrcpy 投屏默认只监听 127.0.0.1确需远程访问时用MIDSCENE_PLAYGROUND_HOST0.0.0.0显式开启且只放在可信网络。3. 高频问题速查设备已连接却无法操作报SecurityException: INJECT_EVENTS确认USB 调试安全设置已开启。输入文本后被清空keyboardDismissStrategy: back-first仍不行则autoDismissKeyboard: false。英文文本被输入法改写imeStrategy: always-yadb。本地 Ollama 报 403设置OLLAMA_ORIGINS*。AI 响应慢先换轻量模型再开缓存最后排查网络。以上条目来自 Android 平台 FAQ 与 通用 FAQ遇到其他报错可先在这两篇里按错误信息检索。六、深入与扩展1. 用 YAML TypeScript Node 写工程化用例midscene/testBeta把声明式测试意图与可编程工程分开UI 流程写 YAML接口调用、数据准备、清理逻辑封装成可复用的 TypeScript Node一个退款用例可以接口下单、UI 发起退款、再视觉验证结果源码在 packages/test/。2. 扩展 Agent 能力用defineAction()定义自定义动作并传入设备配置Agent 规划时即可调用你定义的业务动作如连续点击五次适合沉淀领域特定操作。3. 源码与文档入口Agent 核心与报告packages/core/src/agent/、packages/core/src/Web 与桥接实现packages/web-integration/src/移动端packages/android/src/中文文档apps/site/docs/zh/含平台指南、模型配置、参考手册基准数据README 报告 AndroidWorld Pass1 93.1%、AppControlBench 96.7%详细运行配置见 android-world-benchmark-report.mdxMidscene.js 把 UI 测试从维护选择器变成读懂屏幕同一套自然语言指令可在 Web、Android 等端复用。克隆仓库后先跑一条 Playground 指令再对照 HTML 报告核对每一步你就完成了第一套 AI 自动化测试的闭环。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考