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

# Utilities

一些实用的工具函数。

## rs.stubEnv

- **别名：** `rstest.stubEnv`

- **类型：** `(name: string, value: string | undefined) => RstestUtilities & Disposable`

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

- 如果 `value` 为 `undefined`，该变量会从 `process.env` 和 `import.meta.env` 中移除。

- 可多次调用以模拟多个环境变量。

- 使用 [`rs.unstubAllEnvs()`](#rsunstuballenvs) 可恢复所有通过此方法更改的环境变量。

- **示例：**

```ts
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` 语法**


[Added in v0.10.3](https://github.com/web-infra-dev/rstest/releases/tag/v0.10.3)

`rs.stubEnv()` 返回一个 `Disposable`，可配合 `using` 语法在代码块退出时自动恢复当前 env stub。

`_env` 变量以下划线开头，表示它不会被直接使用。`using` 语法要求声明一个变量，因此不能省略 `_env`，但可以使用其他变量名。

```ts
{
  using _env = rs.stubEnv('NODE_ENV', 'test');
  expect(process.env.NODE_ENV).toBe('test');
}

// NODE_ENV 已恢复为原始值。
```

## rs.unstubAllEnvs

- **别名：** `rstest.unstubAllEnvs`

- **类型：** `() => RstestUtilities`

恢复所有通过 [`rs.stubEnv`](#rsstubenv) 更改的环境变量到原始值。

- 测试后调用此方法以清理环境变量。
- 如果配置项 [`unstubEnvs`](/zh/config/test/unstub-envs.md) 启用，则每个测试前会自动调用。

**示例：**

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

在多个测试中模拟环境变量时，可以在 [`afterEach`](/zh/api/runtime-api/test-api/hooks.md#aftereach) Hook 中调用 `rs.unstubAllEnvs()`，以便在每个测试结束后恢复环境变量：

```ts
import { afterEach } from '@rstest/core';

afterEach(() => {
  rs.unstubAllEnvs();
});
```

## rs.stubGlobal

- **别名：** `rstest.stubGlobal`

- **类型：** `(name: string | number | symbol, value: unknown) => RstestUtilities & Disposable`

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

- 可多次调用以模拟多个全局变量。

- 使用 [`rs.unstubAllGlobals()`](#rsunstuballglobals) 可恢复所有通过此方法更改的全局变量。

- **示例：**

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

rs.stubGlobal(Symbol.for('foo'), 'bar');
expect(globalThis[Symbol.for('foo')]).toBe('bar');
```

- **`using` 语法**


[Added in v0.10.3](https://github.com/web-infra-dev/rstest/releases/tag/v0.10.3)

`rs.stubGlobal()` 返回一个 `Disposable`，可配合 `using` 语法在代码块退出时自动恢复当前 global stub。

`_global` 变量以下划线开头，表示它不会被直接使用。`using` 语法要求声明一个变量，因此不能省略 `_global`，但可以使用其他变量名。

```ts
{
  using _global = rs.stubGlobal('myGlobal', 123);
  expect(globalThis.myGlobal).toBe(123);
}

// myGlobal 已恢复为原始值。
```

## rs.unstubAllGlobals

- **别名：** `rstest.unstubAllGlobals`

- **类型：** `() => RstestUtilities`

恢复所有通过 [`rs.stubGlobal`](#rsstubglobal) 更改的全局变量到原始值。

- 测试后调用此方法以清理全局变量。
- 如果配置项 [`unstubGlobals`](/zh/config/test/unstub-globals.md) 启用，则每个测试前会自动调用。

**示例：**

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

在多个测试中模拟全局变量时，可以在 [`afterEach`](/zh/api/runtime-api/test-api/hooks.md#aftereach) Hook 中调用 `rs.unstubAllGlobals()`，以便在每个测试结束后恢复全局变量：

```ts
import { afterEach } from '@rstest/core';

afterEach(() => {
  rs.unstubAllGlobals();
});
```

## rs.setConfig

- **别名：** `rstest.setConfig`

- **类型：**

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

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

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

**示例：**

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

## rs.resetConfig

- **别名：** `rstest.resetConfig`

- **类型：** `() => void`

将通过 [`rs.setConfig`](#rssetconfig) 修改的运行时配置重置为默认值。

## rs.getConfig

- **别名：** `rstest.getConfig`

- **类型：**

```ts
type GetConfig = () => RuntimeConfig & {
  expect: {
    poll: {
      interval: number;
      timeout: number;
    };
  };
};
```


[Added in v0.12.0](https://github.com/web-infra-dev/rstest/releases/tag/v0.12.0)

返回值还包含合并后的 `expect.poll` 配置副本。修改该副本不会改变运行时配置。

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

**示例：**

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

## rs.waitFor

- **别名：** `rstest.waitFor`

- **类型：**

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

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

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

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

**示例：**

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

## rs.waitUntil

- **别名：** `rstest.waitUntil`

- **类型：**

```ts
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 抛错，会立即中断并抛出该错误。
- 超时时会抛出超时错误。

**示例：**

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