You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/en/README.md
+79-10Lines changed: 79 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,26 @@
1
-
# Vue Test Utils
1
+
# `vue-test-utils`
2
2
3
-
Vue Test Utils is the official test library for Vue.js.
3
+
`vue-test-utils`is the official test utility library for Vue.js.
4
4
5
-
It provides methods for [unit testing](guides/introduction-to-unit-tests.md)Vue components.
5
+
It provides methods that make it easier to traverse, query and assert your Vue components' output in unit tests.
6
6
7
-
## Example
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
+
constwrapper=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:
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
+
constwrapper=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:
18
87
19
-
## Getting started
88
+
-[Testing SFCs with Jest](./guides/testing-SFCs-with-jest.md)
89
+
-[Testing SFCs with Mocha + webpack](./guides/testing-SFCs-with-mocha-webpack.md)
20
90
21
-
To get started using Vue Test Utils, please see [using with jest](guides/using-with-jest.md).
91
+
## Knowing what to test
22
92
23
-
If you're new to unit testing, you can read our [introduction to unit tests](guides/introduction-to-unit-tests.md).
93
+
It's difficult to generalize what you should test and what you shouldn't, because it's a trade-off that has to do with your development requirements and time constraints. However, there are some general rules you can follow.
24
94
25
-
## Testing single file components (SFCs)
95
+
You should write tests to assert your component's logic, not implementation details. The best way to test the logic of component is to make sure an input (user interaction or change of props) creates the expected output.
26
96
27
-
-[Testing SFCs with Jest](guides/testing-SFCs-with-jest.md)
28
-
-[Testing SFCs with Mocha](guides/testing-SFCs-with-mocha-webpack.md)
97
+
For example, imagine we have a `Counter` component that increments a display counter by 1 each time a button is clicked. The test should perform the click and assert that the counter increased by 1. This ensures that your test is not implementation specific. You can rewrite the logic of the test, and as long as clicking a button still updates the counter text, the test will pass.
Copy file name to clipboardExpand all lines: docs/en/api/options.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
-
# options
1
+
# Mounting Options
2
2
3
-
Options for mount and shallow. The options object can contain vue-test-utilsoptions and Vue options together.
3
+
Options for `mount` and `shallow`. The options object can contain both `vue-test-utils` mounting options and raw Vue options.
4
4
5
-
Vue options are passed to the component when a new instance is created. , e.g. `store`, `propsData`. For full list, see the [Vue API](https://vuejs.org/v2/api/). Also takes vue-test-utils options:
5
+
Vue options are passed to the component when a new instance is created. , e.g. `store`, `propsData`. For full list, see the [Vue API](https://vuejs.org/v2/api/).
6
6
7
-
-**Options:**
7
+
## `vue-test-utils` Specific Mounting Options
8
8
9
9
-`{Object} options`
10
10
-`{boolean} attachToDocument`
@@ -14,9 +14,9 @@ Vue options are passed to the component when a new instance is created. , e.g. `
Copy file name to clipboardExpand all lines: docs/en/common-gotchas.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,9 @@
2
2
3
3
## browser environment
4
4
5
-
Vue Test Utils must be run in a browser environment. This means you can run it in a browser (not recommended), or you can run it in node using a virtual browser, like [JSDOM](https://github.com/tmpvar/jsdom).
5
+
`vue-test-utils` must be run in a browser environment. This means you can run it in a browser (not recommended), or you can run it in node using a virtual browser, like [JSDOM](https://github.com/tmpvar/jsdom).
6
6
7
-
[Jest](https://facebook.github.io/jest/docs/en/cli.html) sets up JSDOM automatically, so it is the easiest way for you to run Vue Test Utils in node.
7
+
[Jest](https://facebook.github.io/jest/docs/en/cli.html) sets up JSDOM automatically, so it is the easiest way for you to run `vue-test-utils` in node.
Copy file name to clipboardExpand all lines: docs/en/guides/choosing-a-test-runner.md
+6-20Lines changed: 6 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,31 +2,17 @@
2
2
3
3
A test runner is a program that runs tests.
4
4
5
-
There are many popular JavaScript test runners, and Vue Test Utils works in all of them. It's test runner agnostic.
5
+
There are many popular JavaScript test runners, and `vue-test-utils`works with all of them. It's test runner agnostic.
6
6
7
-
However, some popular test runners do not have good support for compiling singlefile components (SFCs).
7
+
There are a few things to consider when choosing a test runner though: feature set, performance, and support for single-file component (SFC) pre-compilation. After carefully comparing existing libraries, here are two test runners that we recommend:
8
8
9
-
## Performance
9
+
-[Jest](https://facebook.github.io/jest/docs/en/getting-started.html#content) is the most fully featured test runner. It requires the least configuration, sets up JSDOM by default, and has a great command line user experience. However, you will need a preprocessor to be able to import SFC components in your tests. We have created the `jest-vue` preprocessor which can handle most common SFC features, but it currently does not have 100% feature parity with `vue-loader`.
10
10
11
-
The fastest test runners are:
12
-
13
-
- Jest
14
-
- Mocha Webpack
15
-
- tape
16
-
17
-
You can see a performance comparisson of popular test runners [here](https://github.com/eddyerburgh/vue-unit-test-perf-comparison).
18
-
19
-
## Features
20
-
21
-
Jest is the most fully featured test runner. It requires the leat configuration, as it sets up JSDOM by default.
22
-
23
-
tape is very minimal. If you choose tape, you will need to do a lot of set up yourself.
24
-
25
-
To run SFCs in Jest, you need to use jest-vue—a transformer for Jest. jest-vue does not support styles or custom blocks. If you need to use those features, you'll need to use webpack. Mocha works well with webpack, you can read the guide on [testing SFCs with mocha](testing-SFCs-with-mocha-webpack.md) to get started.
11
+
-[mocha-webpack](https://github.com/zinserjan/mocha-webpack) is a wrapper around webpack + Mocha, but with a more streamlined interface and watch mode. The benefits of this setup is that we can get complete SFC support via webpack + `vue-loader`, but it requires more configuration upfront.
26
12
27
13
## Getting started
28
14
29
-
You can use our guides to get started with a test runner:
15
+
You can read the following guides to get started with either test runner:
30
16
31
17
-[Testing SFCs with Jest](testing-SFCs-with-jest.md)
32
18
-[Testing SFCs with Mocha and webpack](testing-SFCs-with-mocha-webpack.md)
@@ -37,4 +23,4 @@ You can use our guides to get started with a test runner:
37
23
-[Example project with Jest](https://github.com/eddyerburgh/vue-test-utils-jest-example)
38
24
-[Example project with Mocha](https://github.com/eddyerburgh/vue-test-utils-mocha-example)
39
25
-[Example project with tape](https://github.com/eddyerburgh/vue-test-utils-tape-example)
40
-
-[Example project with AVA](https://github.com/eddyerburgh/vue-test-utils-ava-example)
26
+
-[Example project with AVA](https://github.com/eddyerburgh/vue-test-utils-ava-example)
0 commit comments