feat(core): support custom test environments

e2e/dom/customBuiltinNodeEnvironment.test.ts

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from '@rstest/core';
+import { runCli } from './utils';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const teardownFile = join(
+  __dirname,
+  'fixtures',
+  'test',
+  'custom-node-environment.teardown.txt',
+);
+
+describe('custom builtin node environment', () => {
+  it('should load a local custom environment that extends builtin node', async () => {
+    fs.rmSync(teardownFile, { force: true });
+
+    const { expectExecSuccess } = await runCli(
+      'test/customNodeEnvironment',
+      undefined,
+      {
+        args: ['--config', 'rstest.customNodeEnvironment.config.mts'],
+      },
+    );
+
+    await expectExecSuccess();
+
+    expect(fs.readFileSync(teardownFile, 'utf8')).toBe('node-marker');
+
+    fs.rmSync(teardownFile, { force: true });
+  });
+});

e2e/dom/customEnvironment.test.ts

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from '@rstest/core';
+import { runCli } from './utils';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const teardownFile = join(
+  __dirname,
+  'fixtures',
+  'test',
+  'custom-environment.teardown.txt',
+);
+
+describe('custom environment', () => {
+  it('should load a local custom environment and extend builtin environments', async () => {
+    fs.rmSync(teardownFile, { force: true });
+
+    const { expectExecSuccess } = await runCli(
+      'test/customEnvironment',
+      undefined,
+      {
+        args: ['--config', 'rstest.customEnvironment.config.mts'],
+      },
+    );
+
+    await expectExecSuccess();
+
+    expect(fs.readFileSync(teardownFile, 'utf8')).toBe('custom-marker');
+
+    fs.rmSync(teardownFile, { force: true });
+  });
+});

e2e/dom/fixtures/package.json

@@ -9,7 +9,8 @@
   },
   "dependencies": {
     "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "react-dom": "^19.2.7",
+    "rstest-environment-package-marker": "workspace:*"
   },
   "devDependencies": {
     "@rsbuild/core": "~2.1.0-beta.0",

e2e/dom/fixtures/rstest-environment-package-marker/index.mjs

@@ -0,0 +1,28 @@
+import { writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const teardownFile = join(
+  __dirname,
+  '..',
+  'test',
+  'package-environment.teardown.txt',
+);
+
+/** @type {import('@rstest/core').TestEnvironment<typeof globalThis, { marker: string }>} */
+const environment = {
+  name: 'package-marker',
+  async setup(global, options) {
+    global.__PACKAGE_ENV_MARKER__ = options.marker;
+
+    return {
+      async teardown() {
+        delete global.__PACKAGE_ENV_MARKER__;
+        await writeFile(teardownFile, options.marker, 'utf8');
+      },
+    };
+  },
+};
+
+export default environment;

e2e/dom/fixtures/rstest-environment-package-marker/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "rstest-environment-package-marker",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "import": "./index.mjs"
+  }
+}

e2e/dom/fixtures/rstest.customEnvironment.config.mts

@@ -0,0 +1,17 @@
+import { defineConfig, type RstestConfig } from '@rstest/core';
+import rsbuildConfig from './rsbuild.config';
+
+export default defineConfig({
+  ...(rsbuildConfig as RstestConfig),
+  setupFiles: ['./test/setup.ts'],
+  testEnvironment: {
+    name: './test/customEnvironment.mjs',
+    target: 'web',
+    options: {
+      marker: 'custom-marker',
+      jsdom: {
+        url: 'https://custom-env.example/',
+      },
+    },
+  },
+});

e2e/dom/fixtures/rstest.customNodeEnvironment.config.mts

@@ -0,0 +1,12 @@
+import { defineConfig, type RstestConfig } from '@rstest/core';
+import rsbuildConfig from './rsbuild.config';
+
+export default defineConfig({
+  ...(rsbuildConfig as RstestConfig),
+  testEnvironment: {
+    name: './test/customNodeEnvironment.mjs',
+    options: {
+      marker: 'node-marker',
+    },
+  },
+});

