Rstest 实例

本页介绍的所有 API 都由 @rstest/core 的 @rstest/core/api 入口导出。你可以通过这些 API 创建 Rstest 实例、运行或列出测试、启动监听会话，以及合并 blob 报告。

import { createRstest } from '@rstest/core/api';

Warning

目前所有导出都是实验性的，在 Rstest 1.0.0 之前可能发生变化。请暂时锁定 @rstest/core 的精确版本来保证 API 稳定性。

createRstest

createRstest 函数用于创建并返回一个 Rstest 实例。config 会在创建实例时解析一次，并作为实例的基础配置持续复用。传给实例方法的选项只应用于当前操作，不会修改这份基础配置。

cwd 默认为 process.cwd()，并作为相对 config.root 的解析基准；省略 config 时使用空的内联配置，不会从 cwd 中发现配置文件。

createRstest 会设置 RSTEST=true，仅当 NODE_ENV 尚未设置时才设置 NODE_ENV=test，并且不会恢复这两个环境变量。

示例

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  cwd: './packages/app',
  config: {
    include: ['src/**/*.test.ts'],
    reporters: [],
  },
});

const result = await rstest.run();
console.log(result.status);

加载配置文件

使用主入口的 loadConfig 加载配置文件，再将返回值（{ content, filePath, dependencies }）直接作为 config 传入。

import { loadConfig } from '@rstest/core';
import { createRstest } from '@rstest/core/api';

const loaded = await loadConfig();
const rstest = await createRstest({ config: loaded });

CreateRstestOptions

类型：

interface LoadedRstestConfig {
  content: RstestConfig; // 已加载的配置内容。
  filePath: string | null; // `loadConfig` 返回的配置文件来源路径，没有时为 `null`。
  dependencies?: string[];
}

interface CreateRstestOptions {
  cwd?: string;
  config?: RstestConfig | LoadedRstestConfig;
  configLoader?: 'auto' | 'jiti' | 'native'; // 通过 `projects` 发现的配置文件所使用的 loader；默认为 `auto`。
}

function createRstest(options?: CreateRstestOptions): Promise<RstestInstance>;

rstest.context

rstest.context 是一个在创建实例时解析一次的只读对象。你可以在不运行测试的情况下检查解析后的状态，例如用 rootPath 确定结果中的 testPath 在 workspace 中的位置，用 projects 展示或筛选多项目配置，用 config 查看生效的配置，也可以用 version 做兼容性检查。

示例

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  config: {
    projects: [
      {
        name: 'unit',
        include: ['tests/**/*.test.ts'],
      },
    ],
  },
});

console.log(rstest.context.version);
console.log(rstest.context.rootPath);

for (const project of rstest.context.projects) {
  console.log(project.name, project.rootPath);
}

RstestContext

类型：

interface ProjectContext {
  name: string; // 项目名称。
  rootPath: string; // 项目的绝对根路径。
  configFilePath?: string; // 与项目关联的配置文件路径（如果有）。
  configFileDependencies?: string[]; // 项目配置依赖，包括父级项目的配置文件。
}

interface RstestContext {
  readonly version: string;
  readonly rootPath: string;
  readonly config: Readonly<NormalizedConfig>;
  readonly projects: readonly ProjectContext[];
}

context.version

当前使用的 @rstest/core 版本。

类型： string

context.rootPath

Rstest 实例的绝对根路径。它由 config.root 解析得出；当 config.root 为相对路径时，以 cwd 为基准。

类型： string

context.config

Rstest 实例规范化后的配置。

类型： Readonly<NormalizedConfig>

context.projects

解析后的项目 Context。未显式配置 projects 时，该数组包含由 config.name 命名的默认项目（默认名称为 'rstest'）。

类型： readonly ProjectContext[]

rstest.run

rstest.run() 会运行一个测试轮次，并返回 TestRunResult。只有在运行完全无法开始时（无效的选项或配置，或 node 项目的 dev server 无法启动）Promise 才会被拒绝。此后的一切失败——浏览器项目的 dev server 或浏览器无法启动、globalSetup 抛错、编译错误、测试失败——都通过 status 报告，不会导致 Promise 被拒绝，具体规则见 TestRunResult。

示例

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  config: {
    include: ['src/**/*.test.ts'],
  },
});

const result = await rstest.run({
  filters: ['"src/foo.test.ts"'],
});

console.log(result.status);
console.log(result.summary.tests);

RunOptions

RunOptions 支持 testTimeout、coverage、reporters 等运行周期选项，不接受创建阶段的选项（config、configLoader、root）以及仅用于 CLI 的 teardownTimeout。完整 flag 列表见 CLI 选项，精确类型见 packages/core/src/api/types.ts。

