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

# Rsbuild adapter reference

For setup, see the [Rsbuild integration overview](/integration/rsbuild.md). This page contains the complete adapter API, configuration mapping, and debugging workflow.

## API

### `withRsbuildConfig(options)`

Returns a configuration function that loads or accepts 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.

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

#### `configPath`

- **Type:** `string`
- **Default:** `'./rsbuild.config.ts'`

Path to rsbuild config file.

:::tip
If both `config` and `configPath` are provided, `config` takes precedence as the config content.
:::

#### `config`


[Added in v0.11.0](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.0)

- **Type:** `RsbuildConfig`
- **Default:** `undefined`

The inline Rsbuild config object to convert directly. When `config` is provided, the adapter does not call Rsbuild's `loadConfig`.

If `configPath` is also provided, the adapter uses it as config file metadata for [`forceRerunTriggers`](/config/test/force-rerun-triggers.md) and build cache dependency resolution, but the inline `config` still takes precedence as the config content.

```ts
import { defineConfig as defineRsbuildConfig } from '@rsbuild/core';
import { defineConfig } from '@rstest/core';
import { withRsbuildConfig } from '@rstest/adapter-rsbuild';

const rsbuildConfig = defineRsbuildConfig({
  source: {
    define: {
      __DEV__: 'true',
    },
  },
});

export default defineConfig({
  extends: withRsbuildConfig({
    config: rsbuildConfig,
  }),
});
```

#### `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:

```ts
// 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.

```ts
// 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.

```ts
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:

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

### `toRstestConfig(options)`

Converts an Rsbuild config object to Rstest configuration without loading a config file. Use this when your project or framework already creates an Rsbuild config object in memory.

```ts
import type { RsbuildConfig } from '@rsbuild/core';
import { defineConfig } from '@rstest/core';
import { toRstestConfig } from '@rstest/adapter-rsbuild';

const rsbuildConfig: RsbuildConfig = {
  resolve: {
    alias: {
      '@': './src',
    },
  },
};

export default defineConfig({
  extends: toRstestConfig({
    rsbuildConfig,
  }),
});
```

#### `rsbuildConfig`

- **Type:** `RsbuildConfig`

The Rsbuild config object to convert.

#### `configPath`

- **Type:** `string`
- **Default:** `undefined`

Source file path for the provided `rsbuildConfig`; it does not load config from this path. The adapter uses it only to add the file to [`forceRerunTriggers`](/config/test/force-rerun-triggers.md) and [`performance.buildCache.buildDependencies`](https://rsbuild.rs/config/performance/build-cache#builddependencies).

#### `environmentName`

- **Type:** `string`
- **Default:** `undefined`

The environment name in the `environments` field to merge with the common config.

#### `modifyRsbuildConfig`

- **Type:** `(config: RsbuildConfig) => RsbuildConfig`
- **Default:** `undefined`

Modify the merged Rsbuild config object before it gets converted to Rstest config.

## Configuration mapping

The adapter automatically maps these Rsbuild options to Rstest:

Only the fields listed below are inherited. Rsbuild options that are not listed are ignored by default, which means test-irrelevant sections such as `dev`, `server`, and `html` are automatically pruned during conversion.

| Rsbuild option           | Rstest equivalent        | Notes                                |
| ------------------------ | ------------------------ | ------------------------------------ |
| `root`                   | `root`                   | Project root directory               |
| `name` from environment  | `name`                   | Environment identifier               |
| `plugins`                | `plugins`                | Plugin configuration                 |
| `source.decorators`      | `source.decorators`      | Decorator support                    |
| `source.assetsInclude`   | `source.assetsInclude`   | Additional static asset patterns     |
| `source.define`          | `source.define`          | Global constants                     |
| `source.include`         | `source.include`         | Source inclusion patterns            |
| `source.exclude`         | `source.exclude`         | Source exclusion patterns            |
| `source.transformImport` | `source.transformImport` | On-demand import transform rules     |
| `source.tsconfigPath`    | `source.tsconfigPath`    | TypeScript config path               |
| `resolve`                | `resolve`                | Module resolution                    |
| `output.cssModules`      | `output.cssModules`      | CSS modules configuration            |
| `output.emitAssets`      | `output.emitAssets`      | Emit imported static assets to disk  |
| `output.module`          | `output.module`          | Output module type                   |
| `performance.buildCache` | `performance.buildCache` | Reused with rstest-aware defaults    |
| `tools.rspack`           | `tools.rspack`           | Rspack configuration                 |
| `tools.swc`              | `tools.swc`              | SWC configuration                    |
| `tools.bundlerChain`     | `tools.bundlerChain`     | Bundler chain configuration          |
| `output.target`          | `testEnvironment`        | 'happy-dom' for web, 'node' for node |

The adapter also removes the `rsbuild:type-check` plugin because type checking is not part of the test runtime pipeline.

## Debug config

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

```ts
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](https://rsbuild.rs/config)
- [Rstest configuration overview](/config/index.md)