close
Rstest
  • 简体中文

      • Utilities

      一些实用的工具函数。

      rs.stubEnv

      • 别名： rstest.stubEnv

      • 类型： (name: string, value: string | undefined) => Rstest & Disposable

      临时设置 process.env 和 import.meta.env 中的环境变量为指定值。适用于测试依赖环境变量的代码。

      • 如果 value 为 undefined，该变量会从 process.env 和 import.meta.env 中移除。
      • 可多次调用以模拟多个环境变量。
      • 使用 rs.unstubAllEnvs() 可恢复所有通过此方法更改的环境变量。

      Disposable / using 语法

      Added in v0.10.3

      Rstest 支持使用 using 语法在代码块退出时自动恢复当前作用域内的 env stub。

      示例：

      rs.stubEnv('NODE_ENV', 'test');
expect(process.env.NODE_ENV).toBe('test');
expect(import.meta.env.NODE_ENV).toBe('test');

rs.stubEnv('MY_VAR', undefined);
expect(process.env.MY_VAR).toBeUndefined();
expect(import.meta.env.MY_VAR).toBeUndefined();
      {
  using _env = rs.stubEnv('NODE_ENV', 'test');
  expect(process.env.NODE_ENV).toBe('test');
}

      rs.unstubAllEnvs

      • 别名： rstest.unstubAllEnvs

      • 类型： () => Rstest

      恢复所有通过 rs.stubEnv 更改的环境变量到原始值。

      • 测试后调用此方法以清理环境变量。
      • 如果配置项 unstubEnvs 启用，则每个测试前会自动调用。

      示例：

      rs.stubEnv('NODE_ENV', 'test');
// ... 执行相关代码
rs.unstubAllEnvs();
expect(process.env.NODE_ENV).not.toBe('test');

      rs.stubGlobal

      • 别名： rstest.stubGlobal

      • 类型： (name: string | number | symbol, value: unknown) => Rstest & Disposable

      临时设置全局变量为指定值。适用于模拟全局对象或函数。

      • 可多次调用以模拟多个全局变量。
      • 使用 rs.unstubAllGlobals() 可恢复所有通过此方法更改的全局变量。

      Disposable / using 语法

      Added in v0.10.3

      Rstest 支持使用 using 语法在代码块退出时自动恢复当前作用域内的 global stub。

      示例：

      rs.stubGlobal('myGlobal', 123);
expect(globalThis.myGlobal).toBe(123);

rs.stubGlobal(Symbol.for('foo'), 'bar');
expect(globalThis[Symbol.for('foo')]).toBe('bar');
      {
  using _global = rs.stubGlobal('myGlobal', 123);
  expect(globalThis.myGlobal).toBe(123);
}

      rs.unstubAllGlobals

      • 别名： rstest.unstubAllGlobals

      • 类型： () => Rstest

      恢复所有通过 rs.stubGlobal 更改的全局变量到原始值。

      • 测试后调用此方法以清理全局变量。
      • 如果配置项 unstubGlobals 启用，则每个测试前会自动调用。

      示例：

      rs.stubGlobal('myGlobal', 123);
// ... 执行相关代码
rs.unstubAllGlobals();
expect(globalThis.myGlobal).toBeUndefined();

      rs.setConfig

      • 别名： rstest.setConfig

      • 类型：

      type RuntimeConfig = {
  testTimeout?: number;
  hookTimeout?: number;
  clearMocks?: boolean;
  resetMocks?: boolean;
  restoreMocks?: boolean;
  maxConcurrency?: number;
  retry?: number;
};

type SetConfig = (config: RuntimeConfig) => void;

      动态更新当前测试的运行时配置。适用于需要在单个测试文件中临时覆盖某些测试设置（如超时时间、并发数、mock 行为等）的场景。

      示例：

      rs.setConfig({ testTimeout: 1000, retry: 2 });
// ... 在新的配置下运行代码
rs.resetConfig(); // 恢复默认配置

      rs.resetConfig

      • 别名： rstest.resetConfig

      • 类型： () => void

      将通过 rs.setConfig 修改的运行时配置重置为默认值。

      rs.getConfig

      • 别名： rstest.getConfig

      • 类型： () => RuntimeConfig

      获取当前测试文件的运行时配置。

      示例：

      const config = rs.getConfig();
console.log(config);

      rs.waitFor

      • 别名： rstest.waitFor

      • 类型：

      type WaitForOptions = {
  timeout?: number; // 默认: 1000
  interval?: number; // 默认: 50
};

type WaitFor = <T>(
  callback: () => T | Promise<T>,
  options?: number | WaitForOptions,
) => Promise<T>;

      不断重试 callback，直到其执行成功（不抛错）或超时。

      • 当 options 为数字时，会被视为 timeout。
      • 超时时会抛出 callback 最后一次抛出的错误。

      示例：

      await rs.waitFor(
  async () => {
    const res = await fetch(url);
    expect(res.ok).toBe(true);
  },
  { timeout: 30_000, interval: 1_000 },
);

      rs.waitUntil

      • 别名： rstest.waitUntil

      • 类型：

      type WaitUntilOptions = {
  timeout?: number; // 默认: 1000
  interval?: number; // 默认: 50
};

type WaitUntil = <T>(
  callback: () => T | Promise<T>,
  options?: number | WaitUntilOptions,
) => Promise<T>;

      仅当 callback 没有返回值（undefined 或 null）或返回 falsy 值时才会继续重试；当其返回 truthy 值时会立刻 resolve。

      • 当 options 为数字时，会被视为 timeout。
      • 如果 callback 抛错，会立即中断并抛出该错误。
      • 超时时会抛出超时错误。

      示例：

      const serverReady = await rs.waitUntil(
  async () => {
    const status = await getServerStatus();
    return status.ready ? status : null;
  },
  { timeout: 10_000, interval: 200 },
);