对于用于覆盖配置的字段，优先级为：本次 run() 显式传入的值 > 实例配置中的值 > 该配置项的默认值。未传入或值为 undefined 的字段沿用配置中的值。嵌套对象和数组遵循对应配置项的合并规则。

覆盖只影响本次 run() 调用，不会修改实例的初始配置：

const rstest = await createRstest({ config: { repeats: 2 } });

await rstest.run({ repeats: 5 }); // 本次调用的全局默认值为 5。
await rstest.run(); // 仍使用配置中的 2。

filters 仅用于 API；CLI 通过位置参数传入 filter。它默认使用不区分大小写的子字符串匹配。用成对的单引号或双引号包裹 filter，可精确匹配绝对路径或相对于 root 的路径，例如 filters: ['"src/foo.test.ts"', 'utils']；带引号和不带引号的 filter 可以混用。省略 filters 时选择所有文件；显式传入空数组时不会选择任何文件。

trace ^v0.12.4 会为本次运行采集性能 trace。传 true 时文件写入 <rootPath>/.rstest/。与 CLI flag 不同，它不会打印任何内容，也不会启动 Perfetto helper server，文件路径从 TestRunResult.trace 读取。在 rstest.watch() 中，它对整个会话生效。

repeats ^v0.13.0 设置单个测试的额外执行次数，测试和套件自身的选项优先。详见 repeats。

类型：

interface RunOptions {
  filters?: string[];
  trace?: boolean;
  repeats?: number;
  // ……以及其他支持的运行选项，用于覆盖同名配置项，
  // 例如 `testTimeout`、`coverage`、`reporters`。
}

interface RstestInstance {
  run(options?: RunOptions): Promise<TestRunResult>;
}

TestRunResult

类型：

type TestRunStatus = 'passed' | 'failed' | 'error';

interface TestRunResult {
  status: TestRunStatus; // 本次运行的整体状态。
  trace?: { tracePath: string; summaryPath: string }; // 仅在运行时传入 `trace` 时存在。
  // 其余字段与 `onTestRunEnd` 的 payload 相同，去掉 `getSourcemap`。
}

其余字段（results、testResults、summary、duration、snapshotSummary、unhandledErrors、coverage、rerunTestPaths）的说明见 Reporter API 的 onTestRunEnd。

当 unhandledErrors 不为空时，status 为 'error'。测试或测试文件失败、coverage 未达 threshold，或未设置 passWithNoTests 时没有找到测试，status 为 'failed'。watch 模式下，只要会话里还有失败的测试文件，即使当前轮次全部通过，status 仍是 'failed'。其他情况下，status 为 'passed'。之后再发生 global teardown 错误不会影响 onTestRunEnd 收到的 payload，但 run() 仍会返回 'failed'。

unhandledErrors 里的每一项都是普通对象，可以直接序列化为 JSON，不是 Error 实例。

trace ^v0.12.4 包含 Perfetto trace JSON 及其 markdown 摘要的绝对路径。运行未开启 trace 时该字段不存在。watch 模式下，它指向最近一轮的文件。

rstest.watch

rstest.watch() 会启动监听会话，并返回用于关闭它的监听器。

示例

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  config: {
    include: ['src/**/*.test.ts'],
  },
});

const watcher = await rstest.watch({
  onResult(result) {
    console.log(
      result.status,
      result.results.map((file) => file.testPath),
      result.rerunTestPaths,
    );
  },
});

await watcher.close();

每一轮结束后都会调用 onResult，第一轮也不例外。results、summary 和 status 反映整个 watch 会话的状态，rerunTestPaths 是这一轮实际执行的文件。

失败分为三类：

启动失败——配置阶段抛错，或 node 项目的 dev server 无法启动。run() 和 watch() 都会被拒绝。
启动之后的致命失败——浏览器项目的 dev server 或浏览器无法启动、首轮 globalSetup 抛错或编译失败，或 bundler 以不会重新挂载文件监听器的方式结束了一次编译。run() 返回 status: 'error'；在 watch 中，失败的那一轮仍会送达 onResult，随后会话关闭；若 watch() 尚未 resolve，则以该错误被拒绝——多个错误时合并为 AggregateError。
可恢复的周期失败——测试失败、测试文件编译失败，或后续轮次的 globalSetup 失败。该轮会上报失败，watch 会话保持打开，等待下一次触发。

onResult 抛出的错误会被隔离，不会停止监听会话。调用 watcher.close() 会释放编译器、worker、文件监听器，并运行待处理的 globalSetup 清理函数。该方法是幂等的，重复调用会得到相同结果；清理失败时，它返回的 Promise 会被拒绝。

rstest.watch() 会拒绝 related 和 changed，因为它们会选择固定的文件集合，而监听会话必须能够发现新的关联测试。使用这些选项时请调用 rstest.run()。related: false 和 changed: false 会被忽略。

