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

• 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. This optimization is disabled by default and must be explicitly enabled.

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 (default): disable the prebundle and load the environment natively.

The current automatic compatibility matrix covers jsdom 15–26 and 29–30, and happy-dom 20. 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',
  },
});

If Rstest cannot build, load, or validate a prebundle, it falls back to the environment's native entry before setting up the test environment. The environment package is resolved from the project's dependency tree first, then from the Rstest workspace root, and finally through @rstest/core's native dependency resolution for backward compatibility.

The prebundle is a performance optimization, not a requirement for DOM testing. Bundling a third-party Node.js package can change how it resolves runtime assets, executable helper files, and optional or native dependencies, even when the generated bundle imports successfully. For example, jsdom 27 and 28 can resolve an optional CSS implementation differently after bundling, causing getComputedStyle() to fail at runtime. These versions therefore use native loading in auto mode. When prebundle: true is used, Rstest probes this known path and falls back to native loading if validation fails. This probe cannot cover every API, so set prebundle: false if your environment behaves differently after Rstest bundles it.

If jsdom or happy-dom provides an official Node.js-compatible bundled entry in the future, Rstest can prefer that entry instead of generating its own prebundle. In that case, Rstest's generated prebundle may no longer be necessary for that environment.

#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