docs(zh): updated api docs 950763f...a0b40f0 (#1568)

* docs(zh): updated api docs 950763f...a0b40f0

* Update options.md

* Update findAllComponents.md

* Update config.md

Author: Jinjiang

docs/zh/README.md

@@ -2,6 +2,8 @@
 
 Vue Test Utils 是 Vue.js 官方的单元测试实用工具库。
 
+<div class="vueschool"><a href="https://vueschool.io/courses/learn-how-to-test-vuejs-components?friend=vuejs" target="_blank" rel="sponsored noopener" title="Learn how to use Vue Test Utils to test Vue.js Components with Vue School">在 Vue School 学习如何测试 Vue.js 组件</a></div>
+
 - [教程](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)

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)!!!

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` 中的方法集合。
 
 示例：
 

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 }

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()`
+  })
+})
+```

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: '<div class="stubbed" />',
         BarFoo: true,
-        FooBar: Faz
+        FooBar: Faz,
+        Bar: { template: '<div class="stubbed" />' }
       }
     })
     expect(wrapper.contains('.stubbed')).toBe(true)
@@ -127,4 +130,8 @@ describe('Foo', () => {
 })
 ```
 
+**废弃通知：**
+
+当对组件存根时，提供一个字符串的方式 (`ComponentToStub: '<div class="stubbed" />`) 已经不再被支持。
+
 - **延伸阅读：**[`Wrapper`](wrapper/)

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: `
+    <div>
+      <span id="foo">{{ foo }}</span>
+      <span id="bar">{{ bar }}</span>
+    </div>
+  `,
+
+  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>|Component|string }`
@@ -54,20 +93,43 @@ expect(wrapper.is(Component)).toBe(true)
 
 ```js
 import Foo from './Foo.vue'
+import MyComponent from './MyComponent.vue'
 
 const bazComponent = {
   name: 'baz-component',
   template: '<p>baz</p>'
 }
 
+const yourComponent = {
+  props: {
+    foo: {
+      type: String,
+      required: true
+    }
+  },
+  render(h) {
+    return h('p', this.foo)
+  }
+}
+
 const wrapper = shallowMount(Component, {
   slots: {
     default: [Foo, '<my-component />', 'text'],
     fooBar: Foo, // 将会匹配 `<slot name="FooBar" />`.
     foo: '<div />',
     bar: 'bar',
     baz: bazComponent,
-    qux: '<my-component />'
+    qux: '<my-component />',
+    quux: '<your-component foo="lorem"/><your-component :foo="yourProperty"/>'
+  },
+  stubs: {
+    // 用来注册自定义组件
+    'my-component': MyComponent,
+    'your-component': yourComponent
+  },
+  mocks: {
+    // 用来向渲染上下文添加 property
+    yourProperty: 'ipsum'
   }
 })
 
@@ -124,12 +186,37 @@ shallowMount(Component, {
 })
 ```
 
+::: warning 必备根元素
+由于该特性内部实现的原因，这里的插槽内容必须返回一个根元素，即使一个作用域插槽是允许返回一个元素数组的。
+
+如果你在测试中有这方面的需要，推荐的变通方式是把被测试的组件包裹在另一个组件里，然后挂载那个组件：
+:::
+
+```javascript
+const WrapperComp = {
+  template: `
+  <ComponentUnderTest v-slot="props">
+    <p>Using the {{props.a}}</p>
+    <p>Using the {{props.a}}</p>
+  </ComponentUnderTest>
+  `,
+  components: {
+    ComponentUnderTest
+  }
+}
+const wrapper = mount(WrapperComp).find(ComponentUnderTest)
+```
+
 ## stubs
 
-- 类型：`{ [name: string]: Component | boolean } | Array<string>`
+- 类型：`{ [name: string]: Component | string | boolean } | Array<string>`
 
 将子组件存根。可以是一个要存根的组件名的数组或对象。如果 `stubs` 是一个数组，则每个存根都是一个 `<${component name}-stub>`。
 
+**废弃通知：**
+
+当对组件存根时，提供一个字符串的方式 (`ComponentToStub: '<div class="stubbed" />`) 已经不再被支持。
+
 示例：
 
 ```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: '<div>ABC</div>'
+}
+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: '<button v-on:click="$emit(\'click\')"></button>'
+}
+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: '<div>{{ foo() }}{{ bar() }}{{ baz() }}</div>',
-  methods: {
-    foo() {
-      return 'a'
-    },
-    bar() {
-      return 'b'
+  template: '<div>{{ foo }}</div>',
+  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')
 ```