WatchOptions

类型：

interface WatchOptions {
  onResult?: (result: TestRunResult & { rerunTestPaths: string[] }) => void;
}

interface RstestWatcher {
  close(): Promise<void>;
}

interface RstestInstance {
  watch(options?: WatchOptions & RunOptions): Promise<RstestWatcher>;
}

rstest.listTests

rstest.listTests() 会收集测试文件和测试声明，但不运行测试主体。

示例

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest({
  config: {
    include: ['src/**/*.test.ts'],
  },
});

const tests = await rstest.listTests({
  includeSuites: true,
  includeTaskLocation: true,
});

console.log(tests);

设置 filesOnly 可跳过声明收集。includeSuites 会将具名测试套件作为独立条目返回。RunOptions 中的 includeTaskLocation 会加入源码位置。

每个条目都包含 testPath 和 project。隐式默认项目的条目使用 config.name（默认为 'rstest'）。测试声明条目包含自身的 name、带测试套件前缀的 fullName，以及表示层级的 parentNames；文件条目不包含 name 和 fullName。标记为 skip 或 todo 的声明也会返回，runMode 分别为 skip 或 todo；可运行声明不提供 runMode。

条目按深度优先的声明顺序返回。测试套件紧邻其后代之前，同一文件的所有条目保持连续。

收集失败时，rstest.listTests() 返回的 Promise 会以 ListTestsError 拒绝，而不是返回部分列表或空列表。

只有显式传给 rstest.listTests() 的 shard 才会生效，并将结果限制在选定分片。省略 shard 时会列出所有文件；实例配置中的 shard 仍会像以前一样被丢弃。

ListOptions

类型：

interface ListOptions {
  filesOnly?: boolean;
  includeSuites?: boolean;
}

interface ListedTest {
  testPath: string; // 测试文件路径。
  name?: string; // 声明自身的名称；文件条目不包含此字段。
  fullName?: string; // 带测试套件前缀的显示名称；文件条目不包含此字段。
  parentNames?: string[]; // 外层测试套件的名称。
  project: string; // 项目名称。
  location?: TestLocation; // 请求后提供的源码位置。
  runMode?: 'skip' | 'todo'; // 不可运行声明的 skip 或 todo 模式。
  type: 'file' | 'suite' | 'case'; // 条目类型。
}

interface RstestInstance {
  listTests(options?: ListOptions & RunOptions): Promise<ListedTest[]>;
}

rstest.mergeReports

rstest.mergeReports() 用于合并 blob 报告，并返回与 rstest.run() 相同的结果模型。

当本次操作无法产生运行结果时，Promise 会被拒绝；合并的测试结果中若有测试失败，仍通过 status 报告，不会导致 Promise 被拒绝。

示例

import { createRstest } from '@rstest/core/api';

const rstest = await createRstest();

const result = await rstest.mergeReports({
  path: './.rstest-reports',
  cleanup: true,
});

console.log(result.status);

path 用于选择 blob 报告目录。cleanup 会在合并成功后删除已消费的报告。

MergeReportsOptions

类型：

interface MergeReportsOptions {
  path?: string;
  cleanup?: boolean;
}

interface RstestInstance {
  mergeReports(options?: MergeReportsOptions): Promise<TestRunResult>;
}

runCLI

runCLI 会在当前进程中运行 Rstest 命令行。它会解析 argv、设置 process.exitCode，并安装 CLI 的 signal handlers。需要 CLI 的进程行为时，请使用 runCLI；实例方法不会设置 process.exitCode 或安装 signal handlers。

示例

import { runCLI } from '@rstest/core/api';

runCLI({
  argv: [...process.argv.slice(0, 2), 'run', 'src/foo.test.ts', '--update'],
});

argv 的结构与 Node.js 的 process.argv 一致，默认值为 process.argv：前两项是 executable 和 script 的路径，会被忽略，命令、filters 和 flags 从索引 2 开始。这与 Rsbuild 和 Rspress 的 runCLI 使用的结构相同。

所有可用的命令和选项，请参阅 CLI 文档。

RunCLIOptions

类型：

interface RunCLIOptions {
  argv?: string[];
}

function runCLI(options?: RunCLIOptions): void;

#Rstest 实例

#createRstest

#示例

#加载配置文件

#CreateRstestOptions

#rstest.context

#示例

#RstestContext

#context.version

#context.rootPath

#context.config

#context.projects

#rstest.run

#示例

#RunOptions

#TestRunResult

#rstest.watch

#示例

#WatchOptions

#rstest.listTests

#示例

#ListOptions

#rstest.mergeReports

#示例

#MergeReportsOptions

#runCLI

#示例

#RunCLIOptions