Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
render
✓ import { render } from 'vitest-browser-react'
✗ const { render } = require('vitest-browser-react')
vitest-browser-react is an ESM-first library; CommonJS `require` is not supported. Use named import for the core rendering function.
renderHook
✓ import { renderHook } from 'vitest-browser-react'
✗ import renderHook from 'vitest-browser-react'
Used for testing React custom hooks in isolation. It's a named export.
page.render
✓ import { page } from 'vitest/browser'; await page.render(...)
✗ import { render } from 'vitest-browser-react'; await page.render(...)
When configured with a setup file, 'vitest-browser-react' automatically injects its `render` function as `page.render`. Access `page` from `vitest/browser`.
configure
✓ import { configure } from 'vitest-browser-react/pure'
✗ import { configure } from 'vitest-browser-react'
The `configure` function, used for global settings like `reactStrictMode`, must be imported specifically from the 'vitest-browser-react/pure' entry point.
Global Types
✓ import 'vitest-browser-react'
Include this import in your Vitest `setupFiles` to ensure TypeScript picks up the global types for `page.render` and other extensions.
This example demonstrates rendering a simple React counter component, simulating a user click, and asserting the updated text content using Vitest's built-in browser locators and retry-ability.
import { render } from 'vitest-browser-react';
import { expect, test } from 'vitest';
function Counter({ initialCount = 0 }) {
const [count, setCount] = useState(initialCount);
return (
<div>
<p>Count is {count}</p>
<button onClick={() => setCount(c => c + 1)}>Increment</button>
</div>
);
}
// Simulate useState if React is not directly imported for brevity
let currentCount = 0;
const useState = (initial) => {
if (currentCount === 0) currentCount = initial;
const setter = (val) => { currentCount = typeof val === 'function' ? val(currentCount) : val; };
return [currentCount, setter];
};
test('counter button increments the count', async () => {
currentCount = 1; // Reset for test clarity
const screen = await render(<Counter initialCount={1} />);
await screen.getByRole('button', { name: 'Increment' }).click();
await expect.element(screen.getByText('Count is 2')).toBeVisible();
});
Debug
Known issues
breakingVersion 2.0.0 introduced breaking changes related to `async act v2` and support for Vitest 4 syntax. Migrating from `vitest-browser-react` v1 to v2 requires upgrading to Vitest 4.x and potentially adjusting how `act` is handled or ensuring full reliance on the library's built-in retry mechanisms.fixUpgrade your Vitest installation to `vitest@^4.0.0`. Review your tests to remove explicit `act` calls if they are now handled by the library's automatic retry mechanisms or Vitest's CDP integration. Consult the official migration guide for `async act v2` if direct `act` usage is still necessary.
affects: >=2.0.0
gotchaThe library explicitly requires `vitest` 4.0.0 or higher as a peer dependency. Using an older version of Vitest will result in installation issues or runtime errors, as `vitest-browser-react` relies on features and APIs introduced in Vitest 4.fixEnsure your project's `vitest` dependency is at least `^4.0.0`. Run `npm install vitest@latest` or `yarn add vitest@latest` to upgrade.
affects: <2.0.0 (and usage with Vitest <4.0.0)
gotchaFor proper JSX support and certain React features (like auto-importing React), it's highly recommended to use `@vitejs/plugin-react` in your `vite.config.ts`. Without it, you might encounter issues with JSX transformation or 'React is not defined' errors.fixInstall `@vitejs/plugin-react` and add it to your `vite.config.ts` plugins array: `plugins: [react()]`. Alternatively, configure JSX options manually in your Vite config.
affects: >=1.0.0
gotchaAlthough `vitest-browser-react` tries to avoid `act` warnings internally, complex asynchronous state updates or direct DOM manipulations outside of the library's `render` and `act` helpers can still trigger React's 'An update to X inside a test was not wrapped in act(...)' warnings.fixFor complex scenarios not directly covered by `render` or `renderHook`, ensure any state updates or DOM manipulations that could trigger React re-renders are wrapped in `await act(() => { /* ... */ })` if you are using `act` from `vitest/browser`. Prefer using `expect.element` with its built-in retry-ability where possible. affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'render')
The `render` function from 'vitest-browser-react' was not properly imported or the `page.render` global was not correctly set up in Vitest Browser Mode.
fixEnsure you have `import { render } from 'vitest-browser-react'` at the top of your test file or `import 'vitest-browser-react'` in your Vitest `setupFiles` if you intend to use `page.render`. Error: `vitest-browser-react` requires `vitest@^4.0.0`. Found `vitest@3.2.0`.
Mismatch between the installed `vitest` version and the peer dependency requirement of `vitest-browser-react`.
fixUpgrade your `vitest` package to version 4.0.0 or newer: `npm install vitest@latest` or `yarn add vitest@latest`.
Warning: An update to X inside a test was not wrapped in act(...)
React detected state updates or effects outside of an `act` context during testing, often due to asynchronous operations not being awaited or handled within the testing utility's lifecycle.
fixReview your test for any asynchronous operations or direct state mutations. Ensure that any interactions causing state changes are properly awaited (e.g., `await screen.getByRole('button').click()`) or, if necessary, explicitly wrapped in `act` from `vitest/browser`. ReferenceError: React is not defined
React is not implicitly available in the scope where JSX is being used, typically because `@vitejs/plugin-react` is missing or misconfigured in `vite.config.ts`.
fixAdd `@vitejs/plugin-react` to your `vite.config.ts` (`npm i -D @vitejs/plugin-react`) or ensure `import React from 'react'` is present in files containing JSX, if not using automatic JSX runtime.
Audit
Dependencies
@types/reactrequiredRequired for TypeScript types for React.
@types/react-domrequiredRequired for TypeScript types for React DOM.
reactrequiredCore React library for component definition and rendering.
react-domrequiredReact DOM for browser rendering capabilities.
vitestrequiredThe core testing framework, specifically requires version 4.0.0 or higher.
@vitejs/plugin-reactoptionalRecommended for handling React JSX and related features within a Vite-based setup.