Midscene.js 配置实战指南从环境搭建到生产级调优的 AI 自动化测试全流程【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一款 AI 驱动的 UI 自动化测试工具GUI Agent for E2E Testing你用自然语言描述操作它自动完成点击、输入、断言。本文按「运行时环境 → 设备连接 → 执行策略 → 输出可观测 → 跨平台」的配置分层带你在 10 分钟内跑通第一条 AI 自动化测试并拿到一套可直接用于 CI 的调优参数。跑通之后你能得到一份.env、一条midscene命令、一个可并发批次的执行配置、一套省 AI 调用成本的缓存策略以及 HTML JSON 报告。第一层运行时环境——安装 CLI 并配置模型Midscene.js 环境搭建分三步确认 Node 版本、安装 CLI、写.env。CLI 执行链路依赖 Rstest/Rspack 工具链Node.js 必须是20.19、22.12或2420.17.0这类旧 patch 版本会被直接拒绝。新手推荐全局安装 CLI如果想从源码跑比如贡献代码再走仓库克隆路线# 路线一快速上手推荐 npm i -g midscene/cli # 路线二源码方式参与开发时使用 git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene pnpm install最小可运行配置midscene命令用 dotenv 加载.env文件。下面的配置解决模型服务在哪、密钥是什么、用哪个模型三个问题# .env 必须放在 CLI 执行目录下不是 YAML 所在目录 MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 # 模型服务地址 MIDSCENE_MODEL_API_KEYyour-api-key # 你的 API Key MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 # 模型名称 MIDSCENE_MODEL_FAMILYdoubao-seed # 模型系列决定适配逻辑配好之后一个最小 YAML 脚本加一条命令就能跑midscene ./bing-search.yaml命令行会输出执行进度并在完成后自动生成可视化报告。[!TIP].env里不要写export前缀dotenv 约定它默认不覆盖全局同名环境变量可用--dotenv-override修改。怀疑没生效时加--dotenv-debug看加载日志。模型参数怎么选四个变量里最容易踩坑的是MIDSCENE_MODEL_FAMILY。它不是给模型看的名字而是告诉 Midscene 按哪套逻辑适配这个模型包括坐标处理、UI 定位策略。选错会直接报MIDSCENE_MODEL_FAMILY is not set to a multimodal model with UI localization。常用模型的 family 对照模型MIDSCENE_MODEL_FAMILY豆包 Seed 2.xdoubao-seed千问 Qwen3qwen3DeepSeekdeepseekGeminigeminiGPT-5gpt-5GLM-Vglm-v选模型的思路先按你的密钥供应商锁定MIDSCENE_MODEL_NAME和BASE_URL再对照上表填 family三者必须成套。第二层设备与目标连接——Android、iOS、浏览器桥接模式Midscene 的 UI 自动化支持三类目标Android 真机/模拟器、iOS 设备、浏览器。连接方式在 YAML 里声明三端对比如下目标端连接方式YAML 关键配置路径/端口要点 Androidadb USB 调试android.deviceId设备 ID 由adb devices查询 iOSWebDriverAgent (WDA)ios.wdaPort/ios.wdaHostWDA 默认端口8100 浏览器无头 Puppeteer / CDP / 桥接模式page.url/page.cdpEndpoint/page.bridgeMode桥接 Server 默认127.0.0.1:3766Android ADB 连接三步走手机开启 USB 调试设置 → 开发者选项连上电脑并确认信任提示确保adb在 PATH 中adb devices能看到设备且状态为device把设备 ID 写进 YAMLandroid: deviceId: s4ey59 # adb devices 输出的设备序列号 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索按钮iOS WDA 连接WebDriverAgent 需要预先构建并在设备上跑起来Midscene 通过 HTTP 端口与它通信ios: wdaPort: 8100 # WDA 默认端口非本机 WDA 时配 wdaHost 浏览器桥接模式桥接模式Bridge Mode让本地脚本直接接管你桌面上已登录的 Chrome复用 cookies、插件和页面状态——这是手动登录一次自动化跑一百次的关键也常被称作 man-in-the-loop。配置步骤在 Chrome 应用商店安装 Midscene 扩展装好后后台持续监听图标黄点监听中、绿点已连接→ 安装依赖npm i midscene/web tsx --save-dev→ 写脚本。最小示例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();脚本运行后扩展会弹确认窗点 Allow 授权本次连接。YAML 场景下只需在page里加bridgeMode: newTabWithUrl复用当前页则填currentTab。跨机器部署时可用new AgentOverChromeBridge({ allowRemoteAccess: true })监听0.0.0.0:3766仅限可信网络使用。[!TIP] 桥接模式下MIDSCENE_MODEL_API_KEY等模型配置要写在**终端Node.js 侧**环境变量里不是浏览器侧。另外userAgent、viewportWidth、cookie等页面选项在桥接模式下会被忽略因为复用的是你真实浏览器的配置。第三层执行策略——并发参数与缓存策略单脚本跑通后真正的效率问题出现在批量执行几十个 YAML 串行跑要等一夜反复调同一个 AI 模型又贵又慢。这一层解决两个问题吞吐量怎么调、缓存怎么省。⚡ 吞吐量怎么调CLI 用--concurrent控制并发、--retry控制失败重试参数还能落到一个 YAML 配置文件里让 CI 复现同一套执行策略# config.yaml批量执行的并发与重试策略 files: - ./scripts/search-*.yaml # glob 匹配所有搜索脚本 concurrent: 4 # 并发数建议不超过 CPU 核心数脚本必须互不依赖 continueOnError: true # 单个失败不阻塞批次 retry: 2 # 失败脚本的额外尝试次数缓解偶发失败midscene --config ./config.yaml两条硬规则concurrent: 1时按files列表顺序执行大于 1 时执行顺序不确定脚本不得依赖彼此的启动/完成顺序。若多个脚本共享登录态用setup前置脚本 shareBrowserContext: true复用 BrowserContext仅限 Puppeteer Web 场景。缓存怎么省Midscene 的缓存策略分四种strategyread-write默认、read-only、write-only以及cache: false禁用。它缓存的是AI 规划步骤和Web 元素的 XPath 定位Canvas、跨域 iframe、closed Shadow DOM 等无稳定 DOM 的场景除外。官方实测中缓存命中让同一脚本执行耗时从 51 秒降到 28 秒# 在 YAML 脚本中开启缓存 agent: cache: id: search-flow # 缓存标识脚本间互相隔离 strategy: read-write # 读旧缓存自动写回CI 生产环境建议 read-only缓存文件落在./midscene_run/cache目录.cache.yaml扩展名。页面变了缓存会自动失效并回退 AI 重新规划所以它不会把脚本焊死在旧页面上。想定期瘦身用agent.flushCache({ cleanUnused: true })清理未命中的记录。[!TIP] 查询类操作aiAssert、aiQuery、aiBoolean永不缓存需要实时结果时放心用它们。CI 里缓存不命中把./midscene_run/cache提交到仓库——没有缓存文件命中率永远是 0。第四层输出与可观测性——报告与运行结果AI 自动化测试的可观测性核心是三样东西每个步骤的截图、AI 调用记录、缓存命中提示。Midscene 执行完成后会在输出目录里生成三类产物--summary指定的 JSON 汇总报告默认index.json整批脚本的执行状态与统计每个 YAML 对应的独立 JSON 执行结果每个脚本一份 HTML 可视化报告步骤截图、AI 输入输出、耗时、缓存命中都会标注在对应步骤上。把汇总报告指到固定路径方便 CI 归档midscene --files ./scripts/*.yaml --summary ./reports/summary.json --headed # --headed 仅 Web 场景打开有界面浏览器便于肉眼验收排查偶发失败时直接打开对应脚本的 HTML 报告定位到失败步骤查看当时的截图和模型返回批量对比各脚本耗时与状态则看summary.json。报告与缓存统一放在./midscene_run/目录下清理时整体移除即可。横切关注点跨平台适配一份配置多端复用Midscene 调用的是 PATH 中的adb、按wdaHost/wdaPort连接 WDA、按page配置驱动浏览器——也就是说它不绑定操作系统路径。跨平台的差异集中在各 OS 上工具装在哪用一段脚本收口后业务 YAML 一行都不用改这就是一份配置、多端复用// ci/device-paths.js按操作系统生成本地工具路径 import os from os; const platform os.platform(); export const devicePaths { win32: { adb: C:\\Android\\Sdk\\platform-tools\\adb.exe, chrome: C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe, }, darwin: { adb: ~/Library/Android/sdk/platform-tools/adb, chrome: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome, }, linux: { adb: /usr/local/android-sdk/platform-tools/adb, chrome: /usr/bin/google-chrome, }, }[platform];差异点WindowsmacOSLinuxadb 常见路径C:\Android\Sdk\platform-tools~/Library/Android/sdk/platform-tools/usr/local/android-sdk/platform-tools需额外注意装 Platform Tools 后加进 PATHiOS WDA 需 Xcode 签名构建无头浏览器依赖系统字体库原则设备路径差异放 CI 脚本层MIDSCENE_MODEL_*与业务 YAML 保持在同一份配置里三端行为一致。排障速查与上线前验收清单Top 5 常见报错报错/现象根因解法Unsupported Node.js versionRspack 抛出Node 版本低于工具链要求升级到 20.19 / 22.12 / 24重装 CLIMIDSCENE_MODEL_FAMILY is not set to a multimodal model...family 未设置或不是 UI 定位多模态模型按模型对照表成套填四个MIDSCENE_MODEL_*.env改了不生效放错目录或写了export前缀放到 CLI 执行目录去掉export--dotenv-debug验证桥接模式脚本无响应扩展未安装或确认窗没点 Allow装扩展并等待黄点弹窗点 Allow 后重试CI 中缓存永不命中缓存默认禁用 / 仓库里没有缓存文件配agent.cache.id提交./midscene_run/cache到仓库上线前验收清单Node 为 20.19/22.12/24midscene命令可执行.env四项模型配置齐全首条脚本跑通并生成 HTML 报告adb devices能识别 Android 设备deviceId已写入 YAMLWDA 已构建启动ios.wdaPort默认 8100可连通Chrome 扩展已安装桥接确认窗可正常 Allow--concurrent按 CI 机器规格设置依赖顺序的脚本保持concurrent: 1agent.cache.id已配置缓存文件已提交仓库summary.json与各脚本 HTML 报告可正常打开归档【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考