#Adapters

Adapters convert configuration from other tools, such as build tools or CLIs, into a format that Rstest supports. With official or custom adapters, you can reuse existing configuration, avoid defining it separately for multiple tools, and keep tests consistent with your project's configuration.

Adapters pass the converted configuration to Rstest through extends. When reusing build configuration, Rstest still manages the test entry points and runtime, and adapters select and transform compatible options.

#Using official adapters

If your project already uses Rsbuild, Rslib, or Rspack, an official adapter lets you reuse aliases, code transformation settings, and compatible plugins. Choose the adapter for your build tool:

#Install and use an adapter

For example, to reuse an Rsbuild configuration, first set up Rstest, then install the adapter:

npm add @rstest/adapter-rsbuild -D

yarn add @rstest/adapter-rsbuild -D

pnpm add @rstest/adapter-rsbuild -D

bun add @rstest/adapter-rsbuild -D

deno add npm:@rstest/adapter-rsbuild -D

@rstest/core runs your tests; @rstest/adapter-rsbuild loads and converts your existing Rsbuild configuration.

import { withRsbuildConfig } from '@rstest/adapter-rsbuild';
import { defineConfig } from '@rstest/core';

export default defineConfig({
  extends: withRsbuildConfig(),
  testEnvironment: 'node',
  testTimeout: 10_000,
});

The adapter loads your Rsbuild configuration and reuses its compatible compilation settings. For example, an alias already defined in rsbuild.config.ts is available to your tests without defining it again in rstest.config.ts.

This example runs tests in Node.js. For tests that need a DOM, install and configure jsdom or happy-dom. Keep test-specific settings, such as timeouts and coverage, in your Rstest configuration.

#Select a configuration

If your build configuration is in a different location, pass configPath. For an Rsbuild project with multiple environments, use environmentName to select the environment to merge with the shared configuration:

import { withRsbuildConfig } from '@rstest/adapter-rsbuild';
import { defineConfig } from '@rstest/core';

export default defineConfig({
  extends: withRsbuildConfig({
    configPath: './config/rsbuild.config.ts',
    environmentName: 'web',
  }),
  testEnvironment: 'node',
});

Use a name defined in your build configuration. The equivalent selection options are libId for Rslib and configName for Rspack. To test several configurations independently, set extends on each Rstest project.

For all options, configuration mappings, and plugin handling, see the corresponding reference:

• Rsbuild adapter reference
• Rslib adapter reference
• Rspack adapter reference

#Configuration merging

Your local Rstest configuration takes precedence over the configuration returned by an adapter. For example, testEnvironment: 'node' in the examples above overrides any environment inferred by the adapter.

Object fields such as resolve and source are deep-merged. Arrays follow the rules for their option: plugins and setupFiles are concatenated, while include and reporters are replaced. See configuration merging for the complete rules and how to compose multiple presets.

#Creating a custom adapter

If your toolchain has its own configuration format, you can write an adapter to map it to Rstest options. For a shared preset that already uses Rstest options, pass the configuration object directly to extends.

An adapter implements ExtendConfigFn: it receives the user's Rstest configuration and returns an ExtendConfig object or a Promise resolving to one. It can read the user configuration when deciding what to return, but should not mutate it. The returned configuration cannot define projects.

For example, a tool might store aliases and compile-time constants in this format:

export default {
  aliases: {
    '@': './src',
  },
  globals: {
    __VERSION__: '"1.0.0"',
  },
};

Map these fields to Rstest's resolve.alias and source.define:

import type { ExtendConfigFn } from '@rstest/core';
import myConfig from './my.config';

export const withMyConfig: ExtendConfigFn = () => ({
  resolve: {
    alias: myConfig.aliases,
  },
  source: {
    define: myConfig.globals,
  },
});

#Using your custom adapter

Pass the adapter to extends and keep test-specific settings in the local configuration:

import { defineConfig } from '@rstest/core';
import { withMyConfig } from './my-adapter';

export default defineConfig({
  extends: withMyConfig,
  testTimeout: 8000,
});

#Advanced usage: adapters with options

To let callers customize an adapter, expose a function that accepts options and returns an ExtendConfigFn. For example, this version lets callers choose a test environment while reusing the same aliases and constants:

import type { ExtendConfigFn } from '@rstest/core';
import myConfig from './my.config';

interface MyAdapterOptions {
  testEnvironment?: 'node' | 'happy-dom';
}

export function withMyConfig(options: MyAdapterOptions = {}): ExtendConfigFn {
  return () => ({
    resolve: {
      alias: myConfig.aliases,
    },
    source: {
      define: myConfig.globals,
    },
    testEnvironment: options.testEnvironment ?? 'node',
  });
}

After installing happy-dom, use extends: withMyConfig({ testEnvironment: 'happy-dom' }) to select that environment. Local Rstest settings still take precedence over the adapter's defaults.