A short guide to all the exported functions in Vue Testing Library.


Difference from DOM Testing Library

The queries returned from render in Vue Testing Library are the same as DOM Testing Library. Yet, they have the first argument bound to the document, so instead of getByText(node, 'text') you write getByText('text').

Search variants

Return if no matchReturn if 1 matchReturn if 1+ matchAwait?

Search types

finds by...DOM example
...ByLabelTextlabel or aria-label content<label for="element" />
...ByPlaceholderTextinput placeholder value<input placeholder="name" />
...ByTextelement text content<p>Lorem ipsum</p>
...ByDisplayValueform element current valueCurrent value of input element
...ByAltTextimg alt attribute<img alt="movie poster" />
...ByTitletitle attribute or svg title tag<span title="Add" /> or <title />
...ByRoleARIA role<div role="dialog" />
...ByTestIddata-testid attribute<div data-testid="some-message" />

You can write any combination of Search variants and Search types.

An example

getByLabelText('Username') will search for a <label> element that contains the string "Username", and will return the associated input. In case of not finding any, or finding more than one, it will throw an error.

queryAllByRole('nav') will synchronously look for all elements with a role="nav" attribute, and return an array with the results (or an empty array if no results were found).

For more information, see Which query should I use?.

Async utilities

  • waitFor (Promise) retry function within until it stops throwing or times out.
  • waitForElement (Promise) retry function or array of functions and return the result.
  • findBy and findAllBy queries are async and retry until either a timeout or if the query returns successfully; they wrap waitForElement.

For more information, see DOM Testing Library Async API.

Remember to await or .then() the result of async functions in your tests!

Firing events

  • fireEvent() trigger DOM event: fireEvent(node, event)
  • fireEvent.* helpers for default event types

For more information, see Events API

Difference from DOM Testing Library

The events returned from Vue Testing Library are all async, so you should await or then() the result.

VTL also exposes fireEvent.update(node, value) event to deal with v-model. See the API for more details.


  • within(node) takes a node and returns an object with all the queries bound to it: within(getByTestId("global-header")).getByText("hello").
  • configure(config) change global options: configure({testIdAttribute: 'my-test-id'}).

For more information, see Querying Within Elements and Config API.

Text Match Options

Given the following HTML:

<div>Hello World</div>

All these matchers will find the element:

// Matching a string:
getByText('Hello World') // full string match
getByText('llo Worl', {exact: false}) // substring match
getByText('hello world', {exact: false}) // ignore case
// Matching a regex:
getByText(/World/) // substring match
getByText(/world/i) // substring match, ignore case
getByText(/^hello world$/i) // full string match, ignore case
getByText(/Hello W?oRlD/i) // advanced regex
// Matching with a custom function:
getByText((content, element) => content.startsWith('Hello'))
Last updated on by Nick McCurdy