{"id":12385,"library":"vitest-browser-vue","title":"Vitest Browser Vue Component Testing","description":"vitest-browser-vue is a library designed for rendering Vue 3 components within Vitest's browser testing environment, adhering to the principles of `@testing-library`. It facilitates writing integration tests by exposing Vitest `locators` and utilities that mimic how users interact with components in a real browser. The current stable version is 2.1.0, with releases occurring regularly, indicating active development and maintenance. A key differentiator from `@testing-library/vue` is its cleanup strategy: it cleans up the component *before* a test starts, rather than after, allowing developers to inspect the rendered UI during debugging. It integrates seamlessly with Vitest's `page.render` and `cleanup` methods and leverages `@vue/test-utils` under the hood for component mounting and interaction. Users must ensure compatibility with `vitest` version `4.0.0` or higher and `vue` version `3.0.0` or higher.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/vitest-community/vitest-browser-vue","tags":["javascript","vue","vitest","browser","testing","typescript"],"install":[{"cmd":"npm install vitest-browser-vue","lang":"bash","label":"npm"},{"cmd":"yarn add vitest-browser-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add vitest-browser-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for running tests in browser mode; integrates directly with Vitest's API.","package":"vitest","optional":false},{"reason":"Core dependency for rendering Vue 3 components.","package":"vue","optional":false}],"imports":[{"note":"This is the primary render function. It automatically cleans up the component *before* each test, allowing UI inspection during debugging. Use ESM imports.","wrong":"const { render } = require('vitest-browser-vue')","symbol":"render","correct":"import { render } from 'vitest-browser-vue'"},{"note":"Use this specific import if you want to explicitly control component cleanup, overriding the default pre-test cleanup behavior.","symbol":"render","correct":"import { render } from 'vitest-browser-vue/pure'"},{"note":"Provides access to the global configuration object for `@vue/test-utils` (e.g., `config.global.mocks`). Also available from `vitest-browser-vue/pure`.","symbol":"config","correct":"import { config } from 'vitest-browser-vue'"}],"quickstart":{"code":"import { render } from 'vitest-browser-vue'\nimport { expect, test } from 'vitest'\n\n// Example Vue component (assuming it's in Component.vue)\n// <template><button @click=\"count++\">Increment</button><p>Count is {{ count }}</p></template>\n// <script setup> import { ref } from 'vue'; const props = defineProps({ initialCount: Number }); const count = ref(props.initialCount || 0); </script>\n\nconst Component = {\n  template: '<button @click=\"count++\">Increment</button><p>Count is {{ count }}</p>',\n  props: ['initialCount'],\n  setup(props) {\n    const count = ref(props.initialCount || 0);\n    return { count };\n  }\n}\n\ntest('counter button increments the count', async () => {\n  const screen = await render(Component, {\n    props: {\n      initialCount: 1\n    }\n  })\n\n  await screen.getByRole('button', { name: 'Increment' }).click()\n\n  await expect.element(screen.getByText('Count is 2')).toBeVisible()\n})\n","lang":"typescript","description":"Demonstrates rendering a Vue component, interacting with it using Vitest locators, and asserting its state, utilizing the default `render` function."},"warnings":[{"fix":"Review Vitest v4 migration guide and update test files and configurations to match the new syntax requirements. Specifically, ensure Vitest is at least `^4.0.0-0`.","message":"Version 2.0.0 introduced breaking changes to support the new syntax of Vitest v4. Ensure your Vitest configuration and test files are updated to align with Vitest v4 API changes.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your `vitest` dependency to version `4.0.18` or newer to prevent `data-testid` attributes from appearing in snapshots.","message":"When using snapshots with a container, a `data-testid` attribute is injected into the DOM. This can cause unexpected differences in snapshots unless Vitest is updated to version 4.0.18 or higher, which handles this injection gracefully.","severity":"gotcha","affected_versions":">=2.0.2"},{"fix":"Add `vitest-browser-vue` to your `compilerOptions.types` array in `tsconfig.json`, or explicitly include `'vitest-browser-vue'` in your `vitest.config.ts`'s `setupFiles` array to ensure type definitions are loaded.","message":"TypeScript types for the injected `page.render` and `cleanup` methods might not be picked up automatically. This can lead to TypeScript errors or missing IntelliSense.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To disable auto-cleanup and manage it manually (e.g., `screen.cleanup()`), import `render` from `vitest-browser-vue/pure`.","message":"By default, `render` from `vitest-browser-vue` cleans up the component *before* each test, which differs from `@testing-library/vue`'s post-test cleanup. This behavior allows for UI inspection. If you require standard post-test cleanup or explicit control, you need to use a different import.","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":[],"ecosystem":"npm"}