#testEnvironment

• Type: 'node' | 'jsdom' | 'happy-dom' | { name: EnvironmentName, options?: EnvironmentOptions, prebundle?: 'auto' | boolean }
• Default: 'node'
• CLI: --testEnvironment=node

The environment that will be used for testing.

The default environment in Rstest is a Node.js environment. If you are building a web application, you can use a browser-like environment through jsdom or happy-dom instead.

npx rstest --testEnvironment=jsdom

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

export default defineConfig({
  testEnvironment: 'jsdom',
});

#DOM testing

Rstest supports jsdom and happy-dom for mocking DOM and browser APIs.

If you want to enable DOM testing, you can use the following configuration:

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

export default defineConfig({
  testEnvironment: 'jsdom', // or 'happy-dom'
});

You also need to install the corresponding package:

For jsdom

npm add jsdom -D

yarn add jsdom -D

pnpm add jsdom -D

bun add jsdom -D

deno add npm:jsdom -D

For happy-dom

npm add happy-dom -D

yarn add happy-dom -D

pnpm add happy-dom -D

bun add happy-dom -D

deno add npm:happy-dom -D

After enabling DOM testing, you can write tests that use browser APIs like document and window.

test('DOM test', () => {
  document.body.innerHTML = '<p class="content">hello world</p>';
  const paragraph = document.querySelector('.content');
  expect(paragraph?.innerHTML).toBe('hello world');
});

#Environment options

You can also pass options to the test environment. This is useful for configuring jsdom or happy-dom. For example, you can set the url for jsdom:

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

export default defineConfig({
  testEnvironment: {
    name: 'jsdom',
    options: {
      // jsdom-specific options
      url: 'https://example.com',
    },
  },
});

The options object is passed directly to the environment's constructor.

When using a Node worker pool (forks, threads, vmForks, or vmThreads), the options must be structured-cloneable because they are sent to a worker. Function-valued options such as beforeParse are not supported in these pools and are rejected before a test file is dispatched.

On Bun, forks and vmForks use JSON IPC, so their options must also be JSON-compatible. Values such as Map, Set, Date, class instances, and BigInt are rejected because JSON IPC would change their shape or fail to serialize them.

• For jsdom, it's passed to the JSDOM constructor. You can find available options in the jsdom documentation.
• For happy-dom, it's passed to the Window constructor. You can find available options in the happy-dom documentation.

#Environment prebundle

Rstest can prebundle a test environment before workers load it. This reduces repeated module resolution and initialization work when many test files use the same DOM environment. Since 0.12.0, this optimization is enabled by default in auto mode.

The prebundle option accepts:

• 'auto': prebundle Rstest-tested versions of the built-in jsdom and happy-dom environments. Unknown versions use native loading.
• true: always prebundle the selected built-in environment.
• false: disable the prebundle and load the environment natively.

The current automatic compatibility matrix covers jsdom 15–26 and 29–30, and happy-dom 20–21. Other major versions stay on the native path unless prebundle: true is set explicitly.

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

export default defineConfig({
  testEnvironment: {
    name: 'jsdom',
    prebundle: 'auto',
  },
});

#Troubleshooting the prebundle

The prebundle is optional. If your DOM environment behaves differently after enabling it, set prebundle: false to load it natively.

Rstest automatically falls back to native loading if it cannot build, load, or validate a prebundle. Validation covers known problem cases, not every API:

• Bundling can change how an environment resolves runtime assets, executable helpers, and optional or native dependencies, even if the bundle imports successfully.
• For example, jsdom 27 and 28 can resolve an optional CSS implementation differently after bundling, causing getComputedStyle() to fail. auto uses native loading for these versions. With prebundle: true, Rstest probes this known case and falls back if validation fails.

The environment package is resolved from the project's dependencies first, then the Rstest workspace root, and finally through @rstest/core's native dependency resolution for backward compatibility.

With a jsdom or happy-dom test environment and prebundle enabled, bundled import, literal import(), and require requests for the same installation of that environment package reuse the environment module. If the prebundle fails, these requests share the native fallback. Explicit externals, other installations of the environment package, and requests inside external dependencies keep their existing loading behavior. Setting prebundle: false disables this reuse.

#Environment comments

You can override the environment for a single test file by adding an environment comment near the top of the file:

// @rstest-environment jsdom

test('DOM test', () => {
  document.body.innerHTML = '<p>hello world</p>';
  expect(document.querySelector('p')?.textContent).toBe('hello world');
});

Use @rstest-environment-options to pass environment options for the annotated file. The options must be a single-line JSON object:

// @rstest-environment jsdom
// @rstest-environment-options { "url": "https://example.com/" }

test('sets the jsdom url', () => {
  expect(window.location.href).toBe('https://example.com/');
});

Rstest also recognizes @vitest-environment and @jest-environment aliases, including their -options variants, to make migration easier.

Environment comments support the built-in Node runner environments: node, jsdom, and happy-dom. They do not apply to browser mode. If most files use the same environment, prefer configuring testEnvironment or separate projects in rstest.config.ts.

#Examples

• Rstest + node
• Rstest + jsdom + react