e2e/dom/fixtures/rstest.packageEnvironment.config.mts

@@ -0,0 +1,12 @@
+import { defineConfig, type RstestConfig } from '@rstest/core';
+import rsbuildConfig from './rsbuild.config';
+
+export default defineConfig({
+  ...(rsbuildConfig as RstestConfig),
+  testEnvironment: {
+    name: 'package-marker',
+    options: {
+      marker: 'package-marker',
+    },
+  },
+});

e2e/dom/fixtures/test/customEnvironment.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { builtinEnvironments } from '@rstest/core';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const teardownFile = path.join(__dirname, 'custom-environment.teardown.txt');
+
+export default {
+  name: 'custom-jsdom',
+  async setup(global, options) {
+    const jsdomEnvironment = await builtinEnvironments.jsdom.setup(
+      global,
+      options.jsdom ?? {},
+    );
+
+    global.__CUSTOM_ENV_MARKER__ = options.marker;
+
+    return {
+      async teardown() {
+        delete global.__CUSTOM_ENV_MARKER__;
+        fs.writeFileSync(teardownFile, String(options.marker));
+        await jsdomEnvironment.teardown();
+      },
+    };
+  },
+};

e2e/dom/fixtures/test/customEnvironment.test.tsx

@@ -0,0 +1,8 @@
+import { expect, test } from '@rstest/core';
+
+test('custom environment can extend builtin jsdom', () => {
+  expect(window.location.href).toBe('https://custom-env.example/');
+  expect(
+    (globalThis as { __CUSTOM_ENV_MARKER__?: string }).__CUSTOM_ENV_MARKER__,
+  ).toBe('custom-marker');
+});

e2e/dom/fixtures/test/customNodeEnvironment.mjs

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { builtinEnvironments } from '@rstest/core';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const teardownFile = path.join(
+  __dirname,
+  'custom-node-environment.teardown.txt',
+);
+
+export default {
+  name: 'custom-node',
+  async setup(global, options) {
+    const nodeEnvironment = await builtinEnvironments.node.setup(
+      global,
+      options,
+    );
+
+    global.__CUSTOM_NODE_ENV_MARKER__ = options.marker;
+
+    return {
+      async teardown() {
+        delete global.__CUSTOM_NODE_ENV_MARKER__;
+        fs.writeFileSync(teardownFile, String(options.marker));
+        await nodeEnvironment.teardown();
+      },
+    };
+  },
+};

e2e/dom/fixtures/test/customNodeEnvironment.test.ts

@@ -0,0 +1,10 @@
+import { expect, test } from '@rstest/core';
+
+test('custom environment can extend builtin node', () => {
+  expect(
+    (globalThis as { __CUSTOM_NODE_ENV_MARKER__?: string })
+      .__CUSTOM_NODE_ENV_MARKER__,
+  ).toBe('node-marker');
+  expect('window' in globalThis).toBe(false);
+  expect(typeof process.cwd()).toBe('string');
+});

e2e/dom/fixtures/test/packageEnvironment.test.ts

@@ -0,0 +1,8 @@
+import { expect, test } from '@rstest/core';
+
+test('custom environment can load from rstest-environment-* package fallback', () => {
+  expect(
+    (globalThis as { __PACKAGE_ENV_MARKER__?: string }).__PACKAGE_ENV_MARKER__,
+  ).toBe('package-marker');
+  expect('window' in globalThis).toBe(false);
+});

e2e/dom/handledError.test.ts

@@ -25,6 +25,18 @@ describe('custom-environment', () => {
     );
     await expectExecFailed();
 
-    expectStderrLog(/Unknown test environment: custom-environment/);
+    expectStderrLog(/Failed to resolve testEnvironment "custom-environment"/);
+  });
+});
+
+describe('prototype-environment-name', () => {
+  it('should throw an explicit resolution error for prototype property names', async () => {
+    const { expectExecFailed, expectStderrLog } = await runCli(
+      filters,
+      'toString',
+    );
+    await expectExecFailed();
+
+    expectStderrLog(/Failed to resolve testEnvironment "toString"/);
   });
 });

