Vue Test Utils

Vue Test Utils (VTU) is the official utility library for testing Vue.js components. It provides methods to mount and interact with Vue components in an isolated manner, simplifying the testing process.

Note that this documentation refers to Vue Test Utils v2, which is designed for Vue 3. If you are using Vue 2, you should use Vue Test Utils v1.

Choose your method based on the intended test outcome:

Note: isVisible() requires attachTo: document.body to work correctly with v-show.

A Vue Test Utils plugin is a function that receives the mounted VueWrapper or DOMWrapper instance and returns an object containing the new properties or methods you wish to attach to that instance.

Common use cases include:

• Aliasing existing public methods.
• Attaching custom matchers.
• Adding helper methods (e.g., finding elements by data-testid).

import { config, DOMWrapper } from '@vue/test-utils'

// A plugin that adds a 'findByTestId' method to the wrapper
const DataTestIdPlugin = wrapper => {
  function findByTestId(selector) {
    const dataSelector = `[data-testid='${selector}']`
    const element = wrapper.element.querySelector(dataSelector)
    return new DOMWrapper(element)
  }

  return {
    findByTestId
  }
}

config.plugins.VueWrapper.install(DataTestIdPlugin)

Vue Test Utils supports scoped slots and the # shorthand. When testing scoped slots, you have two ways to access the slot's scope (the data bound to the slot):

1. Explicit Template: Use a wrapping <template #slotName="scopeVar"> tag within your slot string. This allows you to use scopeVar to access bound data.
2. Implicit params: If you provide a raw string without a wrapping <template> tag, the slot scope is automatically exposed via a special params object. You can access bound data using {{ params.propertyName }}.

// Method 1: Explicit template tag
const wrapper = mount(ComponentWithSlots, {
  slots: {
    scoped: `<template #scoped="scope">
      Hello {{ scope.msg }}
    </template>`
  }
})

// Method 2: Using the implicit 'params' object
const wrapper = mount(ComponentWithSlots, {
  slots: {
    scoped: `Hello {{ params.msg }}`
  }
})

Deciding which mounting strategy to use depends on the goal of your test:

• mount: Renders the entire component hierarchy. This is the most production-like approach and provides the highest confidence as it resembles real browser usage.
• shallow: Automatically stubs all child components. Use this for testing complex components in complete isolation.
• mount + stubs: A middle ground. If you only need to isolate one or two specific components, use mount and manually stub only those. This keeps the test more realistic than a full shallow render.

Best Practice: Focus on inputs (props, user interactions via trigger) and outputs (rendered DOM, emitted events) rather than implementation details.

By default, @vue/test-utils mocks (stubs) <transition> and <transition-group> components. This allows you to test the resulting DOM state immediately without waiting for CSS transitions to complete, making tests faster and more deterministic. You can test components containing transitions as if they were standard components, checking for the presence or absence of elements after triggers (like clicks) that toggle visibility.

import Component from './Component.vue'
import { mount } from '@vue/test-utils'

test('works with transitions', async () => {
  const wrapper = mount(Component)

  // Initial state: element does not exist
  expect(wrapper.find('p').exists()).toBe(false)

  // Trigger change
  await wrapper.find('button').trigger('click')

  // Post-transition state: element exists and contains expected text
  expect(wrapper.get('p').text()).toEqual('hello')
})

If your component's event handler relies on properties within the event object (e.g., event.relatedTarget), you can pass an object as the second argument to trigger() to mock those properties.

Example:

// Simulating a blur event where the focus moved to a specific button
const componentToGetFocus = wrapper.find('button')

await wrapper.find('input').trigger('blur', {
  relatedTarget: componentToGetFocus.element
})

import Form from './Form.vue'

test('emits an event only if you lose focus to a button', () => {
  const wrapper = mount(Form)

  const componentToGetFocus = wrapper.find('button')

  wrapper.find('input').trigger('blur', {
    relatedTarget: componentToGetFocus.element
  })

  expect(wrapper.emitted('focus-lost')).toBeTruthy()
})

Install @vue/test-utils as a development dependency using your preferred package manager.

npm install --save-dev @vue/test-utils

When useStore is used with a unique injection key (e.g., a Symbol), you must provide the store using that exact key. You can do this in two ways:

1. Using global.provide: Pass the key as a computed property name in the provide object.
2. Using global.plugins: Pass an array containing both the store and the key [store, key] to the plugins array.

// Option 1: global.provide
import { key } from './store'

const wrapper = mount(App, {
  global: {
    provide: {
      [key]: store
    }
  }
})

// Option 2: global.plugins
const wrapper = mount(App, {
  global: {
    plugins: [[store, key]]
  }
})