#运行测试

#基本用法

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

pnpm exec midscene-test

#指定用例目录或文件

有配置时，文件或目录参数用于筛选用例。运行全部用例、单个文件或子目录时，命令使用同一份项目配置。

从项目根目录运行以下命令：

pnpm exec midscene-test
pnpm exec midscene-test ./cases/order.yaml
pnpm exec midscene-test ./cases/smoke

这些命令共用配置中的 Node（节点）和 Project（执行项目），默认输出位置也相同。

配置与路径规则

默认配置查找只检查当前工作目录。从子目录运行时，请显式指定项目配置：

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

此时，测试根目录是配置所在的父目录。默认输出仍位于父目录的 midscene_run。

没有配置时，文件参数用于收集指定 YAML，目录参数用于查找该目录下的 YAML。也支持当前工作目录之外的路径。省略参数时，从当前工作目录查找用例。不会加载目标文件或目录旁的配置。默认产物保存在当前工作目录的 midscene_run 中。

无配置时，不会注册任何 Node。YAML 如果引用了 Node，仍需通过配置注册。旧版 tasks/flow YAML 请使用 midscene 命令运行。

文件与标签筛选

脚手架生成的项目通过 files.include 选择用例。默认范围是 cases/ 下的 .yaml 和 .yml 文件。省略 files 时，框架递归查找测试根目录下的 YAML 文件，并忽略 node_modules、.git 和运行产物目录。

有配置时，路径参数会进一步缩小用例范围。--project、文件包含与排除规则，以及 tags（标签）筛选仍然生效。显式指定文件也需要满足这些规则。

传入路径参数后，如果所有 Project 都没有匹配的用例，命令会报筛选错误。部分 Project 没有匹配用例时，其他 Project 仍可运行。

未传路径参数时，沿用原有行为：如果文件存在，但 tags 排除了全部用例，命令可以成功退出。文件查找失败等其他错误仍会导致运行失败。

切换项目与 SDK 调用

运行另一个项目时，请进入该项目目录，或用 --config 指定配置。目录参数不会改变配置查找位置。

SDK 使用以下参数：

• projectRoot：指定默认配置查找目录。省略时使用 cwd。
• testPath：指定文件或目录筛选路径。相对路径以 cwd 为基准。
• configPath：显式选择配置。相对路径以 cwd 为基准，测试根目录为配置所在目录。

以上规则适用于测试运行。nodes 子命令保留原有的目录和配置解析规则。

#配置查找行为迁移

默认配置只从当前工作目录（cwd）加载。框架不会向上查找父目录，也不会因指定用例目录而切换配置。

如果旧命令依靠目录参数加载另一个项目的配置：

pnpm exec midscene-test ./other-project

请改为显式指定配置：

pnpm exec midscene-test --config ./other-project/midscene.config.ts

也可以先进入 other-project，再运行 pnpm exec midscene-test。仅运行其中一个文件时，在原工作目录执行：

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

升级时，请检查以下路径：

• files.include、files.exclude 和 output.reportDir 以配置所在目录为基准。如果配置位于 config/，用例位于同级的 cases/，请将配置移到两者的共同父目录，并将 files.include 设为 ['cases/**/*.yaml']。
• 默认产物写入配置目录下的 midscene_run。请同步调整 CI 的产物收集路径，或将配置移到项目根目录。
• 同时指定用例路径和 --config 时，--config 的相对路径现在以 cwd 为基准。用例路径和 --result-dir 的相对路径也以 cwd 为基准。

无配置时仍可查找、收集 YAML，但引用的 Node 必须通过配置注册。这不等于可以零配置执行任意 YAML。

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

如果工程中配置了多个平台或运行环境，可以通过 --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_run/test-results/<runId>/，包含结果摘要 result.md、供程序读取的 summary.json 和诊断记录。通过 --result-dir 可修改结果根目录，相对路径以命令的工作目录为基准：

  pnpm exec midscene-test --result-dir ./test-results
• HTML 报告：默认位于 midscene_run/report/，可直接用浏览器打开，查看用例结果、步骤截图、错误和回放。通过 output.reportDir 可修改报告目录，相对路径以测试项目为基准。

排查问题或进行程序化分析时，请保留完整结果目录。summary.json 的字段以当前版本的实际输出为准。

#产物目录

默认产物目录为测试项目下的 midscene_run/，其中 report/ 保存报告，test-results/ 保存结果与诊断记录。通过环境变量 MIDSCENE_RUN_DIR 可修改产物目录，相对路径以测试项目为基准：

MIDSCENE_RUN_DIR="./artifacts" pnpm exec midscene-test

在 CI 中使用时：

• 将原先收集 .midscene/test-results 的规则更新为 midscene_run/test-results，或配置后的结果目录。
• 使用 Midscene GitHub Action 时，通过 run-directory 或 MIDSCENE_RUN_DIR 指定目录，执行与产物收集共用该目录。
• 按终端打印的 Summary: / Report:，或 SDK 返回的 summaryPath、markdownPath、reportPath 收集文件。分享报告的方式见下文。

#退出码

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

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

#报告归档与 URL 深度链接

#报告归档

报告默认生成为单文件 HTML：midscene_run/report/midscene-e2e-<runId>.html。在 midscene.config.ts 中通过 output.reportFormat 选择交付格式：

output: {
  reportFormat: 'single-html', // 默认：直接打开 HTML，支持离线查看
  // reportFormat: 'html-and-external-assets',
}

使用 html-and-external-assets 时，归档或上传需保留整个报告目录，并通过 HTTP 服务查看。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 文档。

#用徽章(badge)展示测试结果

Midscene 提供了官方的 Midscene Test 徽章服务，可以把测试通过数和失败数渲染为 SVG 徽章，并嵌入任意 Markdown 文件，例如仓库的 README：

![Midscene Test: 42 passed, 3 failed](https://badge.midscenejs.com/e2e?pass=42&fail=3)

同时提供双行卡片样式，并支持浅色与深色主题：

徽章上的数字完全来自 URL 中的 pass 和 fail 查询参数，服务本身不会读取 CI 数据或测试报告，需要在每次运行后更新 URL，或在工作流中自动生成。在 GitHub Actions 中运行时，任务的 Summary 页面已经会附带一个根据本次运行结果生成的徽章，同一行内容也会写入 result.md，可以直接复制使用。

完整的参数与样式说明——包括 flat、large、card 三种样式、深色主题，以及无需填写数字的静态 “E2E by Midscene.js” 归属徽章——请参阅徽章服务首页，页面提供实时预览和可直接复制的 Markdown。