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

# CI

Rstest 在 CI 中使用的 CLI 与本地相同。主要区别是，CI 应该通过 `rstest` 以 run mode 执行测试，然后上传其他工具需要读取的报告。

## 基础工作流

在 CI 中使用 `rstest`，这样进程会在一次测试完成后退出。如果项目已经有 `test` 脚本，可以让 CI 继续调用该脚本，并让脚本执行 `rstest`。

```json title="package.json"
{
  "scripts": {
    "test": "rstest"
  }
}
```

一个最小的 GitHub Actions 工作流会安装依赖、恢复包管理器缓存，并运行测试脚本：

```yaml title=".github/workflows/test.yml"
name: Test

on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 11

      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
          cache: pnpm

      - run: pnpm install --frozen-lockfile
      - run: pnpm test
```

当 Rstest 检测到 GitHub Actions 且没有手动配置 reporter 时，会自动启用 `github-actions` reporter。失败断言会转换成 GitHub 注释，并在 workflow summary 中追加 Markdown 摘要。更多 reporter 细节请查看 [reporters](/zh/guide/basic/reporters.md#github-actions-报告器)。

其他 CI 系统也可以使用相同命令。关键是先运行 `pnpm install --frozen-lockfile`，再运行 `pnpm rstest` 或你的 package script。

## 添加覆盖率

覆盖率收集默认关闭。启用 `--coverage` 前，需要先安装你想使用的 provider：

- [@rstest/coverage-istanbul](https://github.com/web-infra-dev/rstest/tree/main/packages/coverage-istanbul)：默认的 Istanbul provider，适用于 Node mode 和 Browser Mode。
- [@rstest/coverage-v8](https://github.com/web-infra-dev/rstest/tree/main/packages/coverage-v8)：基于 V8 的 provider，适用于 Node mode 和 headless、非 watch 的 Chromium Browser Mode 运行。

```bash
pnpm add @rstest/coverage-istanbul -D
pnpm rstest --coverage
```

如果 CI 需要保留 HTML 报告，或把覆盖率数据传给其他服务，可以上传生成的 `coverage/` 目录：

```yaml
- run: pnpm rstest --coverage --coverage.reportOnFailure

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: coverage
    path: coverage
```

当失败运行中的报告也有调试价值时，可以使用 `if: always()`。可用的 provider、reporter、阈值和输出路径请查看 [coverage](/zh/config/test/coverage.md)。

## 在 CI 中运行浏览器测试

[Rstest Browser Mode](/zh/guide/browser-testing.md) 和 [@rstest/playwright](https://github.com/web-infra-dev/rstest/tree/main/packages/playwright) 都通过 [Playwright](https://github.com/microsoft/playwright) 启动浏览器。安装 `playwright` npm 包只会提供自动化 API，浏览器可执行文件需要单独提供。

### 选择浏览器的提供方式

通用做法是安装与 Playwright 包版本匹配的浏览器：

```bash
pnpm exec playwright install --with-deps chromium
```

根据 workflow 所需的覆盖范围和可复现性选择安装方式：

| 需求                                         | 浏览器准备方式                                                                                                                   |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| 在标准 GitHub-hosted runner 上快速运行 Chrome      | 跳过 `playwright install`，通过 `channel: 'chrome'` 启动预装的 Chrome。                                                              |
| 使用与 Playwright 包版本绑定的 Chromium             | 运行 `playwright install --with-deps chromium`。如果仅以 headless 模式运行且没有设置 channel，可以添加 `--only-shell`，避免下载完整的 headed Chromium。 |
| 覆盖 Firefox 或 WebKit                        | 通过 `playwright install --with-deps firefox` 或 `playwright install --with-deps webkit` 安装对应的 Playwright 浏览器。               |
| 使用 self-hosted runner、container job 或自定义镜像 | 安装 Playwright 浏览器，或先在镜像中准备 Chrome，再选择 `channel: 'chrome'`。                                                                |

包括 `ubuntu-latest` 在内的标准 [GitHub-hosted runner 镜像](https://github.com/actions/runner-images#available-images)预装了 Google Chrome。选择 `chrome` channel 后，两种 Rstest 集成都可以直接使用该可执行文件，无需下载 Playwright Chromium。GitHub 会定期更新 runner 软件，因此这种方式牺牲了固定的浏览器版本，以换取更快的准备速度。workflow 中的 **Set up job → Runner Image → Included Software** 链接会列出[本次运行使用的准确软件版本](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners#preinstalled-software-for-github-owned-images)。

Firefox 和 WebKit 仍需要下载 Playwright 提供的浏览器。Playwright 依赖这些引擎的补丁版本，不能直接替换为 runner 上安装的 Firefox 或 Safari 应用。

### Browser mode

安装 [@rstest/browser](https://github.com/web-infra-dev/rstest/tree/main/packages/browser) 和 Playwright API：

```bash
pnpm add @rstest/browser playwright -D
```

在标准 GitHub-hosted runner 上，通过 Browser Mode CLI 传入 Chrome channel，并省略浏览器安装步骤：

```yaml
- run: pnpm install --frozen-lockfile
- run: pnpm rstest --browser --browser.providerOptions.launch.channel=chrome
```

如果希望在 `rstest.config.ts` 中通过环境判断启用相同优化，可以改为配置 provider：

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    providerOptions:
      process.env.GITHUB_ACTIONS === 'true'
        ? {
            launch: {
              channel: 'chrome',
            },
          }
        : undefined,
  },
});
```

在 CI 中，`browser.headless` 默认值为 `true`，无需额外配置 headless。其他 browser 和 provider 选项请查看 [Browser Mode 快速开始](/zh/guide/browser-testing/getting-started.md) 和 [browser 配置](/zh/config/test/browser.md)。

### @rstest/playwright

安装 Rstest fixtures 和 Playwright API：

```bash
pnpm add @rstest/playwright playwright -D
```

可以在 `rstest.config.ts` 中配置 [@rstest/playwright](/zh/guide/basic/e2e-testing.md) 的默认启动选项：

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';
import { definePlaywrightConfig } from '@rstest/playwright/config';

export default defineConfig({
  extends: definePlaywrightConfig({
    browserName: 'chromium',
    launchOptions:
      process.env.GITHUB_ACTIONS === 'true' ? { channel: 'chrome' } : undefined,
  }),
});
```

使用该 fixture 后，标准 GitHub-hosted workflow 只需要安装 npm 依赖并运行 Rstest，不要再添加 `playwright install` 步骤。fixture 用法和 trace artifact 请查看 [@rstest/playwright 指南](/zh/guide/basic/e2e-testing.md)。

## 使用分片拆分测试 \{#split-tests-with-shards}

当完整测试套件已经稳定，但单台 CI 机器运行太慢时，可以使用 `--shard <index>/<count>`。每个分片会运行不同的测试文件子集。要在后续合并结果和覆盖率，需要让每个分片都使用 `blob` reporter，上传 blob 文件，然后在后续 job 中合并。

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 11
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm rstest --shard ${{ matrix.shard }}/3 --reporters=blob --coverage
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: rstest-blob-${{ matrix.shard }}
          path: .rstest-reports
          include-hidden-files: true

  merge-reports:
    runs-on: ubuntu-latest
    needs: test
    if: always()
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 11
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - uses: actions/download-artifact@v4
        with:
          pattern: rstest-blob-*
          path: .rstest-reports
          merge-multiple: true
      - run: pnpm rstest merge-reports --coverage --cleanup
```

每个分片会将测试结果和实际采集的覆盖率写入 `.rstest-reports/blob-{index}-{count}.json`。支持延迟最终处理的 coverage provider 会让这些使用 blob 报告器的分片不生成覆盖率报告，也不检查阈值；未使用 blob 报告器的分片仍会正常完成覆盖率最终处理。旧版 provider 保持原有的单次运行最终处理行为。合并 job 会把这些文件收集到同一个 `.rstest-reports/` 目录，然后 `rstest merge-reports` 会基于统一结果补齐未测试文件、运行已配置的 reporter 并检查覆盖率阈值。请把覆盖率最终处理参数放在共享配置中，或将相同的 `--coverage.*` 参数传给合并命令，因为只传给分片的 CLI 参数不会写入 blob。更多细节请查看[测试分片](/zh/guide/basic/cli.md#sharding-tests)和 [`rstest merge-reports`](/zh/guide/basic/cli.md#rstest-merge-reports)。

## 发布机器可读报告

除了终端输出，CI 工具通常还需要结构化报告文件。当你需要 XML、JSON、Markdown 或 blob 输出时，可以添加 reporter：

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

export default defineConfig({
  reporters: [
    'default',
    ['junit', { outputPath: './reports/junit.xml' }],
    ['json', { outputPath: './reports/rstest.json' }],
  ],
});
```

然后上传报告目录：

```yaml
- run: pnpm rstest

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: rstest-reports
    path: reports
```

`junit` 适合 CI 测试结果集成，`json` 适合自定义工具，`md` 适合 Markdown 摘要，`github-actions` 适合 GitHub 注释，`blob` 适合分片报告合并。完整列表和选项请查看 [reporters](/zh/guide/basic/reporters.md)。

## 缓存依赖

建议先从包管理器缓存开始，因为它安全，通常也能带来最明显的 CI 优化。在 GitHub Actions 中，`actions/setup-node` 配合 `cache: pnpm` 会基于 lockfile 恢复 pnpm store。

默认不要缓存 Playwright 浏览器二进制文件。恢复缓存所需的时间可能与重新下载相近，而且缓存不包含 Linux 系统依赖。如果 workflow 可以接受 runner 的浏览器版本，优先使用 GitHub 预装的 Chrome；否则只安装需要的浏览器，并在仅运行 headless Chromium 时使用 `--only-shell`。

## 推荐检查清单

- 使用 Node.js `^20.19.0` 或 `>=22.12.0`，以匹配 Rstest 支持的运行时范围。
- 在 CI 中运行 `rstest`，可以直接运行，也可以通过 package script 运行。
- 仅在 workflow 需要对应功能时安装 coverage 和 browser 包。
- 如果 coverage、JUnit、JSON 或 blob artifact 有助于排查失败，使用 `if: always()` 上传。
- 在单机 workflow 稳定后，再添加 sharding。
- 明确选择与 Playwright 版本匹配的浏览器或系统预装的 Chrome，并让 browser、channel 和安装步骤保持一致。