diff --git a/docs/zh/README.md b/docs/zh/README.md index c32b2bf4a..5982924b9 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -2,6 +2,8 @@ Vue Test Utils 是 Vue.js 官方的单元测试实用工具库。 +
在 Vue School 学习如何测试 Vue.js 组件
+ - [教程](guides/) - [起步](guides/getting-started.md) - [常用技巧](guides/common-tips.md) @@ -10,10 +12,12 @@ Vue Test Utils 是 Vue.js 官方的单元测试实用工具库。 - [用 Jest 测试单文件组件](guides/testing-single-file-components-with-jest.md) - [用 Mocha 和 webpack 测试单文件组件](guides/testing-single-file-components-with-mocha-webpack.md) - [用 Karma 测试单文件组件](guides/testing-single-file-components-with-karma.md) + - [无需构建在 Node.js 中测试](guides/usage-without-a-build-step-node.md) - [测试异步行为](guides/testing-async-components.md) - [配合 TypeScript 使用](guides/using-with-typescript.md) - [配合 Vue Router 使用](guides/using-with-vue-router.md) - [配合 Vuex 使用](guides/using-with-vuex.md) + - [有用的测试库](guides/useful-libraries-for-testing.md) - [API](api/) - [mount](api/mount.md) - [shallowMount](api/shallowMount.md) @@ -43,6 +47,7 @@ Vue Test Utils 是 Vue.js 官方的单元测试实用工具库。 - [destroy](api/wrapper/destroy.md) - [find](api/wrapper/find.md) - [findAll](api/wrapper/findAll.md) + - [get](api/wrapper/get.md) - [html](api/wrapper/html.md) - [is](api/wrapper/is.md) - [isEmpty](api/wrapper/isEmpty.md) diff --git a/docs/zh/api/README.md b/docs/zh/api/README.md index bf3b5fdf0..79d066939 100644 --- a/docs/zh/api/README.md +++ b/docs/zh/api/README.md @@ -8,3 +8,4 @@ !!!include(docs/zh/api/createLocalVue.md)!!! !!!include(docs/zh/api/createWrapper.md)!!! !!!include(docs/zh/api/config.md)!!! +!!!include(docs/zh/api/enableAutoDestroy.md)!!! diff --git a/docs/zh/api/config.md b/docs/zh/api/config.md index 4de174855..71a17a334 100644 --- a/docs/zh/api/config.md +++ b/docs/zh/api/config.md @@ -4,6 +4,21 @@ Vue Test Utils 包含了一个定义其选项的配置对象。 ### Vue Test Utils 配置选项 +### `showDeprecationWarnings` + +- 类型：`Boolean` +- 默认值：`true` + +控制是否展示废弃警告。当设置为 `true` 时，所有的废弃警告都将会在控制台中打印出来。 + +示例： + +```js +import { config } from '@vue/test-utils' + +config.showDeprecationWarnings = false +``` + ### `stubs` - 类型：`{ [name: string]: Component | boolean | string }` @@ -46,7 +61,7 @@ config.mocks['$store'] = { - 类型：`{ [name: string]: Function }` - 默认值：`{}` -你可以使用 `config` 对象配置默认的方法。它可以用于为组件注入方法的插件，例如 [VeeValidate](https://vee-validate.logaretm.com/)。你可以通过在挂载选项中传入 `methods` 来覆写 `config` 中的方法集合。 +你可以使用 `config` 对象配置默认的方法。它可以用于为组件注入方法的插件，例如 [VeeValidate](https://logaretm.github.io/vee-validate/)。你可以通过在挂载选项中传入 `methods` 来覆写 `config` 中的方法集合。 示例： diff --git a/docs/zh/api/createLocalVue.md b/docs/zh/api/createLocalVue.md index e44dbedc6..cf0128dbe 100644 --- a/docs/zh/api/createLocalVue.md +++ b/docs/zh/api/createLocalVue.md @@ -12,9 +12,11 @@ ```js import { createLocalVue, shallowMount } from '@vue/test-utils' +import MyPlugin from 'my-plugin' import Foo from './Foo.vue' const localVue = createLocalVue() +localVue.use(MyPlugin) const wrapper = shallowMount(Foo, { localVue, mocks: { foo: true } diff --git a/docs/zh/api/enableAutoDestroy.md b/docs/zh/api/enableAutoDestroy.md new file mode 100644 index 000000000..0c9084e98 --- /dev/null +++ b/docs/zh/api/enableAutoDestroy.md @@ -0,0 +1,25 @@ +## enableAutoDestroy(hook) + +- **参数：** + + - `{Function} hook` + +- **用法：** + +`enableAutoDestroy` 将会使用被传入的该钩子函数 (例如 [`afterEach`](https://jestjs.io/docs/en/api#aftereachfn-timeout)) 销毁所有被创建的 `Wrapper` 实例。在调用这个方法之后，你可以通过调用 `resetAutoDestroyState` 方法恢复到默认行为。 + +```js +import { enableAutoDestroy, mount } from '@vue/test-utils' +import Foo from './Foo.vue' + +// 将会在每个测试之后运行 `wrapper.destroy()` +enableAutoDestroy(afterEach) + +describe('Foo', () => { + it('renders a div', () => { + const wrapper = mount(Foo) + expect(wrapper.contains('div')).toBe(true) + // 不需要在此运行 `wrapper.destroy()` + }) +}) +``` diff --git a/docs/zh/api/mount.md b/docs/zh/api/mount.md index c00a5b0e2..20a06177d 100644 --- a/docs/zh/api/mount.md +++ b/docs/zh/api/mount.md @@ -55,10 +55,13 @@ import Foo from './Foo.vue' describe('Foo', () => { it('renders a div', () => { + const div = document.createElement('div') + document.body.appendChild(div) const wrapper = mount(Foo, { - attachToDocument: true + attachTo: true }) expect(wrapper.contains('div')).toBe(true) + wrapper.destroy() }) }) ``` @@ -116,9 +119,9 @@ describe('Foo', () => { it('renders a div', () => { const wrapper = mount(Foo, { stubs: { - Bar: '
', BarFoo: true, - FooBar: Faz + FooBar: Faz, + Bar: { template: '
' } } }) expect(wrapper.contains('.stubbed')).toBe(true) @@ -127,4 +130,8 @@ describe('Foo', () => { }) ``` +**废弃通知：** + +当对组件存根时，提供一个字符串的方式 (`ComponentToStub: '
`) 已经不再被支持。 + - **延伸阅读：**[`Wrapper`](wrapper/) diff --git a/docs/zh/api/options.md b/docs/zh/api/options.md index dfca20fb9..8da59b785 100644 --- a/docs/zh/api/options.md +++ b/docs/zh/api/options.md @@ -10,11 +10,13 @@ ::: - [`context`](#context) +- [`data`](#data) - [`slots`](#slots) - [`scopedSlots`](#scopedslots) - [`stubs`](#stubs) - [`mocks`](#mocks) - [`localVue`](#localvue) +- [`attachTo`](#attachto) - [`attachToDocument`](#attachtodocument) - [`propsData`](#propsdata) - [`attrs`](#attrs) @@ -44,6 +46,43 @@ const wrapper = mount(Component, { expect(wrapper.is(Component)).toBe(true) ``` +## data + +- 类型：`Function` + +向一个组件传入数据。这将会合并到现有的 `data` 函数中。 + +示例： + +```js +const Component = { + template: ` +
+ {{ foo }} + {{ bar }} +
+ `, + + data() { + return { + foo: 'foo', + bar: 'bar' + } + } +} + +const wrapper = mount(Component, { + data() { + return { + bar: 'my-override' + } + } +}) + +wrapper.find('#foo').text() // 'foo' +wrapper.find('#bar').text() // 'my-override' +``` + ## slots - 类型：`{ [name: string]: Array|Component|string }` @@ -54,12 +93,25 @@ expect(wrapper.is(Component)).toBe(true) ```js import Foo from './Foo.vue' +import MyComponent from './MyComponent.vue' const bazComponent = { name: 'baz-component', template: '

