#Utilities

A set of useful utility functions.

#rstest.stubEnv

• Alias: rs.stubEnv

• Type: (name: string, value: string | undefined) => Rstest

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 rstest.unstubAllEnvs() to restore all environment variables changed by this method.

Example:

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

rstest.stubEnv('MY_VAR', undefined);
expect(process.env.MY_VAR).toBeUndefined();
expect(import.meta.env.MY_VAR).toBeUndefined();

#rstest.unstubAllEnvs

• Alias: rs.unstubAllEnvs

• Type: () => Rstest

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

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

Example:

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

#rstest.stubGlobal

• Alias: rs.stubGlobal

• Type: (name: string | number | symbol, value: unknown) => Rstest

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 rstest.unstubAllGlobals() to restore all globals changed by this method.

Example:

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

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

#rstest.unstubAllGlobals

• Alias: rs.unstubAllGlobals

• Type: () => Rstest

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

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

Example:

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

#rstest.setConfig

• Alias: rs.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:

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

#rstest.resetConfig

• Alias: rs.resetConfig

• Type: () => void

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

#rstest.getConfig

• Alias: rs.getConfig

• Type: () => RuntimeConfig

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

Example:

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

#rstest.waitFor

• Alias: rs.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 },
);

#rstest.waitUntil

• Alias: rs.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 },
);