> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

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


**CLI**

```bash
npx rstest --testEnvironment=jsdom
```


**rstest.config.ts**

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

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


### DOM testing

Rstest supports [jsdom](https://github.com/jsdom/jsdom) and [happy-dom](https://github.com/capricorn86/happy-dom) for mocking DOM and browser APIs.

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

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

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

You also need to install the corresponding package:

For jsdom


```sh [npm]
npm add jsdom -D
```

```sh [yarn]
yarn add jsdom -D
```

```sh [pnpm]
pnpm add jsdom -D
```

```sh [bun]
bun add jsdom -D
```

```sh [deno]
deno add npm:jsdom -D
```

For happy-dom


```sh [npm]
npm add happy-dom -D
```

```sh [yarn]
yarn add happy-dom -D
```

```sh [pnpm]
pnpm add happy-dom -D
```

```sh [bun]
bun add happy-dom -D
```

```sh [deno]
deno add npm:happy-dom -D
```

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

```ts
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`:

```ts title="rstest.config.ts"
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](https://github.com/jsdom/jsdom#customizing-jsdom).
- For `happy-dom`, it's passed to the `Window` constructor. You can find available options in the [happy-dom documentation](https://github.com/capricorn86/happy-dom/wiki/Window).

#### Environment prebundle


[Added in v0.11.6](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.6)

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. Other major versions stay on the native path unless `prebundle: true` is set explicitly.

```ts title="rstest.config.ts"
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


[Added in v0.10.5](https://github.com/web-infra-dev/rstest/releases/tag/v0.10.5)

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

```ts title="example.test.ts"
// @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:

```ts title="example.test.ts"
// @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](https://github.com/web-infra-dev/rstest/tree/main/examples/node)
- [Rstest + jsdom + react](https://github.com/web-infra-dev/rstest/tree/main/examples/react)