Midscene.js 配置实操：设备接得进、用例跑得批、AI 成本压得低

Midscene.js 配置实操设备接得进、用例跑得批、AI 成本压得低【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene这是一份 Midscene.js 配置实操手册。读完后你能独立完成整套 AI UI 自动化测试环境装好工具链、写对 .env 模型配置、按测试目标选择 Android / iOS / 浏览器桥接三条接入通道之一、用并发参数批量跑 YAML 用例、开启缓存压低 AI 调用成本并在每次运行后拿到可视化 HTML 报告。先看到结果配置完成后你能驱动哪些场景这一节帮你建立预期确认这套配置最终能换来什么。用一句自然语言驱动 Android 真机或模拟器完成打开应用、点击、输入、断言通过 WebDriverAgent 接管 iOS 设备或模拟器执行同样的任务在已登录的桌面 Chrome 标签页上执行自动化不丢登录态、不干扰你手动操作一条命令并发执行一批互不依赖的 YAML 用例每次运行结束自动产出带步骤截图与断言结果的 HTML 报告一次性的环境准备装好工具链.env 四行写完模型配置这一节完成所有只做过一次的基础工作装依赖 配模型服务。先确认环境版本仓库要求 Node.js20.19 / 22.12 / 24、pnpm9.3git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene pnpm install # 安装依赖 pnpm build # 构建全部子包首次使用必须执行然后在工具运行目录创建.env。Midscene 用 dotenv 加载它所以行首不要写exportMIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 # 模型 API 地址 MIDSCENE_MODEL_API_KEY你的APIKey # 密钥错了 AI 全部功能失效 MIDSCENE_MODEL_NAME你的模型名称 # 具体模型 MIDSCENE_MODEL_FAMILY你的模型系列 # 模型家族决定提示词策略两个容易踩的点.env跟你在哪个目录跑命令绑定而不是跟 YAML 文件绑定同名变量已存在于全局环境时.env默认不覆盖可用--dotenv-override改变这一策略用--dotenv-debug观察加载过程。变量全集可查 模型配置文档。按目标选通道Android、iOS、浏览器桥接三种接入方式这一节回答我这次要测的东西在哪该走哪条通道三种方式并列对比。测试目标接入通道关键配置典型入口Android 真机/模拟器ADBMIDSCENE_ADB_PATH远端 adb 用MIDSCENE_ADB_REMOTE_HOST/PORTYAML 中android.deviceId取自adb devicesiOS 真机/模拟器WebDriverAgentMIDSCENE_IOS_DEVICE_UDID或MIDSCENE_IOS_SIMULATOR_UDIDYAML 中ios段指定设备桌面 Chrome 页面桥接模式安装 Midscene Chrome 插件Node 侧环境变量配模型脚本new AgentOverChromeBridge()Android先确保adb devices能看到设备USB 调试已开、已点信任。本地 adb 不在默认路径时MIDSCENE_ADB_PATH/opt/android-sdk/platform-tools/adb # 指向你机器上的 adbiOS先让 WebDriverAgent 跑起来再用 UDID 变量指定目标设备模拟器与真机用不同变量别混用。桥接模式让本地脚本直接操控你桌面上正在使用的 Chrome从而复用 cookies 和登录态脚本写在 Node 侧模型配置也必须在终端环境变量里而不是浏览器里import { AgentOverChromeBridge } from midscene/web/bridge-mode; const agent new AgentOverChromeBridge(); await agent.connectNewTabWithUrl(https://example.com); // 打开新标签页也可附着当前标签页 await agent.ai(搜索 Midscene 并回车); // 与普通 agent API 相同 await agent.aiAssert(出现了搜索结果); await agent.destroy();运行后扩展会弹确认框点 Allow 允许本次连接Always Allow 则永久放行。脚本写法与更多选项见 桥接模式文档。从单条用例到批量执行并发与超时配置这一节把跑一条 demo升级为跑一批用例且不超时失控。CLI 默认串行并发数 1批量执行时用--concurrent拉起来--files支持 glob# 4 路并发跑 cases 目录下一批互不依赖的用例 midscene --files cases/*.yaml --concurrent 4并发数别盲目拉满Web 用例吃内存移动用例受设备数量物理限制经验值是 Web 从 4 起步、每设备 1 条观察机器负载再调。超时只留一个关键变量即可它是 AI 请求的硬超时毫秒默认180000设0禁用MIDSCENE_MODEL_TIMEOUT180000 # 单个 AI 请求超过 180s 直接终止防止整批卡死多个 Web 用例共享同一个登录前置条件时把登录写进setup并设shareBrowserContext: true主脚本按并发数复用这套 cookies / localStorage不用每条都重新登录。速度与成本都要抓缓存策略与测试报告这一节同时解决两个问题重复的 AI 调用太贵太慢以及跑完不知道结果。缓存给 Agent 配置cache后相同指令在相似页面下会复用上次 AI 的规划与元素定位官方案例里同一脚本耗时从 51 秒降到 28 秒。agent: cache: id: my-cache-id # 读写模式首次写入 ./midscene_run/cache/*.cache.yaml后续命中注意边界aiBoolean/aiQuery/aiAssert这类查询断言永远不缓存缓存的规划运行时失败会自动回退重新规划调试期建议cache: false拿到实时结果。报告CLI 跑完每条用例会自动生成可视化 HTML 报告包含每步截图与断言结果无需额外配置MIDSCENE_REPORT_TAG_NAME可用于给报告加标记区分批次。踩坑问答Midscene.js 配置的高频问题问pnpm install 报 Node 版本不兼容怎么解决答部分执行路径依赖 Rspack 工具链会拒绝较旧的 Node 20 patch 版本。升级 Node 到20.19 / 22.12 / 24pnpm 到9.3重装依赖后重试。问adb 提示找不到设备或 Midscene 识别不到怎么办答先确认开发者选项里 USB 调试已开、手机上点了信任此计算机再跑adb devices确认状态是device而不是unauthorized。adb 不在默认路径就补MIDSCENE_ADB_PATH走远端 adb 则配MIDSCENE_ADB_REMOTE_HOST与MIDSCENE_ADB_REMOTE_PORT。问改了 .env 为什么没生效答三个高频原因文件没放在命令执行目录下行首写了exportdotenv 约定不允许同名变量已存在于全局环境.env默认不覆盖。加--dotenv-debug跑一次即可看到实际加载了哪些值。问桥接脚本运行后浏览器毫无反应答依次检查Chrome 插件是否启用且弹出了 Allow 确认框需要上传本地文件时要在插件 Details 里开启 Allow access to file URLs模型环境变量是否配在 Node 终端侧浏览器侧配置不生效。问AI 请求经常卡到很久才失败答这是硬超时没兜底。设MIDSCENE_MODEL_TIMEOUT默认 180 秒让卡死的请求被及时终止0表示禁用仅当你的链路特别慢时才考虑。收尾自检上线前过一遍pnpm build全部子包构建通过无报错.env四个模型变量填了真实值且文件位于命令执行目录adb devices能看到目标 Android 设备iOS 场景则 UDID 变量指向正确设备桥接脚本能收到扩展的 Allow 弹窗并成功接管标签页同一用例第二次执行时缓存命中耗时明显下降批量跑完后 HTML 报告正常生成能逐步查看截图与断言结果【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考