如何安装 Midscene CLI、配置 .env 并运行第一个 Web YAML 自动化脚本

如何安装 Midscene CLI、配置 .env 并运行第一个 Web YAML 自动化脚本【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene这篇文章解决一个具体任务在本地环境装好 Midscene 的命令行工具midscene/cli通过.env文件配置一个支持 UI 定位的多模态模型然后运行你的第一个针对 Web 页面的 YAML 自动化脚本。完成后的结果是midscene命令打开浏览器执行脚本、在终端打印执行进度、并生成 HTML 可视化报告。前提只有一项运行midscene的终端必须使用 Node.js20.19、22.12或24。CLI 的部分执行路径使用 Rstest/Rspack 工具链会拒绝20.17.0这类较旧的 Node 20 patch 版本。安装 CLI全局安装官方文档推荐首次使用者使用npm i -g midscene/cli也可以在单个项目内安装装好后通过npx调用npm i midscene/cli --save-dev两种方式的区别只在于后面运行脚本时用midscene还是npx midscene功能相同。配置 .env 模型参数CLI 使用 dotenv 加载.env文件文件必须放在运行midscene命令的目录下不一定与 YAML 文件同目录。每个值对应你的模型服务MIDSCENE_MODEL_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 MIDSCENE_MODEL_API_KEY你的 API Key MIDSCENE_MODEL_NAMEqwen3.7-plus MIDSCENE_MODEL_FAMILYqwen3上面是文档中给出的阿里云 Qwen 示例MIDSCENE_MODEL_API_KEY替换为你自己的 Key。四个变量的含义Base URL 是模型服务地址API Key 是凭证Model Name 是模型名Model Family 决定 Midscene 如何适配该模型。使用其他模型如 Doubao、GLM、Gemini、GPT-5时按 Supported models and setup 中的表格替换这四个值MIDSCENE_MODEL_FAMILY必须与所选模型系列匹配。写.env时的规则每行不要加export前缀——dotenv 按KEYvalue格式读取。默认情况下shell 中已存在的同名环境变量优先于.env的值需要.env覆盖时加--dotenv-override参数。环境变量加载有问题时可用--dotenv-debug查看调试日志。验证模型连接配置完成后先跑一次连通性检查而不是直接跑完整脚本# 当前项目已安装 midscene/cli 时 npx midscene model verify # 未安装或想用最新版时 npx midscene/clilatest model verify该命令检查模型连通性和 Midscene 兼容性读取当前工作目录的.env并且是少数会用.env的值覆盖 shell 同名变量的命令调试时以.env内容为准。如果model verify通过说明模型配置无误。文档同时提供了用curl直接请求${MIDSCENE_MODEL_BASE_URL%/}/chat/completions的方法若 curl 成功而 verify 失败说明 API 可达问题在模型能力或 Midscene 配置继续对照 Model debugging and observability 排查。编写第一个 Web YAML 脚本在当前目录创建bing-search.yamlpage: url: https://www.bing.com tasks: - name: Search for weather flow: - ai: Search for todays weather - sleep: 3000 - aiAssert: The results show weather information脚本由三部分组成page段声明目标网页url是必填项tasks是任务数组每个任务带name和flow步骤列表。ai是aiAct的简写用自然语言描述交互sleep: 3000等待 3 秒aiAssert执行断言不满足时脚本报错。更多可用的 flow 步骤aiTap、aiInput、aiQuery、aiWaitFor、javascript等见 Automate with scripts in YAML。注意Web 场景默认以 headless无界面方式运行浏览器。运行脚本并查看结果midscene ./bing-search.yaml # 项目内安装时 npx midscene ./bing-search.yaml执行期间 CLI 在终端打印执行进度结束后生成可视化报告。成功标志是脚本走完tasks中所有 flow 步骤、aiAssert断言通过、输出目录中出现报告文件。执行后的输出目录包含--summary指定的 JSON 汇总默认index.json含所有脚本的执行状态和统计每个 YAML 文件各自的执行结果JSON每个脚本的可视化 HTML 报告。HTML 报告是最直观的验证材料里面记录了页面截图、每一步 AI 决策和断言结果。常用可选参数参数用途--headed以有界面模式运行可以看到浏览器窗口仅 Web 场景--keep-window执行结束后保留浏览器窗口自动启用--headed--concurrent number并发执行数默认1--continue-on-error某个脚本失败后继续执行剩余脚本默认关闭--retry number失败脚本的额外重试次数默认0--dotenv-debug打印 dotenv 加载调试日志--dotenv-override允许.env覆盖 shell 中已有的同名环境变量想看浏览器实际执行过程时用midscene ./bing-search.yaml --headed即可。常见问题Rspack 报Unsupported Node.js versionNode.js 版本低于要求如20.17.0。升级 Node.js 到20.19、22.12或24然后重装全局 CLI 或项目依赖。MIDSCENE_MODEL_FAMILY is not set to a multimodal model with UI localizationMIDSCENE_MODEL_FAMILY未设置为支持 UI 定位的多模态模型系列对照 Supported models and setup 的表格修正。模型请求 404 或找不到模型确认MIDSCENE_MODEL_BASE_URL指向提供商的 API 端点通常以/v1之类的版本段结尾且不要手动追加/chat/completion——底层 SDK 会自动拼接请求路径。同时确认MIDSCENE_MODEL_NAME是该端点上真实可用的模型名。限制与下一步文档将 CLI 的 YAML 脚本执行标注为 legacy YAML automation 方案它适合编写并快速运行单脚本自动化对于新的测试项目官方提供了处于 Beta 阶段的 Midscene Test见 Midscene Test overview。脚本本身支持通过${variable-name}引用.env中的环境变量也支持 glob 批量执行如midscene ./scripts/**/*.yaml需要组织多脚本套件时参考 YAML script runner 的完整命令行选项说明。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考