#Rsbuild

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

#Quick start

#New project

Create a new Rsbuild + Rstest project. Add the --tools rstest flag when creating:

npm create rsbuild@latest -- --tools rstest

The scaffold includes Rstest and demo tests. Run them with npm run test.

#Existing project

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

#Reuse Rsbuild config

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

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

#Extend your config

Using the withRsbuildConfig function from the adapter, you can extend your Rstest configuration from the Rsbuild config file.

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

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

This will automatically:

• Load your rsbuild.config.ts file
• Map compatible Rsbuild options to Rstest configuration
• Merge with any additional Rstest config you provide

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

#API

#withRsbuildConfig(options)

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

#cwd

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

The cwd is passed to Rsbuild's loadConfig function. It's the working directory to resolve the Rsbuild config file.

When your Rsbuild 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 Rsbuild config file from a different directory.

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

#configPath

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

Path to rsbuild config file.

#environmentName

• Type: string
• Default: undefined

The environment name in the environments field to use, which will be merged with the common config. Set to a string to use the environment config with a matching name.

By default, the adapter uses the common configuration from Rsbuild. If your Rsbuild config has multiple environment configurations:

// rsbuild.config.ts
export default {
  source: {
    define: {
      'process.env.NODE_ENV': '"development"',
    },
  },
  environments: {
    test: {
      source: {
        define: {
          'process.env.NODE_ENV': '"test"',
        },
      },
    },
    prod: {
      source: {
        define: {
          'process.env.NODE_ENV': '"production"',
        },
      },
    },
  },
};

You can then reference specific environment configurations in your Rstest config. Rstest will adapt the Rsbuild shared configuration and the environment configuration with a matching environmentName to Rstest format.

// For testing the 'test' environment
export default defineConfig({
  extends: withRsbuildConfig({
    environmentName: 'test',
  }),
  // test-environment-specific config
});

When you need to test multiple parts of your application with different configurations independently, you can define multiple Rstest projects. Each project can extend a specific environment configuration by setting the environmentName option.

export default defineConfig({
  projects: [
    {
      extends: withRsbuildConfig({ environmentName: 'node' }),
      include: ['tests/node/**/*.{test,spec}.?(c|m)[jt]s'],
    },
    {
      extends: withRsbuildConfig({ environmentName: 'react' }),
      include: ['tests/react/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
    },
  ],
});

#modifyRsbuildConfig

• Type: (config: RsbuildConfig) => RsbuildConfig | void
• Default: undefined

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

export default defineConfig({
  extends: withRsbuildConfig({
    modifyRsbuildConfig: (rsbuildConfig) => {
      delete rsbuildConfig.source?.define;
      return rsbuildConfig;
    },
  }),
});

#Configuration mapping

The adapter automatically maps these Rsbuild options to Rstest:

#Debug config

To see the resolved configuration returned by the adapter, wrap it and log the result:

export default defineConfig({
  extends: async (user) => {
    const config = await withRsbuildConfig()(user);
    console.log('Extended config:', JSON.stringify(config, null, 2));
    return config;
  },
});

#Related documentation

• Rsbuild configuration overview
• Rstest configuration overview