Registry / testing / vitest-browser-vue

vitest-browser-vue

library2.1.0jsnpmunverified

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.

testing

npm install vitest-browser-vue

github ↗package ↗

INSTALL

IMPORT

SIG · VITEST-BROWSER-VUE

vitest-browser-vue

testingjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

render

✓ import { render } from 'vitest-browser-vue'

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

This is the primary render function. It automatically cleans up the component *before* each test, allowing UI inspection during debugging. Use ESM imports.

render

✓ import { render } from 'vitest-browser-vue/pure'

Use this specific import if you want to explicitly control component cleanup, overriding the default pre-test cleanup behavior.

config

✓ import { config } from 'vitest-browser-vue'

Provides access to the global configuration object for `@vue/test-utils` (e.g., `config.global.mocks`). Also available from `vitest-browser-vue/pure`.

Demonstrates rendering a Vue component, interacting with it using Vitest locators, and asserting its state, utilizing the default `render` function.

import { render } from 'vitest-browser-vue' import { expect, test } from 'vitest' // Example Vue component (assuming it's in Component.vue) // <template><button @click="count++">Increment</button><p>Count is {{ count }}</p></template> // <script setup> import { ref } from 'vue'; const props = defineProps({ initialCount: Number }); const count = ref(props.initialCount || 0); </script> const Component = { template: '<button @click="count++">Increment</button><p>Count is {{ count }}</p>', props: ['initialCount'], setup(props) { const count = ref(props.initialCount || 0); return { count }; } } test('counter button increments the count', async () => { const screen = await render(Component, { props: { 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 to support the new syntax of Vitest v4. Ensure your Vitest configuration and test files are updated to align with Vitest v4 API changes.

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`.

affects: >=2.0.0

gotchaWhen 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.

fix

Upgrade your `vitest` dependency to version `4.0.18` or newer to prevent `data-testid` attributes from appearing in snapshots.

affects: >=2.0.2

gotchaTypeScript types for the injected `page.render` and `cleanup` methods might not be picked up automatically. This can lead to TypeScript errors or missing IntelliSense.

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.

affects: >=1.0.0

gotchaBy 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.

fix

To disable auto-cleanup and manage it manually (e.g., `screen.cleanup()`), import `render` from `vitest-browser-vue/pure`.

affects: >=1.0.0

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

vitestrequiredRequired for running tests in browser mode; integrates directly with Vitest's API.

vuerequiredCore dependency for rendering Vue 3 components.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vitest-community/vitest-browser-vue ↗

packagehttps://www.npmjs.com/package/vitest-browser-vue ↗