#Rspack

This guide covers how to integrate Rstest with Rspack for seamless testing in your Rspack projects.

#Quick start

To add Rstest to an existing Rspack project, follow the Quick Start to install and set up test scripts.

#Reuse Rspack config

@rstest/adapter-rspack is an official adapter that allows Rstest to automatically inherit configuration from your existing Rspack config file. This ensures your test environment matches your build configuration without duplication.

#Install adapter

npm add @rstest/adapter-rspack -D

yarn add @rstest/adapter-rspack -D

pnpm add @rstest/adapter-rspack -D

bun add @rstest/adapter-rspack -D

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

#Extend your config

Using the withRspackConfig function from the adapter, you can extend your Rstest configuration from the Rspack config file.

import { defineConfig } from '@rstest/core';
import { withRspackConfig } from '@rstest/adapter-rspack';

export default defineConfig({
  extends: withRspackConfig(),
  // Additional rstest-specific configuration
});

This will automatically:

• Load your rspack.config.ts file
• Map compatible Rspack options to Rstest configuration
• Merge with any additional Rstest config you provide
• Add the loaded Rspack config file to forceRerunTriggers, so --changed runs the full test suite when that config changes

By default, the adapter uses process.cwd() to resolve the Rspack config. If your config lives elsewhere, you can use the cwd option. See API for more details.

#Example project

See the Rspack adapter example for a complete React project that inherits its Rspack configuration in Rstest.

#API

#withRspackConfig(options)

Returns a configuration function that loads Rspack config and converts it to Rstest configuration.

#cwd

• Type: string
• Default: process.cwd()

The working directory to resolve the Rspack config file.

When your Rspack config is in a different directory or you are running tests in a monorepo (where your process.cwd() is not your config directory), you can specify the cwd option to resolve the Rspack config file from a different directory.

export default defineConfig({
  extends: withRspackConfig({
    cwd: './packages/my-app',
  }),
});

#configPath

• Type: string
• Default: './rspack.config.ts'

Path to rspack config file.

#configName

• Type: string
• Default: undefined

Select a named configuration when using multi-config in your Rspack config file. Set to a string to use the config with a matching name field.

If your Rspack config exports an array of configurations:

// rspack.config.ts
export default [
  {
    name: 'client',
    target: 'web',
    entry: './src/client.ts',
    // ...
  },
  {
    name: 'server',
    target: 'node',
    entry: './src/server.ts',
    // ...
  },
];

You can select a specific configuration in your Rstest config:

export default defineConfig({
  extends: withRspackConfig({
    configName: 'client',
  }),
});

When you need to test multiple parts of your application with different configurations independently, you can define multiple Rstest projects:

export default defineConfig({
  projects: [
    {
      extends: withRspackConfig({ configName: 'server' }),
      include: ['tests/server/**/*.{test,spec}.?(c|m)[jt]s'],
    },
    {
      extends: withRspackConfig({ configName: 'client' }),
      include: ['tests/client/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    },
  ],
});

#env

• Type: Record<string, unknown> | string[]
• Default: undefined

Environment values passed to the Rspack config function. This corresponds to the env parameter in rspack.config.ts when exporting a function:

// rspack.config.ts
export default (env) => {
  console.log(env); // receives the values from adapter
  return {/* ... */};
};

#nodeEnv

• Type: string
• Default: undefined

The NODE_ENV value used when loading the Rspack config.

#modifyRspackConfig

• Type: (config: RspackOptions) => RspackOptions
• Default: undefined

Modify the Rspack config before it gets converted to Rstest config:

export default defineConfig({
  extends: withRspackConfig({
    modifyRspackConfig: (rspackConfig) => {
      delete rspackConfig.resolve?.alias;
      return rspackConfig;
    },
  }),
});

#Configuration mapping

withRspackConfig does not copy the entire Rspack configuration into the test compiler unchanged. It routes each option according to which layer owns the behavior: equivalent concepts become Rstest configuration, compatible compiler options reach Rspack, and settings that would conflict with the generated test build remain under Rstest's control.

The following tables cover every top-level option in Rspack 2.1. Some options appear in more than one table because their sub-options have different owners. For example, Rstest must understand resolve.alias, while Rspack itself must receive resolve.fallback; similarly, Rstest derives its cache from cache, but does not reuse every persistent-cache tuning option.

Some Rspack options have direct equivalents in Rstest. The adapter converts these values before creating the compiler because Rstest needs them to select the test environment, resolve test modules, or prepare build output. Only the listed resolve fields are shared with Rsbuild; the remaining Rspack resolver options are handled in the next table.

Other options still affect the final Rspack compilation but cannot safely replace the generated test configuration. The adapter combines them according to the option's semantics—for example, rules and plugins are appended, Rspack-only resolver options are merged, and the generated output path is retained. Rstest's later compiler hooks can still restore values required by the test runtime.

The next group does not overlap with Rstest-owned build structure, so the adapter passes it to the compiler through Rsbuild's mergeConfig. This uses Rspack's standard merge semantics and keeps the generated configuration as the base. Arrays and nested objects therefore follow Rspack's normal merge behavior instead of being assigned by an adapter-specific rule.

The remaining options either describe an application build, belong to a multi-compiler or dev-server workflow, or control output that Rstest reports itself. Applying them would replace generated test structure or create a setting with no observable effect, so the adapter leaves them under Rstest's control. extends is the exception: Rspack CLI consumes it while loading the config, so the adapter receives the already-merged result rather than forwarding the extends field.

Rspack 2.1 moved the former top-level snapshot option to cache.snapshot, so it is no longer a top-level configuration option. Persistent Rspack cache is converted into Rstest's generated build cache; Rspack-specific tuning fields such as cache.snapshot, maxAge, portable, and readonly are not copied to that generated cache.

#Debug config

Set DEBUG=rstest to write the resolved Rstest, Rsbuild, and Rspack configurations. The command output prints their locations. Inspect the generated Rspack configuration to verify which options reach the compiler:

DEBUG=rstest rstest

#Related documentation

• Rspack configuration overview
• Rstest configuration overview