api.mdx

id	title
api	API

Vue Testing Library re-exports everything from DOM Testing Library.

It also exposes these methods:

• render(Component, options)
  • Parameters
    • Component
    • Options
  • render result
    • ...queries
    • container
    • baseElement
    • debug
    • unmount
    • html
    • emitted
    • rerender
• fireEvent
  • touch(elem)
  • update(elem, value)
• cleanup

---

render(Component, options)

The render function is the only way of rendering components in Vue Testing Library.

It takes up to 2 parameters and returns an object with some helper methods.

functionrender(Component,options){return{ ...DOMTestingLibraryQueries, container, baseElement,debug(element), unmount, html, emitted,rerender(props),}}

Parameters

Component

The valid Vue Component to be tested.

Options

An object containing additional information to be passed to @vue/test-utilsmount.

Additionally, the following options can also be provided:

store (Object | Store)

The object definition of a Vuex store. If a store object is provided, Vue Testing Library will import and configure a Vuex store. If an instantiated Vuex store is passed, it will be used.

routes (Array | VueRouter)

A set of routes for Vue Router. If routes is provided, the library will import and configure Vue Router. If an instantiated Vue Router is passed, it will be used.

props (Object)

It will be merged with propsData.

container (HTMLElement)

By default, Vue Testing Library will create a div and append it to the baseElement. This is where your component will be rendered. If you provide your own HTMLElement container via this option, it will not be appended to the baseElement automatically.

For example: If you are unit testing a tablebody element, it cannot be a child of a div. In this case, you can specify a table as the render container.

consttable=document.createElement('table')const{container}=render(TableBody,{ props,container: document.body.appendChild(table),})

baseElement (HTMLElement)

If the container is specified, then this defaults to that, otherwise this defaults to document.body. baseElement is used as the base element for the queries as well as what is printed when you use debug().

render result

The render method returns an object that has a few properties:

...queries

The most important feature of render is that the queries from DOM Testing Library are automatically returned with their first argument bound to the baseElement, which defaults to document.body.

See Queries for a complete list.

const{getByLabelText, queryAllByTestId}=render(Component)

container

The containing DOM node of your rendered Vue Component. By default it's a div. This is a regular DOM node, so you can call container.querySelector etc. to inspect the children.

Tip: To get the root element of your rendered element, use container.firstChild.

🚨 If you find yourself using container to query for rendered elements then you should reconsider! The other queries are designed to be more resilient to changes that will be made to the component you're testing. Avoid using container to query for elements!

baseElement

The containing DOM node where your Vue Component is rendered in the container. If you don't specify the baseElement in the options of render, it will default to document.body.

This is useful when the component you want to test renders something outside the container div, e.g. when you want to snapshot test your portal component which renders its HTML directly in the body.

Note: the queries returned by the render looks into baseElement, so you can use queries to test your portal component without the baseElement.

debug(element)

This method is a shortcut for console.log(prettyDOM(element)).

import{render}from'@testing-library/vue'constHelloWorldComponent={template: `<h1>Hello World</h1>`,}const{debug}=render(HelloWorldComponent)debug()// <div>// <h1>Hello World</h1>// </div>

This is a simple wrapper around prettyDOM which is also exposed and comes from DOM Testing Library.

unmount()

An alias for @vue/test-utilsdestroy.

html()

An alias for @vue/test-utilshtml.

emitted()

An alias for @vue/test-utilsemitted.

rerender(props)

An alias for @vue/test-utilssetProps.

It returns a Promise through so you can await rerender(...).

---

fireEvent

Because Vue applies DOM updates asynchronously during re-renders, the fireEvent tools are re-exported as async functions. To ensure that the DOM is properly updated in response to an event in a test, it's recommended to always awaitfireEvent.

awaitfireEvent.click(getByText('Click me'))

Additionally, Vue Testing Library exposes two useful methods:

touch(elem)

It triggers both focus() and blur() events.

awaitfireEvent.touch(getByLabelText('username'))// Same as:awaitfireEvent.focus(getByLabelText('username'))awaitfireEvent.blur(getByLabelText('username'))

update(elem, value)

Properly handles inputs controlled by v-model. It updates the input/select/textarea inner value while emitting the appropriate native event.

See a working example of update in the v-model example test.

---

cleanup

Unmounts Vue trees that were mounted with render.

This is called automatically if your testing framework (such as mocha, Jest or Jasmine) injects a global afterEach() function into the testing environment. If not, you will need to call cleanup() after each test.

Failing to call cleanup when you've called render could result in a memory leak and tests which are not idempotent (which can lead to difficult to debug errors in your tests).