|
1 | | -# `vue-test-utils` |
2 | | - |
3 | | -`vue-test-utils` is the official test utility library for Vue.js. |
4 | | - |
5 | | -It provides methods that make it easier to traverse, query and assert your Vue components' output in unit tests. |
6 | | - |
7 | | -## Introduction |
8 | | - |
9 | | -`vue-test-utils` tests Vue components by mounting them in isolation, mocking the necessary inputs (props, injections and user events) and asserting the outputs (render result, emitted custom events). |
10 | | - |
11 | | -### Mounting Components |
12 | | - |
13 | | -The `mount` method returns a [Wrapper](./api/wrapper.md) object that contains the mounted component, and helper methods to perform assertions on the component and to traverse the render tree. |
14 | | - |
15 | | -```js |
16 | | -import { mount } from 'vue-test-utils' |
17 | | - |
18 | | -const wrapper = mount(Component) // returns a Wrapper containing a mounted Component instance |
19 | | -wrapper.text() // returns text of mounted component inside Wrapper |
20 | | -wrapper.vm // the mounted Vue instance |
21 | | -``` |
22 | | - |
23 | | -If we were testing a counter component that increments its count on a button click, the test would look like this: |
24 | | - |
25 | | -```js |
26 | | -import { mount } from 'vue-test-utils' |
27 | | -import Counter from './Counter.vue' |
28 | | - |
29 | | -const wrapper = mount(Counter) |
30 | | -wrapper.find('button').trigger('click') |
31 | | -expect(wrapper.text()).toContain('1') |
32 | | -``` |
33 | | - |
34 | | -### Stubbing Child Components with `shallow` |
35 | | - |
36 | | -For components that contain many child components, the entire rendered tree can get really big. But in unit tests, we typically want to focus on the component being tested as a unit and avoid indirectly asserting the behavior of its child components. Also, repeatedly rendering all child components could slow down our tests. To mount a component without rendering its child components, we can use the `shallow` method which stubs the child components: |
37 | | - |
38 | | -```js |
39 | | -import { shallow } from 'vue-test-utils' |
40 | | - |
41 | | -const wrapper = shallow(Component) // returns a Wrapper containing a mounted Component instance |
42 | | -wrapper.vm // the mounted Vue instance |
43 | | -``` |
44 | | - |
45 | | -### Mocking Props |
46 | | - |
47 | | -You can pass props to the component using Vue's built-in `propsData` option: |
48 | | - |
49 | | -```js |
50 | | -import { mount } from 'vue-test-utils' |
51 | | - |
52 | | -mount(Component, { |
53 | | - propsData: { |
54 | | - aProp: 'some value' |
55 | | - } |
56 | | -}) |
57 | | -``` |
58 | | - |
59 | | -*For a full list of options, please see the [mount options section](./api/options.md) of the docs.* |
60 | | - |
61 | | -### Mocking Injections |
62 | | - |
63 | | -Some Vue plugins such as Vue Router and Vuex auto-injects properties into all child components from the root instance. Since in unit tests we are mounting the component directly without a root instance, we may need to mock these injections. You can do that with the `intercept` option. |
64 | | - |
65 | | -```js |
66 | | -import { mount } from 'vue-test-utils' |
67 | | - |
68 | | -const $store = { |
69 | | - getters: {} |
70 | | -} |
71 | | -mount(Component, { |
72 | | - intercept: { |
73 | | - $store // adds the mocked $store object to the Vue instance before mounting component |
74 | | - } |
75 | | -}) |
76 | | -``` |
77 | | - |
78 | | -Note you can also directly inject real Vuex stores or router instances when mounting the component. See [Using with Vuex](./guides/using-with-vuex.md) and [Using with Vue Router](./guides/using-with-vue-router.md) for more details. |
79 | | - |
80 | | -## Testing Single-File Components |
81 | | - |
82 | | -Single-file Vue components (SFCs) require pre-compilation before they can be run in Node or in the browser. There are two recommended ways to perform the compilation: with a Jest preprocessor, or directly use webpack. |
83 | | - |
84 | | -The `jest-vue` preprocessor supports basic SFC functionalities, but currently does not handle style blocks or custom blocks, which are only supported in `vue-loader`. If you rely on these features or other webpack-specific configurations, you will need to use a webpack + `vue-loader` based setup. |
85 | | - |
86 | | -Read the following guides for different setups: |
87 | | - |
88 | | -- [Testing SFCs with Jest](./guides/testing-SFCs-with-jest.md) |
89 | | -- [Testing SFCs with Mocha + webpack](./guides/testing-SFCs-with-mocha-webpack.md) |
90 | | - |
91 | | -### Knowing What to Test |
92 | | - |
93 | | -For UI components, we don't recommend aiming for complete line-based coverage, because it leads to too much focus on the internal implementation details of the components and could result in brittle tests. |
94 | | - |
95 | | -Instead, we recommend writing tests that assert your component's public interface, and treat its internals as a black box. A single test case would assert that some input (user interaction or change of props) provided to the component results in the expected output (render result or emitted custom events). |
96 | | - |
97 | | -For example, imagine we have a `Counter` component that increments a display counter by 1 each time a button is clicked. Its test case would simulate the click and assert that the rendered output has increased by 1. The test doesn't care about how the Counter increments the value, it only cares about the input and the output. |
98 | | - |
99 | | -The benefit of this approach is that as long as your component's public interface remains the same, your tests will pass no matter how the component's internal implementation changes over time. |
100 | | - |
101 | | -This topic is discussed with more details in a [great presentation by Matt O'Connell](http://slides.com/mattoconnell/deck#/). |
| 1 | +# vue-test-utils |
| 2 | + |
| 3 | +`vue-test-utils` is the official unit testing utility library for Vue.js. |
| 4 | + |
| 5 | +* [Guides](guides/README.md) |
| 6 | + * [Getting Started](guides/getting-started.md) |
| 7 | + * [Common Tips](guides/common-tips.md) |
| 8 | + * [Choosing a test runner](guides/choosing-a-test-runner.md) |
| 9 | + * [Testing SFCs with Jest](guides/testing-SFCs-with-jest.md) |
| 10 | + * [Testing SFCs with Mocha + webpack](guides/testing-SFCs-with-mocha-webpack.md) |
| 11 | + * [Using with Vuex](guides/using-with-vuex.md) |
| 12 | +* [API](api/README.md) |
| 13 | + * [createLocalVue](api/createLocalVue.md) |
| 14 | + * [mount](api/mount.md) |
| 15 | + * [shallow](api/shallow.md) |
| 16 | + * [Mounting Options](api/options.md) |
| 17 | + * [Wrapper](api/wrapper/README.md) |
| 18 | + * [contains](api/wrapper/contains.md) |
| 19 | + * [find](api/wrapper/find.md) |
| 20 | + * [hasAttribute](api/wrapper/hasAttribute.md) |
| 21 | + * [hasClass](api/wrapper/hasClass.md) |
| 22 | + * [hasProp](api/wrapper/hasProp.md) |
| 23 | + * [hasStyle](api/wrapper/hasStyle.md) |
| 24 | + * [html](api/wrapper/html.md) |
| 25 | + * [is](api/wrapper/is.md) |
| 26 | + * [isEmpty](api/wrapper/isEmpty.md) |
| 27 | + * [isVueInstance](api/wrapper/isVueInstance.md) |
| 28 | + * [name](api/wrapper/name.md) |
| 29 | + * [update](api/wrapper/update.md) |
| 30 | + * [setData](api/wrapper/setData.md) |
| 31 | + * [setProps](api/wrapper/setProps.md) |
| 32 | + * [text](api/wrapper/text.md) |
| 33 | + * [trigger](api/wrapper/trigger.md) |
| 34 | + * [WrapperArray](api/wrapper-array/README.md) |
| 35 | + * [at](api/wrapper-array/at.md) |
| 36 | + * [contains](api/wrapper-array/contains.md) |
| 37 | + * [hasAttribute](api/wrapper-array/hasAttribute.md) |
| 38 | + * [hasClass](api/wrapper-array/hasClass.md) |
| 39 | + * [hasProp](api/wrapper-array/hasProp.md) |
| 40 | + * [hasStyle](api/wrapper-array/hasStyle.md) |
| 41 | + * [is](api/wrapper-array/is.md) |
| 42 | + * [isEmpty](api/wrapper-array/isEmpty.md) |
| 43 | + * [isVueInstance](api/wrapper-array/isVueInstance.md) |
| 44 | + * [update](api/wrapper-array/update.md) |
| 45 | + * [setData](api/wrapper-array/setData.md) |
| 46 | + * [setProps](api/wrapper-array/setProps.md) |
| 47 | + * [trigger](api/wrapper-array/trigger.md) |
| 48 | + * [Selectors](api/selectors.md) |
0 commit comments