close
Rstest
  • 简体中文

      • pool

      • 类型：
      export type RstestPoolType = 'forks' | 'threads';

export type RstestPoolOptions = {
  /** 用于运行测试的线程池 */
  type?: RstestPoolType;
  /** 最大运行的线程池的数量或百分比 */
  maxWorkers?: number | string;
  /** 向子进程中的 node 进程传递附加参数。 */
  execArgv?: string[];
};

export type RstestConfig = {
  /** 用于运行测试的线程池 */
  pool?: RstestPoolType | RstestPoolOptions;
};
      • 默认值：
      const defaultPool = {
  type: 'forks',
  // maxWorkers 会根据 CPU 数量和运行模式自动计算
};
      • CLI： --pool <type>, --pool.type <type>, --pool.maxWorkers <value>, --pool.execArgv <arg>

      用于运行测试的线程池的选项。

      Pool 类型

      Rstest 支持两种 pool 类型，它们共享同一套 scheduler、RPC 和结果聚合逻辑，差异仅在于 worker 的创建方式。

      forks

      每个测试文件运行在通过 child_process.fork 启动的独立 Node.js 子进程中。每个 worker 拥有独立的 V8 heap，因此进程级状态（process.chdir、signal handler、env 修改、native module 绑定）不会在文件之间泄漏。

      threads

      Added in v0.10.0

      每个测试文件运行在通过 node:worker_threads 创建的 worker thread 中。Worker 与主进程共享 V8 heap 和 stdio。

      如何选择 pool 类型

      forks 是默认值，多数现有测试代码都依赖按文件维度的进程隔离。如果不确定要不要切换，建议先继续使用 forks。

      下列情况可以考虑切换到 threads：

      • 测试以小型用例为主、单文件耗时短，worker 启动开销在总时间中占比明显 — worker_threads 启动比 child_process.fork 快约 10×，watch 模式 rerun 体感几乎秒回。
      • 并行运行时机器内存吃紧或观察到 OOM — threads 共享主进程的 V8 heap，多个 worker 不会各占一份 V8 实例。
      • 测试代码本身不修改 cwd / 环境变量 / signal handler，也不依赖按文件重置的进程级状态。

      下列情况建议继续使用 forks：

      • 测试里会修改 process.chdir、环境变量、signal handler 等进程级状态，并依赖按文件之间互相隔离。
      • 项目使用 native addon（如 better-sqlite3、sharp、canvas）—— 未针对 worker thread 设计的 addon 在 threads 下可能让整个运行直接 abort（SIGSEGV / SIGABRT，且无法捕获）。
      • 希望单个测试文件的硬性崩溃被限制在该 worker 内，不影响主进程和其他用例。

      控制文件级并行度

      pool.maxWorkers 控制同时运行的测试文件数量。当测试会竞争同一个数据库、端口、fixture 目录或其他外部资源时，可以用它限制并行度。

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  pool: {
    maxWorkers: 1,
  },
});

      也可以通过 CLI 传入相同配置：

      npx rstest --pool.maxWorkers 1

      常见取值：

      • 1：让测试文件逐个运行。这等价于 Vitest 的 fileParallelism: false 和 Jest 的 --runInBand。
      • 50%：根据可用 CPU 数量按比例控制并行度，适合容量共享的 CI 机器。
      • 固定数字，如 4：无论机器规模如何，都把资源占用限制在已知安全的范围内。

      maxWorkers 控制的是文件级并行度。它不会限制单个测试文件内的 test.concurrent 用例；如需限制这类用例，请使用 maxConcurrency。

      向 worker 传递 Node.js flags

      当 worker 内运行的代码需要特定 Node.js flags（例如自定义 conditions、warnings 或调试参数）时，可以使用 pool.execArgv。

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  pool: {
    execArgv: ['--conditions=development'],
  },
});

      如果要调试单个 worker，可以把 execArgv 和 maxWorkers: 1 组合使用，确保同一时间只有一个测试文件连接到 debugger：

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  pool: {
    maxWorkers: 1,
    execArgv: ['--inspect-brk'],
  },
});