> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 运行测试

## 基本用法 {#run-tests}

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

```bash
pnpm exec midscene-test
```

### 指定用例目录或文件

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

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

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

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

**配置与路径规则**

| 项目             | 解析规则                                                             |
| -------------- | ---------------------------------------------------------------- |
| 默认配置           | 仅查找当前工作目录。支持 `midscene.config.ts` 和 `midscene.config.mjs`。       |
| `--config`     | 相对路径以当前工作目录为基准，也支持绝对路径。                                          |
| 测试根目录          | 使用配置所在目录。无配置时，使用当前工作目录。                                          |
| 文件或目录参数        | 以当前工作目录为基准。有配置时筛选项目用例；无配置时查找、收集指定文件或目录中的用例。                      |
| 配置中的路径         | `files.include`、`files.exclude` 和 `output.reportDir` 均以测试根目录为基准。 |
| `--result-dir` | 相对路径以当前工作目录为基准。                                                  |

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

```bash
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）加载。框架不会向上查找父目录，也不会因指定用例目录而切换配置。

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

```bash
pnpm exec midscene-test ./other-project
```

请改为显式指定配置：

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

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

```bash
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` 指定自定义配置文件：

```bash
# 仅运行名为 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` 参数：

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

## 输出与退出码

### 终端输出模式

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

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

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

### 结果文件与报告路径

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

- **结果文件**：默认位于 `midscene_run/test-results/<runId>/`，包含结果摘要 `result.md`、供程序读取的 `summary.json` 和诊断记录。通过 `--result-dir` 可修改结果根目录，相对路径以命令的工作目录为基准：
  ```bash
  pnpm exec midscene-test --result-dir ./test-results
  ```
- **HTML 报告**：默认位于 `midscene_run/report/`，可直接用浏览器打开，查看用例结果、步骤截图、错误和回放。通过 `output.reportDir` 可修改报告目录，相对路径以测试项目为基准。

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

### 产物目录 {#统一产物根与迁移}

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

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

在 CI 中使用时：

- 将原先收集 `.midscene/test-results` 的规则更新为 `midscene_run/test-results`，或配置后的结果目录。
- 使用 [Midscene GitHub Action](https://github.com/web-infra-dev/midscene-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` 选择交付格式：

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

使用 `html-and-external-assets` 时，归档或上传需保留整个报告目录，并通过 HTTP 服务查看。CI 配置参阅[在 GitHub Actions 中运行](#在-github-actions-中运行)。

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

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

| 选择器           | 定位目标                      |
| ------------- | ------------------------- |
| `first`       | 最早开始执行的 Step              |
| `last`        | 最晚执行完成的 Step              |
| `first-error` | 最早开始执行的失败 Step（包含失败的重试记录） |
| `last-error`  | 最晚执行完成的失败 Step（包含失败的重试记录） |

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

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

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

```text
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`：
  ```ts
  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](https://github.com/marketplace/actions/midscene-action)，用于在 GitHub Actions 中运行 Midscene Test 并管理测试产物：

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

关于完整的配置参数与进阶用法，请参阅 [GitHub Marketplace 上的 midscene-action 文档](https://github.com/marketplace/actions/midscene-action)。

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

Midscene 提供了官方的 [Midscene Test 徽章服务](https://badge.midscenejs.com)，可以把测试通过数和失败数渲染为 SVG 徽章，并嵌入任意 Markdown 文件，例如仓库的 README：

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

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

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

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

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

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