|
1 | 1 | <div align="center"> |
2 | | -<h1>vue-testing-library</h1> |
| 2 | +<h1>Vue Testing Library</h1> |
3 | 3 |
|
4 | | -<p>Lightweight adapter allowing <a href="https://github.com/kentcdodds/dom-testing-library/">dom-testing-library</a> to be used to test <a href="https://github.com/vuejs/vue">Vue.js</a> components built on top of <a href="https://github.com/vuejs/vue-test-utils">@vue/test-utils</a></p> |
| 4 | +<p>Lightweight adapter allowing <a href="https://github.com/testing-library/dom-testing-library/">DOM Testing Library</a> to be used to test <a href="https://github.com/vuejs/vue">Vue.js</a> components. Built on top of <a href="https://github.com/vuejs/vue-test-utils">@vue/test-utils</a>.</p> |
| 5 | + |
| 6 | +<br /> |
| 7 | + |
| 8 | +[**Read The Docs**](https://testing-library.com/vue) | |
| 9 | +[Edit the docs](https://github.com/testing-library/testing-library-docs) |
| 10 | + |
| 11 | +<br /> |
5 | 12 |
|
6 | 13 | </div> |
7 | 14 |
|
8 | 15 | <hr /> |
9 | 16 |
|
10 | | -[](https://travis-ci.org/dfcook/vue-testing-library) |
11 | | -[](https://coveralls.io/github/dfcook/vue-testing-library?branch=master) |
12 | | -[](https://badge.fury.io/gh/dfcook%2Fvue-testing-library) |
| 17 | +[](https://travis-ci.org/testing-library/vue-testing-library) |
| 18 | +[](https://coveralls.io/github/testing-library/vue-testing-library?branch=master) |
| 19 | +[](https://badge.fury.io/gh/testing-library%2Fvue-testing-library) |
13 | 20 |
|
14 | 21 | [](https://badge.fury.io/js/vue-testing-library) |
15 | | -[](https://img.shields.io/github/license/dfcook/vue-testing-library) |
16 | | - |
17 | | -## This library |
| 22 | +[](https://img.shields.io/github/license/testing-library/vue-testing-library) |
18 | 23 |
|
19 | | -The `vue-testing-library` is a an adapter that enables Vue testing using the framework-agnostic DOM testing library `dom-testing-library` |
| 24 | +<h2>Table of Contents</h2> |
20 | 25 |
|
21 | | -* [Installation](#installation) |
22 | | -* [Usage](#usage) |
23 | | - * [`render`](#render) |
24 | | - * [`fireEvent`](#fireEvent) |
25 | | - * [`wait`](#wait) |
26 | | -* [Examples](#examples) |
27 | | -* [LICENSE](#license) |
| 26 | +- [Installation](#installation) |
| 27 | +- [Examples](#examples) |
| 28 | +- [Docs](#docs) |
| 29 | +- [License](#license) |
| 30 | +- [Contributors](#contributors) |
28 | 31 |
|
29 | 32 | ## Installation |
30 | 33 |
|
31 | 34 | This module is distributed via npm which is bundled with node and |
32 | 35 | should be installed as one of your project's `devDependencies`: |
33 | 36 |
|
34 | 37 | ``` |
35 | | -npm install --save-dev vue-testing-library |
36 | | -
|
37 | | -``` |
38 | | - |
39 | | -## Usage |
40 | | - |
41 | | -``` |
42 | | -npm install --save-dev vue-testing-library |
43 | | - jest |
44 | | - vue-jest |
45 | | - babel-jest |
46 | | - babel-preset-env |
47 | | - babel-plugin-transform-runtime |
| 38 | +npm install --save-dev @testing-library/vue |
48 | 39 | ``` |
49 | 40 |
|
50 | | -```javascript |
51 | | -// package.json |
52 | | - "scripts": { |
53 | | - "test": "jest" |
54 | | - } |
55 | | - |
56 | | - "jest": { |
57 | | - "moduleDirectories": [ |
58 | | - "node_modules", |
59 | | - "src" |
60 | | - ], |
61 | | - "moduleFileExtensions": [ |
62 | | - "js", |
63 | | - "vue" |
64 | | - ], |
65 | | - "testPathIgnorePatterns": [ |
66 | | - "/node_modules/" |
67 | | - ], |
68 | | - "transform": { |
69 | | - "^.+\\.js$": "<rootDir>/node_modules/babel-jest", |
70 | | - ".*\\.(vue)$": "<rootDir>/node_modules/vue-jest" |
71 | | - } |
72 | | - } |
| 41 | +You may also be interested in installing `jest-dom` so you can use |
| 42 | +[the custom Jest matchers](https://github.com/gnapse/jest-dom#readme). |
73 | 43 |
|
74 | | -// .babelrc |
75 | | -{ |
76 | | - "presets": [ |
77 | | - ["env", { |
78 | | - "modules": false, |
79 | | - "targets": { |
80 | | - "browsers": ["> 1%", "last 2 versions", "not ie <= 8"] |
81 | | - } |
82 | | - }] |
83 | | - ], |
84 | | - "plugins": [ |
85 | | - "transform-runtime" |
86 | | - ], |
87 | | - "env": { |
88 | | - "test": { |
89 | | - "presets": ["env"] |
90 | | - } |
91 | | - } |
92 | | -} |
| 44 | +## Examples |
93 | 45 |
|
94 | | -// src/TestComponent.vue |
| 46 | +```html |
| 47 | +<!-- TestComponent.vue --> |
95 | 48 | <template> |
96 | 49 | <div> |
97 | | - <span data-testid="test1">Hello World</span> |
| 50 | + <p>Times clicked: {{ count }}</p> |
| 51 | + <button @click="increment">increment</button> |
98 | 52 | </div> |
99 | 53 | </template> |
100 | 54 |
|
101 | | -// src/TestComponent.spec.js |
102 | | -import 'jest-dom/extend-expect' |
103 | | -import { render } from 'vue-testing-library' |
104 | | -import TestComponent from './TestComponent' |
105 | | - |
106 | | -test('should render HelloWorld', () => { |
107 | | - const { queryByTestId } = render(TestComponent) |
108 | | - expect(queryByTestId('test1')).toHaveTextContent('Hello World') |
109 | | -}) |
110 | | - |
| 55 | +<script> |
| 56 | +export default { |
| 57 | + data: () => ({ |
| 58 | + count: 0 |
| 59 | + }), |
| 60 | + methods: { |
| 61 | + increment () { |
| 62 | + this.count++ |
| 63 | + } |
| 64 | + } |
| 65 | +} |
| 66 | +</script> |
111 | 67 | ``` |
112 | 68 |
|
113 | | -### render |
114 | | - |
115 | | -The `render` function takes up to 3 parameters and returns an object with some helper methods |
| 69 | +```js |
| 70 | +// TestComponent.spec.js |
| 71 | +import { render, fireEvent, cleanup } from '@testing-library/vue' |
| 72 | +import TestComponent from './TestComponent.vue' |
116 | 73 |
|
117 | | -1. Component - the Vue component to be tested. |
118 | | -2. RenderOptions - an object containing additional information to be passed to @vue/test-utils mount. This can be: |
119 | | -* store - The object definition of a Vuex store, if present `render` will configure a Vuex store and pass to mount. |
120 | | -* routes - A set of routes, if present render will configure VueRouter and pass to mount. |
121 | | -All additional render options are passed to the vue-test-utils mount function in its options. |
122 | | -3. configurationCb - A callback to be called passing the Vue instance when created. This allows 3rd party plugins to be installed prior to mount. |
| 74 | +// automatically unmount and cleanup DOM after the test is finished. |
| 75 | +afterEach(cleanup) |
123 | 76 |
|
124 | | -### fireEvent |
| 77 | +it('increments value on click', async () => { |
| 78 | + // The render method returns a collection of utilities to query your component. |
| 79 | + const { getByText } = render(TestComponent) |
125 | 80 |
|
126 | | -Lightweight wrapper around DOM element events and methods. Will call wait, so can be awaited to allow effects to propagate. |
| 81 | + // getByText returns the first matching node for the provided text, and |
| 82 | + // throws an error if no elements match or if more than one match is found. |
| 83 | + getByText('Times clicked: 0') |
127 | 84 |
|
128 | | -### wait |
| 85 | + const button = getByText('increment') |
129 | 86 |
|
130 | | -When in need to wait for non-deterministic periods of time you can use `wait`, |
131 | | -to wait for your expectations to pass. The `wait` function is a small wrapper |
132 | | -around the |
133 | | -[`wait-for-expect`](https://github.com/TheBrainFamily/wait-for-expect) module. |
| 87 | + // Dispatch a native click event to our button element. |
| 88 | + await fireEvent.click(button) |
| 89 | + await fireEvent.click(button) |
134 | 90 |
|
135 | | -Waiting can be very important in Vue components, @vue/test-utils has succeeded in making the majority of updates happen |
136 | | -synchronously however there are occasions when wait will allow the DOM to update. For example, see [`here`](https://github.com/dfcook/vue-testing-library/tree/master/tests/__tests__/validate-plugin.js) |
137 | | - |
138 | | -## Examples |
| 91 | + getByText('Times clicked: 2') |
| 92 | +}) |
| 93 | +``` |
139 | 94 |
|
140 | 95 | You'll find examples of testing with different libraries in |
141 | | -[the test directory](https://github.com/dfcook/vue-testing-library/tree/master/tests/__tests__). |
| 96 | +[the test directory](https://github.com/testing-library/vue-testing-library/tree/master/tests/__tests__). |
| 97 | + |
142 | 98 | Some included are: |
143 | 99 |
|
144 | | -* [`vuex`](https://github.com/dfcook/vue-testing-library/tree/master/tests/__tests__/vuex.js) |
145 | | -* [`vue-router`](https://github.com/dfcook/vue-testing-library/tree/master/tests/__tests__/vue-router.js) |
146 | | -* [`vee-validate`](https://github.com/dfcook/vue-testing-library/tree/master/tests/__tests__/validate-plugin.js) |
| 100 | +* [`vuex`](https://github.com/testing-library/vue-testing-library/tree/master/tests/__tests__/vuex.js) |
| 101 | +* [`vue-router`](https://github.com/testing-library/vue-testing-library/tree/master/tests/__tests__/vue-router.js) |
| 102 | +* [`vee-validate`](https://github.com/testing-library/vue-testing-library/tree/master/tests/__tests__/validate-plugin.js) |
| 103 | + |
| 104 | +Feel free to contribute with more! |
| 105 | + |
| 106 | +## Docs |
147 | 107 |
|
148 | | -Feel free to contribute more! |
| 108 | +[**Read The Docs**](https://testing-library.com/vue) | |
| 109 | +[Edit the docs](https://github.com/testing-library/testing-library-docs) |
149 | 110 |
|
150 | | -## LICENSE |
| 111 | +## License |
151 | 112 |
|
152 | 113 | MIT |
153 | 114 |
|
154 | | -## CONTRIBUTORS |
| 115 | +## Contributors |
155 | 116 |
|
156 | 117 | [](https://github.com/dfcook) |
| 118 | +[](https://github.com/afontcu) |
157 | 119 | [](https://github.com/eunjae-lee) |
158 | 120 | [](https://github.com/tim-maguire) |
159 | 121 | [](https://github.com/samdelacruz) |
160 | 122 | [](https://github.com/ankitsinghaniyaz) |
161 | 123 | [](https://github.com/lindgr3n) |
162 | | -[](https://github.com/kentcdodds) |
| 124 | +[](https://github.com/kentcdodds) |
0 commit comments