{"id":12384,"library":"vitest-browser-react","title":"Vitest Browser React Renderer","description":"vitest-browser-react is a testing utility designed to render React components within Vitest's Browser Mode, providing a browser-like environment for component testing. Currently at version 2.2.0, this library receives regular updates, often aligning with Vitest's own release cycle, indicating active maintenance. Its core differentiator lies in its deep integration with Vitest Browser Mode's native locator and retry-ability APIs, offering an ergonomic testing experience without requiring explicit `act` calls for most scenarios. Unlike `@testing-library/react`, it leverages Vitest's built-in browser assertion mechanisms, simplifying asynchronous testing patterns. It also provides a `renderHook` utility for testing React hooks and can automatically inject `page.render` into the Vitest `page` object for convenience.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/vitest-community/vitest-browser-react","tags":["javascript","react","vitest","browser","testing","typescript"],"install":[{"cmd":"npm install vitest-browser-react","lang":"bash","label":"npm"},{"cmd":"yarn add vitest-browser-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add vitest-browser-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for TypeScript types for React.","package":"@types/react","optional":false},{"reason":"Required for TypeScript types for React DOM.","package":"@types/react-dom","optional":false},{"reason":"Core React library for component definition and rendering.","package":"react","optional":false},{"reason":"React DOM for browser rendering capabilities.","package":"react-dom","optional":false},{"reason":"The core testing framework, specifically requires version 4.0.0 or higher.","package":"vitest","optional":false},{"reason":"Recommended for handling React JSX and related features within a Vite-based setup.","package":"@vitejs/plugin-react","optional":true}],"imports":[{"note":"vitest-browser-react is an ESM-first library; CommonJS `require` is not supported. Use named import for the core rendering function.","wrong":"const { render } = require('vitest-browser-react')","symbol":"render","correct":"import { render } from 'vitest-browser-react'"},{"note":"Used for testing React custom hooks in isolation. It's a named export.","wrong":"import renderHook from 'vitest-browser-react'","symbol":"renderHook","correct":"import { renderHook } from 'vitest-browser-react'"},{"note":"When configured with a setup file, 'vitest-browser-react' automatically injects its `render` function as `page.render`. Access `page` from `vitest/browser`.","wrong":"import { render } from 'vitest-browser-react'; await page.render(...)","symbol":"page.render","correct":"import { page } from 'vitest/browser'; await page.render(...)"},{"note":"The `configure` function, used for global settings like `reactStrictMode`, must be imported specifically from the 'vitest-browser-react/pure' entry point.","wrong":"import { configure } from 'vitest-browser-react'","symbol":"configure","correct":"import { configure } from 'vitest-browser-react/pure'"},{"note":"Include this import in your Vitest `setupFiles` to ensure TypeScript picks up the global types for `page.render` and other extensions.","symbol":"Global Types","correct":"import 'vitest-browser-react'"}],"quickstart":{"code":"import { render } from 'vitest-browser-react';\nimport { expect, test } from 'vitest';\n\nfunction Counter({ initialCount = 0 }) {\n  const [count, setCount] = useState(initialCount);\n  return (\n    <div>\n      <p>Count is {count}</p>\n      <button onClick={() => setCount(c => c + 1)}>Increment</button>\n    </div>\n  );\n}\n\n// Simulate useState if React is not directly imported for brevity\nlet currentCount = 0;\nconst useState = (initial) => {\n  if (currentCount === 0) currentCount = initial;\n  const setter = (val) => { currentCount = typeof val === 'function' ? val(currentCount) : val; };\n  return [currentCount, setter];\n};\n\ntest('counter button increments the count', async () => {\n  currentCount = 1; // Reset for test clarity\n  const screen = await render(<Counter initialCount={1} />);\n\n  await screen.getByRole('button', { name: 'Increment' }).click();\n\n  await expect.element(screen.getByText('Count is 2')).toBeVisible();\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.0 (and usage with Vitest <4.0.0)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'render')"},{"fix":"Upgrade your `vitest` package to version 4.0.0 or newer: `npm install vitest@latest` or `yarn add vitest@latest`.","cause":"Mismatch between the installed `vitest` version and the peer dependency requirement of `vitest-browser-react`.","error":"Error: `vitest-browser-react` requires `vitest@^4.0.0`. Found `vitest@3.2.0`."},{"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`.","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.","error":"Warning: An update to X inside a test was not wrapped in act(...)"},{"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.","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`.","error":"ReferenceError: React is not defined"}],"ecosystem":"npm"}