CI

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

基础工作流

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

package.json

{
  "scripts": {
    "test": "rstest"
  }
}

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

.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。

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

添加覆盖率

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

@rstest/coverage-istanbul：默认的 Istanbul provider，适用于 Node mode 和 Browser Mode。
@rstest/coverage-v8：基于 V8 的 provider，仅适用于 Node mode。

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

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

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

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

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

在 CI 中运行浏览器测试

Rstest Browser Mode 和 @rstest/playwright 都通过 Playwright 启动浏览器。安装 playwright npm 包只会提供自动化 API，浏览器可执行文件需要单独提供。

选择浏览器的提供方式

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

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 镜像预装了 Google Chrome。选择 chrome channel 后，两种 Rstest 集成都可以直接使用该可执行文件，无需下载 Playwright Chromium。GitHub 会定期更新 runner 软件，因此这种方式牺牲了固定的浏览器版本，以换取更快的准备速度。workflow 中的 Set up job → Runner Image → Included Software 链接会列出本次运行使用的准确软件版本。

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

Browser mode

安装 @rstest/browser 和 Playwright API：

pnpm add @rstest/browser playwright -D

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

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

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

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 快速开始和 browser 配置。

@rstest/playwright

安装 Rstest fixtures 和 Playwright API：

pnpm add @rstest/playwright playwright -D

@rstest/playwright 通过 playwright fixture 配置启动选项。定义一个共享的扩展 test，然后在浏览器测试文件中导入：

tests/fixtures.ts

import { expect, test as base } from '@rstest/playwright';
import type { PlaywrightOptions } from '@rstest/playwright';

export { expect };

export const test = base.extend({
  playwright: {
    browserName: 'chromium',
    launchOptions:
      process.env.GITHUB_ACTIONS === 'true' ? { channel: 'chrome' } : undefined,
  } satisfies PlaywrightOptions,
});

使用该 fixture 后，标准 GitHub-hosted workflow 只需要安装 npm 依赖并运行 Rstest，不要再添加 playwright install 步骤。fixture 用法和 trace artifact 请查看 @rstest/playwright 指南。

使用分片拆分测试

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

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。合并 job 会把这些文件收集到同一个 .rstest-reports/ 目录，然后 rstest merge-reports 会基于统一结果运行已配置的 reporter，并合并覆盖率数据。更多细节请查看测试分片和 rstest merge-reports。

发布机器可读报告

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

rstest.config.ts

import { defineConfig } from '@rstest/core';

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

然后上传报告目录：

- 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。

缓存依赖

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

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

#CI

#基础工作流

#添加覆盖率

#在 CI 中运行浏览器测试

#选择浏览器的提供方式

#Browser mode

#@rstest/playwright

#使用分片拆分测试

#发布机器可读报告

#缓存依赖

#推荐检查清单

CI