Vitest Browser Vue Component Testing

Warnings

• breaking 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.
  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`.
• gotcha 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.
  Fix: Upgrade your `vitest` dependency to version `4.0.18` or newer to prevent `data-testid` attributes from appearing in snapshots.
• gotcha 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.
  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.
• gotcha 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.
  Fix: To disable auto-cleanup and manage it manually (e.g., `screen.cleanup()`), import `render` from `vitest-browser-vue/pure`.

Install

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

Imports

• render
  wrong:

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

  correct:

  import { render } from '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`.

Quickstart

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