e2e/dom/packageEnvironment.test.ts

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from '@rstest/core';
+import { runCli } from './utils';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const teardownFile = join(
+  __dirname,
+  'fixtures',
+  'test',
+  'package-environment.teardown.txt',
+);
+
+describe('package environment fallback', () => {
+  it('should resolve rstest-environment-* packages from testEnvironment.name', async () => {
+    fs.rmSync(teardownFile, { force: true });
+
+    const { expectExecSuccess } = await runCli(
+      'test/packageEnvironment',
+      undefined,
+      {
+        args: ['--config', 'rstest.packageEnvironment.config.mts'],
+      },
+    );
+
+    await expectExecSuccess();
+
+    expect(fs.readFileSync(teardownFile, 'utf8')).toBe('package-marker');
+
+    fs.rmSync(teardownFile, { force: true });
+  });
+});

e2e/watch/customEnvironment.test.ts

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it, rs } from '@rstest/core';
+import { prepareFixtures, runRstestCli } from '../scripts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+rs.setConfig({
+  retry: 3,
+});
+
+describe.skipIf(process.platform === 'win32')(
+  'watch custom environment',
+  () => {
+    it('should re-run all tests when custom environment file changes', async () => {
+      const fixturesTargetPath = `${__dirname}/fixtures-test-custom-environment${process.env.RSTEST_OUTPUT_MODULE !== 'false' ? '-module' : ''}`;
+
+      const { fs } = await prepareFixtures({
+        fixturesPath: `${__dirname}/fixtures-custom-environment`,
+        fixturesTargetPath,
+      });
+
+      const { cli } = await runRstestCli({
+        command: 'rstest',
+        args: ['watch', '--disableConsoleIntercept'],
+        options: {
+          nodeOptions: {
+            cwd: fixturesTargetPath,
+          },
+        },
+      });
+
+      await cli.waitForStdout('Duration');
+      expect(cli.stdout).toMatch('Tests 1 passed');
+      expect(cli.stdout).not.toMatch('Test files to re-run:');
+
+      const environmentPath = path.join(
+        fixturesTargetPath,
+        'test-environment.mjs',
+      );
+      const environmentHelperPath = path.join(
+        fixturesTargetPath,
+        'environment-helper.mjs',
+      );
+
+      cli.resetStd();
+      fs.update(environmentPath, (content) => {
+        return content.replace(
+          'global.__CUSTOM_ENV_MARKER__ = marker;',
+          'global.__CUSTOM_ENV_MARKER__ = `${marker}-modified`;',
+        );
+      });
+      fs.update(path.join(fixturesTargetPath, 'index.test.ts'), (content) => {
+        return content.replace("'initial'", "'initial-modified'");
+      });
+
+      await cli.waitForStdout('Duration');
+      expect(cli.stdout).toMatch('Tests 1 passed');
+
+      cli.resetStd();
+      fs.update(path.join(fixturesTargetPath, 'index.test.ts'), (content) => {
+        return content.replace("'initial-modified'", "'dependency-modified'");
+      });
+
+      await cli.waitForStdout('Tests 1 failed');
+
+      cli.resetStd();
+      fs.update(environmentHelperPath, (content) => {
+        return content.replace("'initial'", "'dependency'");
+      });
+
+      await cli.waitForStdout('Duration');
+      expect(cli.stdout).toMatch('Tests 1 passed');
+
+      cli.resetStd();
+      fs.delete(environmentPath);
+
+      await cli.waitForStderr('Failed to resolve testEnvironment');
+
+      cli.exec.kill();
+    });
+  },
+);

e2e/watch/fixtures-custom-environment/environment-helper.mjs

@@ -0,0 +1 @@
+export const marker = 'initial';