Vitest Browser React Renderer

Common errors

• TypeError: Cannot read properties of undefined (reading 'render')

  cause 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.
  fix Ensure 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`.

  cause Mismatch between the installed `vitest` version and the peer dependency requirement of `vitest-browser-react`.
  fix Upgrade 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(...)

  cause 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.
  fix Review 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

  cause 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`.
  fix Add `@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.

Warnings

• breaking Version 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.
  Fix: Upgrade 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.
• gotcha The 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.
  Fix: Ensure your project's `vitest` dependency is at least `^4.0.0`. Run `npm install vitest@latest` or `yarn add vitest@latest` to upgrade.
• gotcha For 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.
  Fix: Install `@vitejs/plugin-react` and add it to your `vite.config.ts` plugins array: `plugins: [react()]`. Alternatively, configure JSX options manually in your Vite config.
• gotcha Although `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.
  Fix: For 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.

Install

• npm install vitest-browser-react npm
• yarn add vitest-browser-react yarn
• pnpm add vitest-browser-react pnpm

Imports

• render
  wrong:

  const { render } = require('vitest-browser-react')

  correct:

  import { render } from '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
  wrong:

  import renderHook from 'vitest-browser-react'

  correct:

  import { renderHook } from 'vitest-browser-react'

  Used for testing React custom hooks in isolation. It's a named export.
• page.render
  wrong:

  import { render } from 'vitest-browser-react'; await page.render(...)

  correct:

  import { page } from 'vitest/browser'; 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
  wrong:

  import { configure } from 'vitest-browser-react'

  correct:

  import { configure } from 'vitest-browser-react/pure'

  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.

Quickstart

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();
});