#运行测试

#基本用法

在项目根目录下运行以下命令，即可执行项目中的 YAML 测试用例：

pnpm exec midscene-test

#指定用例目录或文件

脚手架生成的项目默认通过 files.include 匹配 cases/ 目录下的 .yaml 和 .yml 文件。如果配置文件中未声明 files，Midscene Test 会递归查找测试根目录下的所有 YAML 文件（自动忽略 node_modules 和 .git）。

在命令行中传入目录或文件路径时，请留意测试根目录（Test Root）的变化及其对路径解析的影响：

• 测试根目录的确定：未传路径参数时，测试根目录为当前工作目录；传入目录参数时，测试根目录变为该目录；传入单个文件时，测试根目录变为该文件所在的目录。
• 相对于测试根目录解析：默认配置文件查找（仅在测试根目录下查找，不会向上级目录回溯）、--config 参数路径，以及配置中的 files.include / files.exclude。
• 相对于当前工作目录解析：--result-dir 参数路径。

因此，当 midscene.config.ts 位于项目根目录、而你只想运行 cases/ 子目录下的单个文件时，需要显式传入 --config（注意它相对于目标文件所在的 cases/ 目录解析）：

pnpm exec midscene-test ./cases/order.yaml --config ../midscene.config.ts

直接指定单个文件时，该文件不受 files.include / files.exclude 规则限制，但 tags 筛选依然生效。如果你想只运行某个子目录（如 cases/smoke），建议仍在项目根目录下运行命令，并通过在配置中将 files.include 设置为 cases/smoke/**/*.{yaml,yml} 来限定范围，避免因指定子目录而改变测试根目录。

#过滤执行项目与指定配置文件

如果工程中配置了多个平台或运行环境，可以通过 --project 指定只运行特定的执行项目（Project），也可以通过 --config 指定自定义配置文件：

# 仅运行名为 android-smoke 和 ios-regression 的执行项目
pnpm exec midscene-test --project android-smoke --project ios-regression

# 使用指定的配置文件运行测试
pnpm exec midscene-test --config ./config/midscene.config.ts

为特定执行项目生成 Node 说明书时，同样可以使用 --project 参数：

pnpm exec midscene-test nodes --project android-smoke

#输出与退出码

#终端输出模式

默认情况下，终端按用例（Case）维度汇总打印执行结果。如果需要查看每个步骤的详细诊断信息，可以使用 --reporter verbose 参数。运行 --help 可以查看所有支持的命令行选项：

# 查看详细的步骤诊断信息
pnpm exec midscene-test --reporter verbose

# 查看所有命令行选项
pnpm exec midscene-test --help

#结果文件与报告路径

每次运行都会生成两类产物，具体路径以终端末尾打印的 Summary: 和 Report: 为准：

• 结构化结果文件：默认写入测试根目录下的 .midscene/test-results/<runId>/，包含供程序读取的 summary.json 和便于阅读的 result.md。你可以通过 --result-dir 修改结果根目录（每次运行仍会在其下创建独立的 <runId> 子目录）：

  pnpm exec midscene-test --result-dir ./test-results
  注意：summary.json 的字段结构可能随版本演进，外部工具消费时请以当前版本的实际输出为准。
• HTML 可视化报告：测试运行结束后可在浏览器中直接打开。报告中完整记录了用例执行结果、每一步的界面截图、输入输出参数、报错堆栈以及 Agent 视觉执行回放，方便快速定位问题。输出目录由配置文件中的 output.reportDir 控制（默认生成在 midscene_run/report/ 目录下），与结构化结果目录相互独立。

#退出码

你可以根据 CLI 退出码判断整次测试运行是否成功：

• 0：所有选中用例及生命周期钩子均执行成功。
• 1：运行过程中出现错误（包括用例步骤失败、YAML 解析或收集阶段报错、项目级或文件级生命周期报错等）。即使所有用例步骤均通过，若清理阶段发生异常，退出码同样为 1。

#报告归档与 URL 深度链接

#报告归档

报告默认生成为单文件 HTML：midscene_run/report/midscene-e2e-<runId>.html。如果启用了外置截图模式，产物目录中会包含 index.html 与 screenshots/ 文件夹，在 CI 中归档或上传产物时请务必保留整个目录。在 CI 中配置报告归档的方式请参阅在 GitHub Actions 中运行。

#链接到指定步骤（URL Hash）

在 CI 通知、群告警或 PR 评论中分享报告时，可以通过 URL Hash 参数 runner-step 直接定位并高亮目标步骤。除了传入具体的 Step ID 外，还支持以下通用选择器：

示例：直接打开报告中最后一个失败步骤：

https://example.com/report/index.html#runner-step=last-error

若该步骤包含 Agent 视觉回放详情，还可追加 runner-trace=page 直接以全屏模式展开 Agent 执行详情：

https://example.com/report/index.html#runner-step=last-error&runner-trace=page

如需限定在特定用例范围内定位，可配合 runner-page=case、runner-project=<projectId> 与 runner-case=<caseKey> 路由参数使用。参数值分别取报告内部的 projectId 和复合 Case Key <projectId>:<documentId>:<caseId>，并进行 URL 编码（例如使用 URLSearchParams）。获取这些值时，可以先在报告中打开目标用例并复制其 URL，再追加 runner-step 及所需的 runner-trace 参数。

#加载环境变量

Midscene Test 从系统环境变量（process.env）中读取模型配置与运行参数。你可以根据使用场景选择合适的方式注入环境变量：

#本地开发：使用 .env 文件

• 脚手架生成的项目（开箱即用）：通过 midscene-test create 创建的项目，已在 midscene.config.ts 顶部配置了 dotenv。你只需在项目根目录下创建 .env 文件并填入配置，即可直接生效。
• 手写配置文件：如果是手动创建的配置文件，需在 midscene.config.ts 顶部显式引入 dotenv：

  import 'dotenv/config';

通过 dotenv 加载时，当前 Shell 中已有的同名环境变量优先于 .env 文件中的值。

#CI / CD 环境

在持续集成（如 GitHub Actions）或自动化流水线中，通常无需创建 .env 文件，直接将密钥或配置注入为流水线系统环境变量即可。

#模型连通性检查（model verify）

运行 midscene-test model verify 排查模型连接时，该命令会自动读取当前工作目录下的 .env 文件。为了方便即时验证本地文件中的配置，该命令会优先采用 .env 中的值（覆盖同名 Shell 环境变量）。排查问题时，请确保 .env 中的配置与测试运行时所用的模型设置一致。

#在 GitHub Actions 中运行

Midscene 提供了官方的 midscene-action，用于在 GitHub Actions 中运行 Midscene Test 并管理测试产物：

• 自动将测试执行结果汇总到 GitHub Actions 工作流的 Summary 页面。
• 将 HTML 测试报告与结果数据打包保存为 Artifacts，方便下载排查。
• 支持按需将测试报告发布到 Cloudflare Workers，生成在线预览链接。

关于完整的配置参数与进阶用法，请参阅 GitHub Marketplace 上的 midscene-action 文档。