@vue/test-utils

What is @vue/test-utils?

@vue/test-utils is the official unit testing utility library for Vue.js. It provides methods to mount and interact with Vue components in an isolated manner, allowing developers to write unit tests for their Vue components effectively.

What are @vue/test-utils's main functionalities?

Mounting Components

Mounting components allows you to render a Vue component in a test environment and returns a wrapper that contains the mounted component and methods to interact with it.

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

const wrapper = mount(MyComponent);

Finding Elements

Finding elements within the mounted component using CSS selectors, Vue component options, or ref attributes, which can then be used to test the component's behavior.

const button = wrapper.find('button');

Simulating User Interaction

Simulating user interactions such as clicks, typing, or other events on the mounted component to test how it responds to user input.

button.trigger('click');

Accessing Component Data and Methods

Accessing the Vue instance's data, computed properties, and methods to assert their values and behavior within the test.

const vm = wrapper.vm;
console.log(vm.someData);

Stubbing Child Components

Stubbing child components to prevent their actual implementation from being rendered, which can simplify tests and improve test performance.

const wrapper = mount(MyComponent, {
  stubs: {
    ChildComponent: true
  }
});

Other packages similar to @vue/test-utils

enzyme

Enzyme is a JavaScript testing utility for React that is similar to @vue/test-utils but for React components. It allows for shallow rendering, full DOM rendering, and static rendering. Enzyme provides a more granular approach to testing React components compared to @vue/test-utils.

react-testing-library

React Testing Library is another testing library for React that focuses on testing components in a way that resembles how users would interact with them, rather than testing implementation details. It is similar to @vue/test-utils in philosophy but tailored for React.

angular-testing-library

Angular Testing Library is a set of helpers for testing Angular components with a focus on the user experience. Like @vue/test-utils, it provides utilities for interacting with components, but it is designed specifically for the Angular framework.

README

vue-test-utils-next

The next iteration of Vue Test Utils. It targets Vue 3.

Installation and Usage

• yarn: yarn add @vue/test-utils@next --dev
• npm: npm install @vue/test-utils@next --save-dev

Coming from Vue 2 + Vue Test Utils beta?

We are working on some documentation to help people migrate. At this point it will you will have better luck trying this out with a brand new Vue 3 app, as opposed to upgrading an existing Vue 2 app. Feedback and bug reports are welcome!

Working with .vue files

There is vue-jest for loading .vue files into Jest. The next branch contains support for Vue 3. Install it with yarn add vue-jest@next. It lacks support for some things, namely JSX.

If you don't want to configure things, you can download a repository with Vue 3, @vue/test-utils@next, vue-jest@next and TypeScript configured here.

Docs

Docs are located in this repo. Read them here. They are in a separate repository because running Vuepress alongside a repo with Vue 3 causes conflicts - Vuepress expects to be running against Vue 2. This seems like the most simple solution for now.

Development

It's a pretty small codebase at the moment. Get started by running yarn install. You can run the tests with yarn test. That's it!

There is a lot of work to do. See issues for some basic TODOs, or the table at the bottom of this page.

What works?

See the docs. Most basic DOM interactions work. Advanced features like shallowMount and stubs are a work in progress.

Contributing

This is still very much alpha - if you want to add a feature, have a hack or ping someone in Discord to chat, or check out the issues and project board.

Comparsion with Vue Test Utils beta (targeting Vue 2)

This is table for those coming from VTU beta, comparing the two APIs. A lot of things are still a work in progress.

• ✅ - implemented

• ❌ - not yet implemented

• ⚰️ - will not be implemented (if you have a compelling use case, please open an issue)

• Q: Where is shallowMount?

• A: Coming soon. There is an issue and a PR open.

Mounting Options

option	status	notes
data	✅
slots	✅	has not been tested vigorously. Please try it out.
mocks	✅	nested in global
propsData	✅	now called props
provide	✅	nested in global
mixins	✅	(new!) nested in global
plugins	✅	(new!) nested in global
component	✅	(new!) nested in global
directives	✅	(new!) nested in global
stubs	❌
attachToDocument	❌	will rename to attachTo. See here
attrs	❌
scopedSlots	⚰️	scopedSlots are merged with slots in Vue 3
context	⚰️	different from Vue 2, may not make sense anymore.
localVue	⚰️	may not make sense anymore since we do not mutate the global Vue instance in Vue 3.
listeners	⚰️	no longer exists in Vue 3
parentComponent	⚰️

Wrapper API (mount)

method	status	notes
attributes	✅
classes	✅
exists	✅
find	✅	only querySelector syntax is supported. find(Comp) under discussion here
emitted	✅
findAll	✅	see above. .vm is different to Vue 2. We are exploring options.
html	✅
setValue	✅	works for select, checkbox, radio button, input, textarea. Returns nextTick.
text	✅
trigger	✅	returns nextTick. You can do await wrapper.find('button').trigger('click')
setProps	✅
setData	❌	has PR
destroy	❌
get	❌
isVisible	❌	use matchers such as this
props	❌
contains	⚰️	use find
emittedByOrder	⚰️	use emitted
setSelected	⚰️	now part of setValue
setChecked	⚰️	now part of setValue
is	⚰️
isEmpty	⚰️	use matchers such as this
isVueInstance	⚰️
name	⚰️
setMethods	⚰️