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

# isolate

- **Type:** `boolean`
- **Default:** `true`
- **CLI:** `--isolate`, `--isolate=false`, `--no-isolate`

Run tests in an isolated environment.

By default, Rstest runs each test in an isolated environment, which avoids the impact of some module side effects and helps improve the stability of the test.

If your code has no side effects, turning off this option will help improve performance because module caches can be reused between different test files.

:::info `vmForks` and `vmThreads` always isolate test files
This option has no effect when [`pool.type`](/config/test/pool.md#vmforks) is `vmForks` or `vmThreads`. Rstest reuses the worker but creates a fresh VM context, module graph, and test environment for every file. Setup files and worker-scoped fixtures therefore also remain file-scoped.
:::

:::warning Module top-level code runs once per worker
For `forks` and `threads`, when `isolate` is `false`, a module imported by multiple test files is evaluated **once per worker**, not once per file. Any code at that shared module's top level — including hooks registered there (e.g. a helper that calls `beforeEach` at module scope) — therefore runs only for the first file that loads it, not for every file. For setup that must run per file, use [`setupFiles`](/config/test/setup-files.md), which Rstest re-runs for each test file even without isolation. The [test environment](/config/test/test-environment.md) follows the same rule — it is created once per worker, so its state (the DOM, timers you did not clear, installed fake timers) persists across files and can be reset per file in `setupFiles`.
:::


**CLI**

```bash
npx rstest --no-isolate
```


**rstest.config.ts**

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

export default defineConfig({
  isolate: false,
});
```


## Module mocks

Because modules are shared across the files in a worker, a [module mock](/api/runtime-api/rstest/mock-modules.md) behaves differently when `isolate` is `false`:

- The mock may not apply. If an earlier file already loaded a module that imports the mocked one, that cached module keeps the real implementation.
- The mock may leak. Modules loaded while the mock is active keep the mocked implementation in later files.

Which file fails depends on the order in which files run.

For example, both test files below import `./user-service`, which calls `fetchUser()` from `./api`. The real `fetchUser()` returns `{ name: 'Bob' }`, and only `user-service.test.ts` mocks it. To keep both files correct in any order, the mocking file resets the module cache before importing the code under test, then undoes the mock after it finishes (highlighted lines):

```ts title="user-service.test.ts" {4-6,10-13}
import { afterAll, expect, rs, test } from '@rstest/core';
import { loadUserName } from './user-service';

rs.hoisted(() => {
  rs.resetModules();
});

rs.mock('./api', () => ({ fetchUser: () => ({ name: 'Alice' }) }));

afterAll(() => {
  rs.doUnmock('./api');
  rs.resetModules();
});

test('loads the mocked user name', () => {
  expect(loadUserName()).toBe('Alice');
});
```

```ts title="profile.test.ts"
import { expect, test } from '@rstest/core';
import { loadUserName } from './user-service';

test('loads the real user name', () => {
  expect(loadUserName()).toBe('Bob');
});
```

`profile.test.ts` needs no changes: whether it runs before or after `user-service.test.ts`, it gets the real `./api`.

- Call [`rs.resetModules()`](/api/runtime-api/rstest/mock-modules.md#rsresetmodules) inside [`rs.hoisted()`](/api/runtime-api/rstest/mock-modules.md#rshoisted) so the module cache is cleared before the static imports run.
- Call [`rs.doUnmock()`](/api/runtime-api/rstest/mock-modules.md#rsdounmock) in `afterAll` for every module the file mocks.
- Both `rs.resetModules()` calls clear the shared module cache, so modules are re-evaluated for this file and for the next file in the worker. Files without this pattern keep sharing modules.