baz

' } +const yourComponent = { + props: { + foo: { + type: String, + required: true + } + }, + render(h) { + return h('p', this.foo) + } +} + const wrapper = shallowMount(Component, { slots: { default: [Foo, '', 'text'], @@ -67,7 +119,17 @@ const wrapper = shallowMount(Component, { foo: '
', bar: 'bar', baz: bazComponent, - qux: '' + qux: '', + quux: '' + }, + stubs: { + // 用来注册自定义组件 + 'my-component': MyComponent, + 'your-component': yourComponent + }, + mocks: { + // 用来向渲染上下文添加 property + yourProperty: 'ipsum' } }) @@ -124,12 +186,37 @@ shallowMount(Component, { }) ``` +::: warning 必备根元素 +由于该特性内部实现的原因，这里的插槽内容必须返回一个根元素，即使一个作用域插槽是允许返回一个元素数组的。 + +如果你在测试中有这方面的需要，推荐的变通方式是把被测试的组件包裹在另一个组件里，然后挂载那个组件： +::: + +```javascript +const WrapperComp = { + template: ` + +

Using the {{props.a}}

+

Using the {{props.a}}

+ + `, + components: { + ComponentUnderTest + } +} +const wrapper = mount(WrapperComp).find(ComponentUnderTest) +``` + ## stubs -- 类型：`{ [name: string]: Component | boolean } | Array` +- 类型：`{ [name: string]: Component | string | boolean } | Array` 将子组件存根。可以是一个要存根的组件名的数组或对象。如果 `stubs` 是一个数组，则每个存根都是一个 `<${component name}-stub>`。 +**废弃通知：** + +当对组件存根时，提供一个字符串的方式 (`ComponentToStub: '
`) 已经不再被支持。 + 示例： ```js @@ -169,6 +256,10 @@ const wrapper = shallowMount(Component, { expect(wrapper.vm.$route.path).toBe($route.path) ``` +::: tip +如果想要伪造 `$root` 请换用[这里](https://github.com/vuejs/vue-test-utils/issues/481#issuecomment-423716430)描述的 `parentComponent` 选项。 +::: + ## localVue - 类型：`Vue` @@ -198,12 +289,42 @@ const wrapper = mount(Component, { expect(wrapper.vm.$route).toBeInstanceOf(Object) ``` +## attachTo + +- 类型：`HTMLElement | string` +- 默认值：`null` + +指定一个 `HTMLElement` 或定位到一个 HTML 元素的 CSS 选择器字符串，组件将会被完全挂载到文档中的这个元素。 + +当要挂载到 DOM 时，你需要在测试的结尾调用 `wrapper.destroy()` 以将该元素从文档中移除，并销毁该组件实例。 + +```js +const Component = { + template: '
ABC
' +} +let wrapper = mount(Component, { + attachTo: '#root' +}) +expect(wrapper.vm.$el.parentNode).to.not.be.null +wrapper.destroy() + +wrapper = mount(Component, { + attachTo: document.getElementById('root') +}) +expect(wrapper.vm.$el.parentNode).to.not.be.null +wrapper.destroy() +``` + ## attachToDocument - 类型：`boolean` - 默认值：`false` -当设为 `true` 时，组件在渲染时将会挂载到 DOM 上。 +::: warning 废弃警告 +`attachToDocument` 已经被废弃并且将会在未来的发布中被移除。请换用 [`attachTo`](#attachto)。 +::: + +像 [`attachTo`](#attachto) 一样，不过会自动创建一个新的 `div` 元素并将其插入到 body 里。 如果添加到了 DOM 上，你应该在测试的最后调用 `wrapper.destroy()` 将元素从文档中移除并销毁组件实例。 @@ -244,6 +365,23 @@ expect(wrapper.text()).toBe('aBC') 设置组件实例的 `$listeners` 对象。 +示例： + +```js +const Component = { + template: '' +} +const onClick = jest.fn() +const wrapper = mount(Component, { + listeners: { + click: onClick + } +}) + +wrapper.trigger('click') +expect(onClick).toHaveBeenCalled() +``` + ## parentComponent - 类型：`Object` @@ -292,26 +430,22 @@ expect(wrapper.text()).toBe('fooValue') ```js const Component = { - template: '
{{ foo() }}{{ bar() }}{{ baz() }}
', - methods: { - foo() { - return 'a' - }, - bar() { - return 'b' + template: '
{{ foo }}
', + data() { + return { + foo: 'fromComponent' } } } const options = { - methods: { - bar() { - return 'B' - }, - baz() { - return 'C' + data() { + return { + foo: 'fromOptions' } } } + const wrapper = mount(Component, options) -expect(wrapper.text()).toBe('aBC') + +expect(wrapper.text()).toBe('fromOptions') ``` diff --git a/docs/zh/api/shallowMount.md b/docs/zh/api/shallowMount.md index 397e611fe..72290ad5f 100644 --- a/docs/zh/api/shallowMount.md +++ b/docs/zh/api/shallowMount.md @@ -4,6 +4,7 @@ - `{Component} component` - `{Object} options` + - `{HTMLElement|string} string` - `{boolean} attachToDocument` - `{Object} context` - `{Array|Component} children` @@ -64,10 +65,13 @@ import Foo from './Foo.vue' describe('Foo', () => { it('renders a div', () => { + const div = document.createElement('div') + document.body.appendChild(div) const wrapper = shallowMount(Foo, { - attachToDocument: true + attachTo: div }) expect(wrapper.contains('div')).toBe(true) + wrapper.destroy() }) }) ``` diff --git a/docs/zh/api/wrapper-array/at.md b/docs/zh/api/wrapper-array/at.md index 0c97ce46a..0bdb46494 100644 --- a/docs/zh/api/wrapper-array/at.md +++ b/docs/zh/api/wrapper-array/at.md @@ -1,6 +1,6 @@ ## at -返回第 `index` 个传入的 `Wrapper` 。数字从 0 开始计数 (比如第一个项目的索引值是 0)。 +返回第 `index` 个传入的 `Wrapper` 。数字从 0 开始计数 (比如第一个项目的索引值是 0)。如果 `index` 是负数，则从最后一个元素往回计数 (比如最后一个项目的索引值是 -1)。 - **参数：** @@ -16,6 +16,10 @@ import Foo from './Foo.vue' const wrapper = shallowMount(Foo) const divArray = wrapper.findAll('div') + const secondDiv = divArray.at(1) -expect(secondDiv.is('p')).toBe(true) +expect(secondDiv.is('div')).toBe(true) + +const lastDiv = divArray.at(-1) +expect(lastDiv.is('div')).toBe(true) ``` diff --git a/docs/zh/api/wrapper-array/is.md b/docs/zh/api/wrapper-array/is.md index ae72250bd..a4818f79f 100644 --- a/docs/zh/api/wrapper-array/is.md +++ b/docs/zh/api/wrapper-array/is.md @@ -15,6 +15,6 @@ import { mount } from '@vue/test-utils' import Foo from './Foo.vue' const wrapper = mount(Foo) -const divArray = wrapper.find('div') +const divArray = wrapper.findAll('div') expect(divArray.is('div')).toBe(true) ``` diff --git a/docs/zh/api/wrapper-array/isEmpty.md b/docs/zh/api/wrapper-array/isEmpty.md index d2db0dd51..1061b3012 100644 --- a/docs/zh/api/wrapper-array/isEmpty.md +++ b/docs/zh/api/wrapper-array/isEmpty.md @@ -1,5 +1,13 @@ ## isEmpty +::: warning 废弃警告 +`isEmpty` 已经被废弃并会在未来的发布中被移除。 + +可以考虑一个诸如 [jest-dom](https://github.com/testing-library/jest-dom#tobeempty) 中提供的自定义匹配。 + +当使用 `findComponent` 时，可以通过 `findComponent(Comp).element` 访问其 DOM 元素。 +::: + 断言 `WrapperArray` 的每个 `Wrapper` 都不包含子节点。 - **返回值：**`{boolean}` diff --git a/docs/zh/api/wrapper-array/isVueInstance.md b/docs/zh/api/wrapper-array/isVueInstance.md index 902acb541..86e1d605d 100644 --- a/docs/zh/api/wrapper-array/isVueInstance.md +++ b/docs/zh/api/wrapper-array/isVueInstance.md @@ -1,5 +1,13 @@ ## isVueInstance +::: warning 废弃警告 +`isVueInstance` 已经被废弃并会在未来的发布中被移除。 + +依赖 `isVueInstance` 断言的测试并没有特别大的意义，我们建议将与之相关的断言替换为更有目的性的断言。 + +为了保留这些测试，一个替换 `isVueInstance()` 的可行方式是对 `wrapper.find(...).vm` 的 truthy 断言。 +::: + 断言 `WrapperArray` 的每个 `Wrapper` 都是 Vue 实例。 - **返回值：**`{boolean}` diff --git a/docs/zh/api/wrapper-array/setMethods.md b/docs/zh/api/wrapper-array/setMethods.md index 5639f5603..87cf9bc78 100644 --- a/docs/zh/api/wrapper-array/setMethods.md +++ b/docs/zh/api/wrapper-array/setMethods.md @@ -1,5 +1,15 @@ ## setMethods +::: warning 废弃警告 +`setMethods` 已经被废弃并会在未来的发布中被移除。 + +这里没有明确的路径替换 `setMethods`，因为这取决于你之前的用法。这很容易导致依赖实现细节的琐碎的测试，而这是[不推荐的](https://github.com/vuejs/rfcs/blob/668866fa71d70322f6a7689e88554ab27d349f9c/active-rfcs/0000-vtu-api.md#setmethods)。 + +我们建议重新考虑那些测试。 + +如果是为了存根一个复杂方法，可将其从组件中提取出来并单独测试。如果是为了断言一个方法被调用，可使用你的测试运行器窥探它。 +::: + 为 `WrapperArray` 的每个 `Wrapper` `vm` 都设置方法并强行更新。 **注意：该包裹器必须包含一个 Vue 实例。** diff --git a/docs/zh/api/wrapper-array/trigger.md b/docs/zh/api/wrapper-array/trigger.md index a5020488d..7bcc17ceb 100644 --- a/docs/zh/api/wrapper-array/trigger.md +++ b/docs/zh/api/wrapper-array/trigger.md @@ -1,6 +1,6 @@ ## trigger -为 `WrapperArray` 的每个 `Wrapper` DOM 节点都触发一个事件。 +为 `WrapperArray` 的每个 `Wrapper` DOM 节点都触发一个[事件](../../guides/dom-events.md#触发事件)。 **注意：该包裹器必须包含一个 Vue 实例。** diff --git a/docs/zh/api/wrapper/README.md b/docs/zh/api/wrapper/README.md index 12ce49efd..9aff7a56e 100644 --- a/docs/zh/api/wrapper/README.md +++ b/docs/zh/api/wrapper/README.md @@ -4,6 +4,8 @@ Vue Test Utils 是一个基于包裹器的 API。 一个 `Wrapper` 是一个包括了一个挂载组件或 vnode，以及测试该组件或 vnode 的方法。 +
通过 Vue School 的免费视频学习 Wrapper 对象
+ ## 属性 ### `vm` @@ -18,31 +20,38 @@ Vue Test Utils 是一个基于包裹器的 API。 #### `options.attachedToDocument` -`Boolean` (只读)：如果组件在渲染之后被添加到了文档上则为真 +`Boolean` (只读)：如果组件在渲染之后被添加到了文档上则为 `true` + +### `selector` + +`Selector`: 被 [`find()`](./find.md) 或 [`findAll()`](./findAll.md) 创建这个 wrapper 时使用的选择器。 ## 方法 -!!!include(docs/zh/api/wrapper/attributes.md)!!! -!!!include(docs/zh/api/wrapper/classes.md)!!! -!!!include(docs/zh/api/wrapper/contains.md)!!! -!!!include(docs/zh/api/wrapper/destroy.md)!!! -!!!include(docs/zh/api/wrapper/emitted.md)!!! -!!!include(docs/zh/api/wrapper/emittedByOrder.md)!!! -!!!include(docs/zh/api/wrapper/exists.md)!!! -!!!include(docs/zh/api/wrapper/find.md)!!! -!!!include(docs/zh/api/wrapper/findAll.md)!!! -!!!include(docs/zh/api/wrapper/html.md)!!! -!!!include(docs/zh/api/wrapper/is.md)!!! -!!!include(docs/zh/api/wrapper/isEmpty.md)!!! -!!!include(docs/zh/api/wrapper/isVisible.md)!!! -!!!include(docs/zh/api/wrapper/isVueInstance.md)!!! -!!!include(docs/zh/api/wrapper/name.md)!!! -!!!include(docs/zh/api/wrapper/props.md)!!! -!!!include(docs/zh/api/wrapper/setChecked.md)!!! -!!!include(docs/zh/api/wrapper/setData.md)!!! -!!!include(docs/zh/api/wrapper/setMethods.md)!!! -!!!include(docs/zh/api/wrapper/setProps.md)!!! -!!!include(docs/zh/api/wrapper/setSelected.md)!!! -!!!include(docs/zh/api/wrapper/setValue.md)!!! -!!!include(docs/zh/api/wrapper/text.md)!!! -!!!include(docs/zh/api/wrapper/trigger.md)!!! +!!!include(docs/api/wrapper/attributes.md)!!! +!!!include(docs/api/wrapper/classes.md)!!! +!!!include(docs/api/wrapper/contains.md)!!! +!!!include(docs/api/wrapper/destroy.md)!!! +!!!include(docs/api/wrapper/emitted.md)!!! +!!!include(docs/api/wrapper/emittedByOrder.md)!!! +!!!include(docs/api/wrapper/exists.md)!!! +!!!include(docs/api/wrapper/find.md)!!! +!!!include(docs/api/wrapper/findAll.md)!!! +!!!include(docs/api/wrapper/findComponent.md)!!! +!!!include(docs/api/wrapper/findAllComponents.md)!!! +!!!include(docs/api/wrapper/html.md)!!! +!!!include(docs/api/wrapper/get.md)!!! +!!!include(docs/api/wrapper/is.md)!!! +!!!include(docs/api/wrapper/isEmpty.md)!!! +!!!include(docs/api/wrapper/isVisible.md)!!! +!!!include(docs/api/wrapper/isVueInstance.md)!!! +!!!include(docs/api/wrapper/name.md)!!! +!!!include(docs/api/wrapper/props.md)!!! +!!!include(docs/api/wrapper/setChecked.md)!!! +!!!include(docs/api/wrapper/setData.md)!!! +!!!include(docs/api/wrapper/setMethods.md)!!! +!!!include(docs/api/wrapper/setProps.md)!!! +!!!include(docs/api/wrapper/setSelected.md)!!! +!!!include(docs/api/wrapper/setValue.md)!!! +!!!include(docs/api/wrapper/text.md)!!! +!!!include(docs/api/wrapper/trigger.md)!!! diff --git a/docs/zh/api/wrapper/destroy.md b/docs/zh/api/wrapper/destroy.md index 74e585d8a..cb5a2f9b1 100644 --- a/docs/zh/api/wrapper/destroy.md +++ b/docs/zh/api/wrapper/destroy.md @@ -18,6 +18,6 @@ mount({ expect(spy.calledOnce).toBe(true) ``` -如果挂载时 `attachToDocument` 被设为 `true`，则组件的 DOM 元素也将会从文档中被移除。 +如果挂载时 `attachTo` 或 `attachToDocument` 选项导致组件被挂载到文档，则组件的 DOM 元素也将会从文档中被移除。 对于函数式组件来说，`destroy` 只会从文档中移除渲染出来的 DOM 元素。 diff --git a/docs/zh/api/wrapper/emittedByOrder.md b/docs/zh/api/wrapper/emittedByOrder.md index d06d0bc6f..c70bd960b 100644 --- a/docs/zh/api/wrapper/emittedByOrder.md +++ b/docs/zh/api/wrapper/emittedByOrder.md @@ -1,5 +1,11 @@ ## emittedByOrder +::: warning 废弃警告 +`emittedByOrder` 已经被废弃并会在未来的发布中被移除。 + +请换用 `wrapper.emitted`。 +::: + 返回一个包含由 `Wrapper` `vm` 触发的自定义事件的数组。 - **返回值：**`Array<{ name: string, args: Array }>` diff --git a/docs/zh/api/wrapper/find.md b/docs/zh/api/wrapper/find.md index 873fab022..0fe1f7a7e 100644 --- a/docs/zh/api/wrapper/find.md +++ b/docs/zh/api/wrapper/find.md @@ -1,12 +1,16 @@ ## find +::: warning 废弃警告 +使用 `find` 搜索组件的方式已经被废弃并会被移除。请换用 [`findComponent`](./findComponent.md)。 +::: + 返回匹配选择器的第一个 DOM 节点或 Vue 组件的 `Wrapper`。 -可以使用任何有效的[选择器](../selectors.md)。 +可以使用任何有效的 DOM 选择器 (使用 `querySelector` 语法)。 - **参数：** - - `{string|Component} selector` + - `{string} selector` - **返回值：**`{Wrapper}` @@ -20,14 +24,19 @@ import Bar from './Bar.vue' const wrapper = mount(Foo) const div = wrapper.find('div') -expect(div.is('div')).toBe(true) +expect(div.exists()).toBe(true) + +const byId = wrapper.find('#bar') +expect(byId.element.id).toBe('bar') +``` -const bar = wrapper.find(Bar) -expect(bar.is(Bar)).toBe(true) +- **注意：** -const barByName = wrapper.find({ name: 'bar' }) -expect(barByName.is(Bar)).toBe(true) + - 你可以链式调用 `find`： -const fooRef = wrapper.find({ ref: 'foo' }) -expect(fooRef.is(Foo)).toBe(true) +```js +const button = wrapper.find({ ref: 'testButton' }) +expect(button.find('.icon').exists()).toBe(true) ``` + +- **延伸阅读：**[get](./get.md) diff --git a/docs/zh/api/wrapper/findAll.md b/docs/zh/api/wrapper/findAll.md index 20322124b..cbd9550e7 100644 --- a/docs/zh/api/wrapper/findAll.md +++ b/docs/zh/api/wrapper/findAll.md @@ -1,5 +1,9 @@ ## findAll +::: warning 废弃警告 +使用 `findAll` 搜索组件的方式已经被废弃并会被移除。请换用 `findAllComponents`。 +::: + 返回一个 [`WrapperArray`](../wrapper-array/)。 可以使用任何有效的[选择器](../selectors.md)。 @@ -18,8 +22,10 @@ import Foo from './Foo.vue' import Bar from './Bar.vue' const wrapper = mount(Foo) + const div = wrapper.findAll('div').at(0) expect(div.is('div')).toBe(true) -const bar = wrapper.findAll(Bar).at(0) + +const bar = wrapper.findAll(Bar).at(0) // 已废弃的用法 expect(bar.is(Bar)).toBe(true) ``` diff --git a/docs/zh/api/wrapper/findAllComponents.md b/docs/zh/api/wrapper/findAllComponents.md new file mode 100644 index 000000000..ce93af3a2 --- /dev/null +++ b/docs/zh/api/wrapper/findAllComponents.md @@ -0,0 +1,23 @@ +## findAllComponents + +为所有匹配的 Vue 组件返回一个 [`WrapperArray`](../wrapper-array/)。 + +- **参数：** + + - `{Component|ref|name} selector` + +- **返回值：** `{WrapperArray}` + +- **示例：** + +```js +import { mount } from '@vue/test-utils' +import Foo from './Foo.vue' +import Bar from './Bar.vue' + +const wrapper = mount(Foo) +const bar = wrapper.findAllComponents(Bar).at(0) +expect(bar.exists()).toBeTruthy() +const bars = wrapper.findAllComponents(Bar) +expect(bar).toHaveLength(1) +``` diff --git a/docs/zh/api/wrapper/findComponent.md b/docs/zh/api/wrapper/findComponent.md new file mode 100644 index 000000000..38e099d5f --- /dev/null +++ b/docs/zh/api/wrapper/findComponent.md @@ -0,0 +1,26 @@ +## findComponent + +返回第一个匹配的 Vue 组件的 `Wrapper`。 + +- **参数：** + + - `{Component|ref|name} selector` + +- **返回值：** `{Wrapper}` + +- **示例：** + +```js +import { mount } from '@vue/test-utils' +import Foo from './Foo.vue' +import Bar from './Bar.vue' + +const wrapper = mount(Foo) + +const bar = wrapper.findComponent(Bar) // => 通过组件实例找到 Bar +expect(bar.exists()).toBe(true) +const barByName = wrapper.findComponent({ name: 'bar' }) // => 通过 `name` 找到 Bar +expect(barByName.exists()).toBe(true) +const barRef = wrapper.findComponent({ ref: 'bar' }) // => 通过 `ref` 找到 Bar +expect(barRef.exists()).toBe(true) +``` diff --git a/docs/zh/api/wrapper/get.md b/docs/zh/api/wrapper/get.md new file mode 100644 index 000000000..fca5c1316 --- /dev/null +++ b/docs/zh/api/wrapper/get.md @@ -0,0 +1,20 @@ +## get + +和 [find](./find.md) 工作起来一样，但是如果未匹配到给定的选择器时会抛出错误。当搜索一个可能不存在的元素时你应该使用 `find`。当获取一个应该存在的元素时你应该使用这个方法，并且如果没有找到的话它会提供一则友好的错误信息。 + +```js +import { mount } from '@vue/test-utils' + +const wrapper = mount(Foo) + +// 和 `wrapper.find` 相似。 +// 如果 `get` 没有找到任何元素将会抛出一个而错误。`find` 则不会做任何事。 +expect(wrapper.get('.does-exist')) + +expect(() => wrapper.get('.does-not-exist')) + .to.throw() + .with.property( + 'message', + 'Unable to find .does-not-exist within:
the actual DOM here...
' + ) +``` diff --git a/docs/zh/api/wrapper/is.md b/docs/zh/api/wrapper/is.md index 5d56a2663..e46eca50b 100644 --- a/docs/zh/api/wrapper/is.md +++ b/docs/zh/api/wrapper/is.md @@ -1,5 +1,19 @@ ## is +::: warning 废弃警告 +使用 `is` 断言 DOM 结点或 `vm` 匹配选择器的方式已经被废弃并会被移除。 + +可以考虑一个诸如 [jest-dom](https://github.com/testing-library/jest-dom#custom-matchers) 提供的自定义匹配。或为 DOM 元素类型断言换用原生的 [`Element.tagName`](https://developer.mozilla.org/en-US/docs/Web/API/Element/tagName)。 + +为了保留这些测试，一个有效替换： + +- `is('DOM_SELECTOR')` 的方式是一个 `wrapper.element.tagName` 的断言。 +- `is('ATTR_NAME')` 的方式是一个 `wrapper.attributes('ATTR_NAME')` 的 truthy 断言。 +- `is('CLASS_NAME')` 的方式是一个 `wrapper.classes('CLASS_NAME')` 的 truthy 断言。 + +当使用 `findComponent` 时，通过 `findComponent(Comp).element` 访问 DOM 元素。 +::: + 断言 `Wrapper` DOM 节点或 `vm` 匹配[选择器](../selectors.md)。 - **参数：** diff --git a/docs/zh/api/wrapper/isEmpty.md b/docs/zh/api/wrapper/isEmpty.md index 6c57618a5..747fbfc45 100644 --- a/docs/zh/api/wrapper/isEmpty.md +++ b/docs/zh/api/wrapper/isEmpty.md @@ -1,5 +1,13 @@ ## isEmpty +::: warning 废弃警告 +`isEmpty` 已经被废弃并会在未来的发布中被移除。 + +可以考虑一个诸如 [jest-dom](https://github.com/testing-library/jest-dom#tobeempty) 中提供的自定义匹配。 + +当使用 `findComponent` 时，可以通过 `findComponent(Comp).element` 访问其 DOM 元素。 +::: + 断言 `Wrapper` 并不包含子节点。 - **返回值：**`{boolean}` diff --git a/docs/zh/api/wrapper/isVisible.md b/docs/zh/api/wrapper/isVisible.md index 11ff01c5b..f572e073e 100644 --- a/docs/zh/api/wrapper/isVisible.md +++ b/docs/zh/api/wrapper/isVisible.md @@ -1,5 +1,13 @@ ## isVisible +::: warning 废弃警告 +`isVisible` 已经被废弃并会在未来的发布中被移除。 + +可以考虑一个诸如 [jest-dom](https://github.com/testing-library/jest-dom#tobeempty) 中提供的自定义匹配。 + +当使用 `findComponent` 时，可以通过 `findComponent(Comp).element` 访问其 DOM 元素。 +::: + 断言 `Wrapper` 是否可见。 如果有一个祖先元素拥有 `display: none` 或 `visibility: hidden` 样式则返回 `false`。 diff --git a/docs/zh/api/wrapper/isVueInstance.md b/docs/zh/api/wrapper/isVueInstance.md index ebb134bfd..4ea36e2cb 100644 --- a/docs/zh/api/wrapper/isVueInstance.md +++ b/docs/zh/api/wrapper/isVueInstance.md @@ -1,5 +1,13 @@ ## isVueInstance +::: warning 废弃警告 +`isVueInstance` 已经被废弃并会在未来的发布中被移除。 + +依赖 `isVueInstance` 断言的测试并没有特别大的意义，我们建议将与之相关的断言替换为更有目的性的断言。 + +为了保留这些测试，一个替换 `isVueInstance()` 的可行方式是对 `wrapper.find(...).vm` 的 truthy 断言。 +::: + 断言 `Wrapper` 是 Vue 实例。 - **返回值：**`{boolean}` diff --git a/docs/zh/api/wrapper/name.md b/docs/zh/api/wrapper/name.md index 32eee5406..42a577b52 100644 --- a/docs/zh/api/wrapper/name.md +++ b/docs/zh/api/wrapper/name.md @@ -1,5 +1,9 @@ ## name +::: warning 废弃警告 +`name` 已经被废弃并会在未来的发布中被移除。 +::: + 如果 `Wrapper` 包含一个 Vue 实例则返回组件名，否则返回 `Wrapper` DOM 节点的标签名。 - **返回值：**`{string}` diff --git a/docs/zh/api/wrapper/overview.md b/docs/zh/api/wrapper/overview.md new file mode 100644 index 000000000..30a3f8b1e --- /dev/null +++ b/docs/zh/api/wrapper/overview.md @@ -0,0 +1,47 @@ +## overview + +::: warning 废弃警告 +`overview` 已经被废弃并会在未来的发布中被移除。 +::: + +打印一个简单的 `Wrapper` 的总览。 + +- **示例：** + +```js +import { mount } from '@vue/test-utils' +import Component from './Component.vue' + +const wrapper = mount(Component) +wrapper.overview() + +// Console output +/* +Wrapper (Visible): + +Html: +
+

My name is Tess Ting

+
+ +Data: { + firstName: Tess, + lastName: Ting +} + +Computed: { + fullName: Tess Ting' +} + +Emitted: {', + foo: [', + 0: [ hello, world ], + 1: [ bye, world ]' + ], + bar: [ + 0: [ hey ]' + ] +} + +*/ +``` diff --git a/docs/zh/api/wrapper/setMethods.md b/docs/zh/api/wrapper/setMethods.md index 4107067f3..18b6747ee 100644 --- a/docs/zh/api/wrapper/setMethods.md +++ b/docs/zh/api/wrapper/setMethods.md @@ -1,5 +1,15 @@ ## setMethods +::: warning 废弃警告 +`setMethods` 已经被废弃并会在未来的发布中被移除。 + +这里没有明确的路径替换 `setMethods`，因为这取决于你之前的用法。这很容易导致依赖实现细节的琐碎的测试，而这是[不推荐的](https://github.com/vuejs/rfcs/blob/668866fa71d70322f6a7689e88554ab27d349f9c/active-rfcs/0000-vtu-api.md#setmethods)。 + +我们建议重新考虑那些测试。 + +如果是为了存根一个复杂方法，可将其从组件中提取出来并单独测试。如果是为了断言一个方法被调用，可使用你的测试运行器窥探它。 +::: + 设置 `Wrapper` `vm` 的方法并强制更新。 **注意：该包裹器必须包含一个 Vue 示例。** diff --git a/docs/zh/api/wrapper/trigger.md b/docs/zh/api/wrapper/trigger.md index 861679de4..161747268 100644 --- a/docs/zh/api/wrapper/trigger.md +++ b/docs/zh/api/wrapper/trigger.md @@ -1,8 +1,8 @@ ## trigger -在该 `Wrapper` DOM 节点上触发一个事件。 +在该 `Wrapper` DOM 节点上异步触发一个事件。 -`trigger` 带有一个可选的 `options` 对象。`options` 对象内的属性会被添加到事件上。 +`trigger` 带有一个可选的 `options` 对象。`options` 对象内的属性会被添加到事件上。`trigger` 会返回一个 Promise，当这个 Promise 被解决时，会确保组件已经被更新。 - **参数：** @@ -22,18 +22,16 @@ test('trigger demo', async () => { propsData: { clickHandler } }) - wrapper.trigger('click') + await wrapper.trigger('click') - wrapper.trigger('click', { + await wrapper.trigger('click', { button: 0 }) - wrapper.trigger('click', { + await wrapper.trigger('click', { ctrlKey: true // 用于测试 @click.ctrl 处理函数 }) - await wrapper.vm.$nextTick() // 等待事件处理完成 - expect(clickHandler.called).toBe(true) }) ```