#YAML 脚本运行器

Midscene 定义了一种 YAML 格式的脚本，方便开发者快速编写自动化脚本，并提供了对应的命令行工具来快速执行这些脚本。

举例来说，你可以编写如下 YAML 格式脚本示例：

page:
  url: https://www.bing.com

tasks:
  - name: 搜索天气
    flow:
      - ai: 搜索 "今日天气"
      - sleep: 3000
      - aiAssert: 结果显示天气信息

并通过一条命令来执行它：

midscene ./bing-search.yaml

命令行会输出执行进度，并在完成后生成可视化报告。整个运行过程大幅简化了开发者做环境配置的复杂度。

本文将介绍如何使用 Midscene 的命令行工具。关于更多 YAML 格式脚本的内容，可以参考 使用 YAML 格式的自动化脚本。

#使用 .env 配置环境变量

Midscene 命令行工具使用 dotenv 来加载 .env 文件。你可以在工具运行目录下创建一个 .env 文件，并添加以下配置：

MIDSCENE_MODEL_BASE_URL="https://替换为你的模型服务地址/v1"
MIDSCENE_MODEL_API_KEY="替换为你的 API Key"
MIDSCENE_MODEL_NAME="替换为你的模型名称"
MIDSCENE_MODEL_FAMILY="替换为你的模型系列"

更多配置信息请参考模型策略文档。

请注意：

• 这个文件不是必须的，你也可以通过全局环境变量的形式来配置
• 请注意这里没有 export 前缀，这是 dotenv 库的约定
• .env 文件必须放置在工具运行目录下，而与 YAML 文件所在的目录无关。
• 这些变量默认是不覆盖全局环境变量中已经的同名变量的，如需修改这个策略，请参考后文“--dotenv-override” 参数
• 如需调试此部分环境变量的逻辑，可使用 --dotenv-debug 参数

#开始使用

#安装命令行工具

安装 CLI 前，请确认运行 midscene 的终端使用 Node.js 20.19+、22.12+ 或 24+。CLI 的部分执行路径会使用 Rstest/Rspack 工具链，这些依赖会拒绝 20.17.0 这类较旧的 Node 20 patch 版本。如果看到 Rspack 抛出的 Unsupported Node.js version 提示，请升级 Node.js 后重新安装全局 CLI 或项目依赖。

全局安装 @midscene/cli （推荐新手使用）：

npm i -g @midscene/cli

或在项目中按需安装

npm i @midscene/cli --save-dev

#编写第一个脚本

编写一个名为 bing-search.yaml 的文件来驱动 Web 浏览器：

page:
  url: https://www.bing.com

tasks:
  - name: 搜索天气
    flow:
      - ai: 搜索 "今日天气"
      - sleep: 3000
      - aiAssert: 结果显示天气信息

驱动已连接 adb 的 Android 设备：

android:
  deviceId: s4ey59 # device id 可以在 adb 命令行中通过 `adb devices` 命令获取

tasks:
  - name: 地图导航
    flow:
      - ai: 打开地图应用
      - ai: 在搜索栏输入 "杭州西湖"，然后点击搜索按钮
      - ai: 点击第一个搜索结果，进入详情页
      - ai: 点击 "路线" 按钮，进入路线规划页面
      - ai: 点击 "开始" 按钮开始导航

或者驱动配置好 WebDriverAgent 的 iOS 设备：

ios:
  wdaPort: 8100

tasks:
  - name: 修改系统设置
    flow:
      - ai: 打开设置应用
      - ai: 点击 "显示与亮度"
      - ai: 开启 "深色模式"
      - aiAssert: 深色模式已开启

#运行脚本

midscene ./bing-search.yaml
# 如果在项目中安装了 Midscene
npx midscene ./bing-search.yaml

命令行会输出执行进度，并在完成后生成可视化报告。

#命令行工具的高级用法

#在 .yaml 中使用环境变量来填入动态值

脚本中可以通过 ${variable-name} 引用环境变量。环境变量会在 YAML 任务执行前完成替换，包括任务正文中的字符串。

topic=weather today

# ...
- ai: 在输入框中输入 ${topic}
# ...

#运行多个脚本

@midscene/cli 支持使用通配符匹配多个脚本来批量执行脚本，这相当于 --files 参数的简写。

# 运行单个脚本
midscene ./bing-search.yaml

# 使用通配符模式运行所有匹配的脚本
midscene './scripts/**/*.yaml'

#分析命令行运行结果

执行完成后，输出目录会包含：

• --summary 指定的 JSON 报告（默认 index.json），记录所有脚本的执行状态与统计数据。
• 每个 YAML 文件对应的独立执行结果（JSON 格式）。
• 每个脚本生成的可视化报告（HTML 格式）。

#运行在可视化（Headed）模式

仅适用于 Web page 场景

Headed 模式会打开浏览器窗口。默认情况下脚本在无头模式运行。

# 运行在 headed 模式
midscene /path/to/yaml --headed

# 运行在 headed 模式并在结束后保留窗口
midscene /path/to/yaml --keep-window

#使用 CDP 连接模式

仅适用于 web 场景

