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

# Rstest

[Rstest](https://rstest.rs) is a testing framework developed by the Rspack team and built on top of Rspack for fast test execution.

This guide explains how to integrate Rstest with Modern.js for web app testing.

## Quick Start

Install the base dependencies first:


```sh [npm]
npm add @rstest/core @modern-js/adapter-rstest -D
```

```sh [yarn]
yarn add @rstest/core @modern-js/adapter-rstest -D
```

```sh [pnpm]
pnpm add @rstest/core @modern-js/adapter-rstest -D
```

```sh [bun]
bun add @rstest/core @modern-js/adapter-rstest -D
```

```sh [deno]
deno add npm:@rstest/core npm:@modern-js/adapter-rstest -D
```

Then create `rstest.config.ts`:

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';
import { withModernConfig } from '@modern-js/adapter-rstest';

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

`@modern-js/adapter-rstest` lets Rstest inherit your existing Modern.js config so your test setup stays aligned with your app.

For more configuration details, refer to the [Rstest configuration documentation](https://rstest.rs/config).

You can run tests with `npx rstest`, or add a script in `package.json`:

```json title="package.json"
{
  "scripts": {
    "test": "rstest"
  }
}
```

## Testing Web UI

For web UI tests in Modern.js, there are two common approaches:

- Use Rstest browser mode, which runs tests in a real browser. This is the recommended option in most cases, although it is currently experimental.
- Use a simulated DOM environment with `happy-dom` and Testing Library. This matches the default web test environment provided by `@modern-js/adapter-rstest`.

We generally recommend browser mode because it uses real browser APIs and behavior, supports cases that simulated DOM environments cannot fully cover, and offers a better debugging experience when UI behavior does not match expectations.

### Browser mode (experimental)

If you want to test in a real browser instead of a simulated DOM, install the browser mode dependencies:


```sh [npm]
npm add @rstest/browser @rstest/browser-react playwright -D
```

```sh [yarn]
yarn add @rstest/browser @rstest/browser-react playwright -D
```

```sh [pnpm]
pnpm add @rstest/browser @rstest/browser-react playwright -D
```

```sh [bun]
bun add @rstest/browser @rstest/browser-react playwright -D
```

```sh [deno]
deno add npm:@rstest/browser npm:@rstest/browser-react npm:playwright -D
```

Then enable browser mode in `rstest.config.ts`:

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';
import { withModernConfig } from '@modern-js/adapter-rstest';

export default defineConfig({
  extends: withModernConfig(),
  browser: {
    enabled: true,
    provider: 'playwright',
  },
});
```

Example test:

```tsx title="__tests__/page.browser.test.tsx"
import { BrowserRouter as Router } from '@modern-js/runtime/router';
import { page } from '@rstest/browser';
import { render } from '@rstest/browser-react';
import { expect, test } from '@rstest/core';
import Page from '../routes/page';

test('Page', async () => {
  await render(
    <Router>
      <Page />
    </Router>,
  );

  await expect.element(
    page.getByRole('heading', { level: 1, name: 'Home' }),
  ).toBeVisible();
});
```

For more browser mode setup, Locator APIs, and assertions, refer to the [Rstest documentation](https://rstest.rs/guide/browser-testing/).

### DOM simulation with `happy-dom`

Install the DOM testing dependencies:


```sh [npm]
npm add happy-dom @testing-library/react @testing-library/dom -D
```

```sh [yarn]
yarn add happy-dom @testing-library/react @testing-library/dom -D
```

```sh [pnpm]
pnpm add happy-dom @testing-library/react @testing-library/dom -D
```

```sh [bun]
bun add happy-dom @testing-library/react @testing-library/dom -D
```

```sh [deno]
deno add npm:happy-dom npm:@testing-library/react npm:@testing-library/dom -D
```

Update `rstest.config.ts` to use `happy-dom`:

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';
import { withModernConfig } from '@modern-js/adapter-rstest';

export default defineConfig({
  extends: withModernConfig(),
  testEnvironment: 'happy-dom',
});
```

First, create a simple page for testing:

```tsx title="routes/page.tsx"
import { Link } from '@modern-js/runtime/router';

const Page = () => (
  <div>
    <h1>Home</h1>
    <Link to="/about">About</Link>
  </div>
);

export default Page;
```

Then add a test case:

```tsx title="__tests__/page.test.tsx"
import { BrowserRouter as Router } from '@modern-js/runtime/router';
import { expect, test } from '@rstest/core';
import { render, screen } from '@testing-library/react';
import Page from '../routes/page';

test('Page', () => {
  render(
    <Router>
      <Page />
    </Router>,
  );

  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
});
```

## Running Test Cases

Execute the `test` command above to run your tests:

```bash
✓ __tests__/page.test.tsx (1)
  ✓ Page

 Test Files 1 passed
      Tests 1 passed
   Duration 510ms (build 145ms, tests 365ms)
```

## Node Mode

If you need node mode tests for server-side logic such as `bff`, refer to the [Rstest documentation](https://rstest.rs) directly.

Modern.js mainly targets web apps, so this guide focuses on web UI testing and browser mode.

## Migrating from Existing Projects

If your project already uses Jest or Vitest, refer to the official Rstest migration guides:

- [Migrate from Jest to Rstest](https://rstest.rs/guide/migration/jest)
- [Migrate from Vitest to Rstest](https://rstest.rs/guide/migration/vitest)

We recommend installing the `migrate-to-rstest` skill first, then copying this prompt to your coding agent. It keeps the Modern.js `@modern-js/adapter-rstest` integration during migration:


For your Agent

Migrate to Rstest

Copy this prompt and send it to your coding agent.

Copy Prompt

Migrate this Modern.js project from Jest or Vitest to Rstest.

First install and use the migrate-to-rstest skill. If it is not installed, install it with:
npx skills add rstackjs/agent-skills --skill migrate-to-rstest

Follow the migrate-to-rstest skill instructions and the official Rstest migration guides:
- Jest: https://rstest.rs/guide/migration/jest
- Vitest: https://rstest.rs/guide/migration/vitest

Modern.js-specific requirement:
- Install and use @modern-js/adapter-rstest together with @rstest/core.
- Create or update rstest.config.ts to import withModernConfig from @modern-js/adapter-rstest.
- Reuse the Modern.js app configuration with extends: withModernConfig().
- Do not replace this with a plain Rstest config unless the project explicitly does not need Modern.js config integration.