FAQ

See also the main FAQ for questions not specific to Vue testing.

Is Vue Testing Library a replacement for the official @vue/test-utils?

Short answer: yes, it is. If you use Vue Testing Library (VTL) there's no need to install @vue/test-utils.

Longer answer: VTL is built on top of @vue/test-utils. The official library is used to render Vue components (by calling mount) and exposes some of its methods (while hiding others). You can check the full list of available methods in the API section.

Do I need to install DOM Testing Library?

Nope! VTL imports everything it needs from DOM Testing Library, and then re-exports it.

What queries does Vue Testing Library provide?

All queries from DOM Testing Library. See Queries for full list.

If I can't use shallow rendering, how do I mock out components in tests?

In general, you should avoid mocking out components (see the Guiding Principles section).

However if you need to, you can either use Jest's mocking feature or the global.stubs key provided by @vue/test-utils.

import {render} from '@testing-library/vue'
import Component from './Component'

test('Can stub components', () => {
  render(Component, {
    global: {stubs: ['FontAwesomeIcon']},
  })
})

You can check out a working example in the GitHub repository of VTL.

How can I test if an element has appeared / has disappeared?

Check the Appearance and Disappearance section of the Guide for available methods to test appearance and disappearance.

If you want to check if an element was never rendered, you might want to write something like the following:

expect(queryByText('submit')).toBeNull()

// or, if using jest-dom:
import '@testing-library/jest-dom'
expect(queryByText('submit')).not.toBeInTheDocument()

Why does my Vue Router state seem to be shared between tests?

The history implementations most apps use, createWebHistory and createWebHashHistory, store the current URL in window.location. Test runners such as Jest and Vitest do not reset the JSDOM window between tests, so a navigation in one test leaks into the next, even when each test creates its own router.

In tests, use createMemoryHistory instead. It keeps the history stack in memory and never touches window.location, so nothing is shared between tests.

Vue Router navigates asynchronously, and a freshly created router has not navigated anywhere yet. Navigate to the route under test and wait for that navigation to finish before rendering, so the component mounts on that route:

import {render} from '@testing-library/vue'
import {createRouter, createMemoryHistory} from 'vue-router'
import Component from './Component.vue'

test('isolates router state with memory history', async () => {
  const router = createRouter({
    history: createMemoryHistory(),
    routes: [
      // Your routes here
    ],
  })

  // Awaiting push waits for the navigation to finish.
  await router.push('/')

  render(Component, {
    global: {
      plugins: [router],
    },
  })
})

To reduce boilerplate, you can create a custom render function to use throughout your test suite. For example:

// test-utils.js

import {render} from '@testing-library/vue'
import {createRouter, createMemoryHistory} from 'vue-router'

export async function renderApp(component, options = {}) {
  const router = createRouter({
    history: createMemoryHistory(),
    routes: [
      // Your routes here
    ],
  })

  await router.push('/')

  return render(component, {
    ...options,
    global: {
      ...options.global,
      plugins: [router, ...(options.global?.plugins || [])],
    },
  })
}