#Configure Rstest

#Configuration file

When you use the CLI of Rstest, Rstest will automatically read the configuration file in the root directory of the current project and resolve it in the following order:

• rstest.config.mjs
• rstest.config.ts
• rstest.config.js
• rstest.config.cjs
• rstest.config.mts
• rstest.config.cts

We recommend using the .mjs or .ts format for the configuration file and importing the defineConfig utility function from @rstest/core. It provides friendly TypeScript type hints and autocompletion, which can help you avoid errors in the configuration.

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

export default defineConfig({
  testEnvironment: 'node',
});

If you are developing a non-TypeScript project, you can use the .mjs format for the configuration file.

#Specify config file

Rstest CLI uses the --config option to specify the config file, which can be set to a relative path or an absolute path.

{
  "scripts": {
    "test": "rstest --config scripts/rstest.config.mjs"
  }
}

You can also abbreviate the --config option to -c:

rstest -c scripts/rstest.config.mjs

#Configure Rsbuild

Rstest's build configuration inherits from Rsbuild. Therefore, in Rstest, you can use most of the Rsbuild configurations, such as:

• Using Rsbuild plugins through plugins;
• Configuring module resolution behavior through resolve;
• Configuring Rspack through tools.rspack;
• Configuring builtin:swc-loader through tools.swc.

More configurations can be referred to Build Configurations.

#Configure Rspack

Rstest uses Rspack for building, so you can directly use Rspack's configuration options to configure Rstest's build behavior.

More details can be referred to Configure Rspack.

#Configure SWC

Rstest uses Rspack's builtin:swc-loader to transform JavaScript and TypeScript code by default, which is the Rust version of swc-loader.

Rstest exposes some options to configure builtin:swc-loader:

• tools.swc: Used to configure the options of builtin:swc-loader.
• source.include: Used to specify the files that need to be compiled by SWC.
• source.exclude: Used to exclude files that do not need to be compiled by SWC.

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

export default defineConfig({
  tools: {
    swc: {
      jsc: {
        transform: {
          react: {
            runtime: 'automatic',
          },
        },
        experimental: {
          plugins: [['@swc/plugin-emotion', {}]],
        },
      },
    },
  },
});

#SWC plugin version

Please note that SWC's plugins are still an experimental feature. Currently, SWC's Wasm plugins are not backward compatible, and the version of SWC plugins is strongly coupled with the swc_core version that Rspack depends on.

This means that you need to choose SWC plugins that match the current swc_core version to make them work properly. If the SWC plugin version you use does not match the swc_core version that Rspack depends on, Rspack will throw errors during the build. Please refer to Rspack FAQ - SWC plugin version mismatch for handling.

#Detect Rstest environment

You can use process.env.RSTEST to detect whether it is an Rstest test environment to apply different configurations/codes in your tests.

if (process.env.RSTEST) {
  // 'true' will be returned in the rstest environment
  // do something...
}

It should be noted that if you use process.env.RSTEST in your source code, define process.env.RSTEST as false in your build configuration (such as rsbuild.config.ts) during production builds, this will help the bundler eliminate dead code.

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

export default defineConfig({
  source: {
    define: {
+      'process.env.RSTEST': false,
    },
  },
});

If you are developing the Rsbuild plugin, you can use api.context.callerName to determine the current plugin is being called.

export const myPlugin = {
  name: 'my-plugin',
  setup(api) {
    const { callerName } = api.context;

    if (callerName === 'rstest') {
      // ...
    } else if (callerName === 'rsbuild') {
      // ...
    }
  },
};