testEnvironment

类型： 'node' | 'jsdom' | 'happy-dom' | string | { name: EnvironmentName, options?: EnvironmentOptions }
默认值： 'node'
CLI： --testEnvironment=node

测试时所使用的环境。

Rstest 默认使用 Node.js 作为测试环境。如果你在开发 Web 应用，可以使用类浏览器环境，如 jsdom 或 happy-dom。

CLI

rstest.config.ts

npx rstest --testEnvironment=jsdom

DOM 测试

Rstest 支持使用 jsdom 和 happy-dom 来模拟 DOM 和浏览器 API。

如果你想启用 DOM 测试，可以使用如下配置：

rstest.config.ts

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

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

你还需要安装对应的包：

使用 jsdom

npm

yarn

pnpm

bun

deno

npm add jsdom -D

使用 happy-dom

npm

yarn

pnpm

bun

deno

npm add happy-dom -D

启用 DOM 测试后，你可以在测试用例中使用 document 和 window 等浏览器 API。

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

环境选项

你也可以为测试环境传递选项。这对于配置 jsdom 或 happy-dom 非常有用。例如，你可以为 jsdom 设置 url：

rstest.config.ts

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

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

options 对象会直接传递给环境的构造函数。

对于 jsdom，它会传递给 JSDOM 构造函数。你可以在 jsdom 文档中找到可用的选项。
对于 happy-dom，它会传递给 Window 构造函数。你可以在 happy-dom 文档中找到可用的选项。

自定义 environment

Added in v0.10.2

Rstest 也支持通过 testEnvironment.name 加载自定义 environment。

可以传包名。
可以传相对或绝对 JavaScript 文件路径，例如 .js 或 .mjs。
对于包名，testEnvironment: 'foo' 也会继续尝试解析 rstest-environment-foo。

自定义 environment 需要默认导出一个 environment 对象，或导出一个具名 environment 对象。

my-environment.mjs

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

/** @type {import('@rstest/core').TestEnvironment<typeof globalThis, { marker: string }>} */
const environment = {
  name: 'custom-jsdom',
  async setup(global, options) {
    const base = await builtinEnvironments.jsdom.setup(global, {
      url: 'https://example.com',
    });

    global.__MARKER__ = options.marker;

    return {
      async teardown() {
        delete global.__MARKER__;
        await base.teardown();
      },
    };
  },
};

export default environment;

rstest.config.ts

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

export default defineConfig({
  testEnvironment: {
    name: './my-environment.mjs',
    options: {
      marker: 'custom-marker',
    },
  },
});

@rstest/core 导出了 builtinEnvironments，这样你可以基于 node、jsdom 或 happy-dom 做扩展，而不是从零实现。

Rstest 当前会按 JavaScript module 加载自定义 environment 文件，因此暂不支持直接传 .ts custom environment 文件路径。如果你需要类型检查，可以先用 TypeScript 编写，再编译成 .mjs 或 .js，或者在 JavaScript 文件里使用 JSDoc 标注类型。

Rstest 暂不支持文件级 @vitest-environment 或 @jest-environment 注释。如果你需要按文件切换环境，当前建议用不同的 project 或不同的配置文件来拆分。

什么时候用自定义 environment，什么时候用 setupFiles

当你需要为每个测试文件定义或包装底层宿主环境本身时，用自定义 environment。

切换或扩展 node、jsdom、happy-dom。
在测试模块执行前创建全局对象或宿主 API。
管理 environment 级别的 teardown，例如关闭类浏览器运行时或清理注入的全局变量。

当环境本身已经正确，只需要在该环境里做测试初始化时，用 setupFiles。

注册 @testing-library/jest-dom 这类 matcher。
安装 fake timers、snapshot serializer、mock 或通用 hooks。
执行依赖当前 environment 已经准备好的项目级初始化逻辑。

一句话区分：testEnvironment 决定“测试运行在什么宿主里”；setupFiles 决定“测试在这个宿主里如何初始化”。

#testEnvironment

#DOM 测试

#环境选项

#自定义 environment

#什么时候用自定义 environment，什么时候用 setupFiles

#示例

testEnvironment

DOM 测试

环境选项

自定义 environment

什么时候用自定义 environment，什么时候用 setupFiles

示例