#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:

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

The return value also includes a copy of the resolved expect.poll configuration. Modifying this copy does not change the runtime configuration.

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 },
);