#Utilities

A set of useful utility functions.

#rs.stubEnv

• Alias: rstest.stubEnv

• Type: (name: string, value: string | undefined) => RstestUtilities & Disposable

Temporarily sets an environment variable in process.env and import.meta.env to the specified value. Useful for testing code that depends on environment variables.

• If value is undefined, the variable will be removed from process.env and import.meta.env.

• You can call this multiple times to stub multiple variables.

• Use rs.unstubAllEnvs() to restore all environment variables changed by this method.

• Example:

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 syntax

rs.stubEnv() returns a Disposable that works with the using syntax to restore the current env stub automatically when the block exits.

The _env binding is intentionally unused, as indicated by its leading underscore. A binding is required by the using syntax, so it cannot be omitted.

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

// NODE_ENV is restored to its original value.

#rs.unstubAllEnvs

• Alias: rstest.unstubAllEnvs

• Type: () => RstestUtilities

Restores all environment variables that were changed using rs.stubEnv to their original values.

• Call this after your test to clean up any environment changes.
• Automatically called before each test if the unstubEnvs config is enabled.

Example:

rs.stubEnv('NODE_ENV', 'test');
// ... run some code
rs.unstubAllEnvs();
expect(process.env.NODE_ENV).not.toBe('test');

When stubbing environment variables in multiple tests, call rs.unstubAllEnvs() in an afterEach hook to restore them after every test:

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

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

#rs.stubGlobal

• Alias: rstest.stubGlobal

• Type: (name: string | number | symbol, value: unknown) => RstestUtilities & Disposable

Temporarily sets a global variable to the specified value. Useful for mocking global objects or functions.

• You can call this multiple times to stub multiple globals.

• Use rs.unstubAllGlobals() to restore all globals changed by this method.

• Example:

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

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

• using syntax

rs.stubGlobal() returns a Disposable that works with the using syntax to restore the current global stub automatically when the block exits.

The _global binding is intentionally unused, as indicated by its leading underscore. A binding is required by the using syntax, so it cannot be omitted.

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

// myGlobal is restored to its original value.

#rs.unstubAllGlobals

• Alias: rstest.unstubAllGlobals

• Type: () => RstestUtilities

Restores all global variables that were changed using rs.stubGlobal to their original values.

• Call this after your test to clean up any global changes.
• Automatically called before each test if the unstubGlobals config is enabled.

Example:

rs.stubGlobal('myGlobal', 123);
// ... run some code
rs.unstubAllGlobals();
expect(globalThis.myGlobal).toBeUndefined();

When stubbing global variables in multiple tests, call rs.unstubAllGlobals() in an afterEach hook to restore them after every test:

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

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

#rs.setConfig

• Alias: rstest.setConfig

• Type:

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

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

Dynamically updates the runtime configuration for the current test file. Useful for temporarily overriding test settings such as timeouts, concurrency, or mock behavior.

Example:

rs.setConfig({ testTimeout: 1000, retry: 2 });
// ... run some code with the new config
rs.resetConfig(); // Restore to default config

#rs.resetConfig

• Alias: rstest.resetConfig

• Type: () => void

Resets the runtime configuration that was changed using rs.setConfig back to the default values.

#rs.getConfig

• Alias: rstest.getConfig

• Type: () => RuntimeConfig

Retrieves the current runtime configuration for the test file. Useful for inspecting or logging the current settings.

Example:

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

#rs.waitFor

• Alias: rstest.waitFor

• Type:

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

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

Retries callback until it succeeds (does not throw) or timeout is reached.

• If options is a number, it is treated as timeout.
• If timeout is reached, it throws the last error from the callback.

Example:

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

#rs.waitUntil

• Alias: rstest.waitUntil

• Type:

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

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

Calls callback repeatedly only while it returns undefined (no value) or any falsy value. It resolves when the callback returns a truthy value.

• If options is a number, it is treated as timeout.
• If the callback throws, execution is interrupted immediately and the error is thrown.
• If timeout is reached, it throws a timeout error.

Example:

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