CDP 模式可以让 YAML 脚本通过 Chrome DevTools Protocol 连接到已有的浏览器实例，无需启动新浏览器。适用于需要复用已有浏览器会话、连接远程浏览器或云端浏览器服务的场景。

在 page 配置中设置 cdpEndpoint：

page:
  url: https://www.bing.com
+ cdpEndpoint: ws://localhost:9222/devtools/browser

#使用桥接模式

仅适用于 Web page 场景

使用桥接模式可以让 YAML 脚本驱动现有的桌面浏览器，便于复用 Cookies、插件或已有状态。先安装 Chrome 扩展，然后在 page 配置中加入：

page:
  url: https://www.bing.com
+ bridgeMode: newTabWithUrl

更多细节请参阅 通过 Chrome 插件桥接模式。

#使用 JavaScript 运行 YAML 脚本

调用 Agent 的 runYaml 方法同样可以在 JavaScript 中执行 YAML，注意该方法只会运行脚本中的 tasks 部分。

#命令行参数

命令行工具提供了多项参数，用于控制脚本的执行行为：

• --files <file1> <file2> ...：指定脚本文件列表。默认按顺序执行（--concurrent 为 1），可通过 --concurrent 设置并发数量。支持 glob 通配符语法；当 glob 或目录匹配到多个文件时，匹配结果会按文件路径的字典序排序后加入执行列表。
• --setup <file>：在主 --files 之前执行的前置脚本。它与主脚本共享同一个浏览器上下文，因此在这里建立的前置状态（如登录态）对每个主脚本都可见。前置脚本失败会中止整个批次，主脚本将被标记为未执行。需要配合 --share-browser-context 使用。
• --concurrent <number>：设置并发执行的数量，默认 1。
• --continue-on-error：启用后，即使某个脚本失败也会继续执行后续脚本。默认关闭。
• --retry <number>：失败脚本的重试次数。每一轮只会重新执行上一轮失败的脚本，可缓解网络波动或大模型输出不稳定导致的偶发失败。默认 0。（与 --share-browser-context 同时使用时不生效，该模式下所有脚本共享同一次执行。）
• --share-browser-context：在多个脚本之间共享浏览器上下文（Cookies、localStorage 等），适合需要连续登录态的场景。默认关闭。
• --summary <filename>：指定生成的 JSON 总结报告路径。
• --headed：在带界面的浏览器中运行脚本，而非默认的无头模式。
• --keep-window：脚本执行完成后保持浏览器窗口，会自动开启 --headed 模式。
• --config <filename>：指定配置文件，文件中的参数会作为命令行参数的默认值。
• --web.userAgent <ua>：设置浏览器 UA，覆盖所有脚本中的 web.userAgent。
• --web.viewportWidth <width>：设置浏览器视口宽度，覆盖所有脚本中的 web.viewportWidth。
• --web.viewportHeight <height>：设置浏览器视口高度，覆盖所有脚本中的 web.viewportHeight。
• --android.deviceId <device-id>：设置安卓设备 ID，覆盖所有脚本中的 android.deviceId。
• --ios.wdaPort <port>：设置 WebDriverAgent 端口，覆盖所有脚本中的 ios.wdaPort。
• --ios.wdaHost <host>：设置 WebDriverAgent 主机地址，覆盖所有脚本中的 ios.wdaHost。
• --dotenv-debug：开启 dotenv 的调试日志，默认关闭。
• --dotenv-override：允许 dotenv 覆盖同名的全局环境变量，默认关闭。

示例：

使用 --files 指定执行顺序：

midscene --files ./login.yaml ./buy/*.yaml ./checkout.yaml

以 4 个并发执行多个互不依赖的搜索脚本，并在出错时继续运行：

midscene --files './scripts/search-*.yaml' --concurrent 4 --continue-on-error

#通过文件编写命令行参数

可以把参数写到 YAML 配置文件中，并通过 --config 引用。命令行传入的参数优先级高于配置文件。

files:
  - './scripts/search-iphone.yaml'
  - './scripts/search-laptop.yaml'
  - './scripts/search-headphones.yaml'
  - './scripts/search-camera.yaml'

concurrent: 4
continueOnError: true
retry: 2

运行方式：

midscene --config ./config.yaml

#在并行脚本之前执行前置任务

当多个互不依赖的脚本都依赖同一个前置条件（例如登录）时,可以把前置任务写在 setup 下。前置脚本会在主 files 之前执行;成功后,主脚本再按配置的并发数运行。前置脚本与主脚本共享同一个浏览器上下文,因此登录态会被带过去。setup 需要配合 shareBrowserContext: true 使用。

setup: ./scripts/login.yaml

files:
  - ./scripts/search.yaml
  - ./scripts/report.yaml
  - ./scripts/settings.yaml

shareBrowserContext: true
concurrent: 3

如果前置脚本失败,整个批次会被中止,主脚本将被标记为未执行。

#常见问题

如何导出 JSON 格式的 Cookies？

可以借助 Chrome 扩展 导出 Cookies。

如何查看 dotenv 的调试日志？

使用 --dotenv-debug 参数即可：

midscene /path/to/yaml --dotenv-debug=true