> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

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

```ts title="rstest.config.ts"
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.

```json title="package.json"
{
  "scripts": {
    "test": "rstest --config scripts/rstest.config.mjs"
  }
}
```

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

```bash
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](/config/build/plugins.md);
- Configuring module resolution behavior through [resolve](/config/build/resolve.md);
- Configuring Rspack through [tools.rspack](/config/build/tools.md#toolsrspack);
- Configuring builtin:swc-loader through [tools.swc](/config/build/tools.md#toolsswc).

More configurations can be referred to [Build Configurations](/config/index.md#build-configurations).

### Read Rstest config in Rsbuild plugins \{#get-rstest-config}

You can read the resolved Rstest config for the current Rsbuild environment through the API exposed by Rstest.

See [Read Rstest config in Rsbuild plugins](/config/build/plugins.md#get-rstest-config) for usage and type definitions.

### Modify Rstest config in Rsbuild plugins \{#modify-rstest-config}

You can modify the current Rstest project config in Rsbuild plugins through the API exposed by Rstest.

See [Modify Rstest config in Rsbuild plugins](/config/build/plugins.md#modify-rstest-config) for usage, type definitions, and limitations.

## 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](https://rsbuild.rs/guide/configuration/rspack).

## Configure SWC

Rstest uses Rspack's [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader) to transform JavaScript and TypeScript code by default, which is the Rust version of [swc-loader](https://github.com/swc-project/pkgs/tree/main/packages/swc-loader).

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

- [tools.swc](/config/build/tools.md#toolsswc): Used to configure the options of `builtin:swc-loader`.
- [source.include](/config/build/source.md#sourceinclude): Used to specify the files that need to be compiled by SWC.
- [source.exclude](/config/build/source.md#sourceexclude): Used to exclude files that do not need to be compiled by SWC.

```ts
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](https://rspack.rs/errors/swc-plugin-version) for handling.

## Detect Rstest environment

You can use `import.meta.env.RSTEST` or `process.env.RSTEST` to detect whether code is running under Rstest. Both values are `'true'` in every test environment, including browser mode.

Prefer `import.meta.env.RSTEST` in browser-compatible ESM source code. Browser mode replaces these expressions at build time but does not add a global `process` object, so do not guard access with `typeof process !== 'undefined'`.

```ts
if (import.meta.env.RSTEST === 'true') {
  // do something...
}
```

When building the source code for production, define the expressions you use as `false` in your build configuration (such as `rsbuild.config.ts`). This allows the bundler to eliminate the test-only branches as dead code.

```diff title=rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';

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

### Detect Rstest in Rsbuild plugins

If you are developing an Rsbuild plugin, see [Detect whether a plugin is running in Rstest](/config/build/plugins.md#detect-rstest-environment) to use `api.context.callerName` for environment-specific behavior.

## Configuration integration

In large projects, you often already have existing build/toolchain configurations (aliases, global variables, plugins, etc.). Through [adapters](/guide/advanced/adapters.md) and the [extends](/config/test/extends.md) option, Rstest can transform and integrate these external configurations into your test setup, helping you avoid duplicate maintenance and keep configurations consistent.

- With `extends`, you can load a function (adapter) or object, and the returned configuration will be deeply merged with the current Rstest configuration.
- This is suitable for reusing configurations from tools such as Rsbuild and Rspack, or presetting testing behavior for framework templates (for example, default test environments and setup scripts).