From 669541f78d30480fcb8ab19c99f202849d867031 Mon Sep 17 00:00:00 2001
From: Jinjiang <zhaojinjiang@me.com>
Date: Mon, 8 Jun 2020 00:48:16 +0800
Subject: [PATCH 1/4] docs(zh): updated api docs 950763f...a0b40f0

---
 docs/zh/README.md                          |   5 +
 docs/zh/api/README.md                      |   1 +
 docs/zh/api/config.md                      |  14 +-
 docs/zh/api/createLocalVue.md              |   2 +
 docs/zh/api/enableAutoDestroy.md           |  25 +++
 docs/zh/api/mount.md                       |  13 +-
 docs/zh/api/options.md                     | 169 ++++++++++++++++++---
 docs/zh/api/shallowMount.md                |   6 +-
 docs/zh/api/wrapper-array/at.md            |   8 +-
 docs/zh/api/wrapper-array/is.md            |   2 +-
 docs/zh/api/wrapper-array/isEmpty.md       |   8 +
 docs/zh/api/wrapper-array/isVueInstance.md |   8 +
 docs/zh/api/wrapper-array/setMethods.md    |  10 ++
 docs/zh/api/wrapper-array/trigger.md       |   2 +-
 docs/zh/api/wrapper/README.md              |  59 ++++---
 docs/zh/api/wrapper/destroy.md             |   2 +-
 docs/zh/api/wrapper/emittedByOrder.md      |   6 +
 docs/zh/api/wrapper/find.md                |  27 ++--
 docs/zh/api/wrapper/findAll.md             |   8 +-
 docs/zh/api/wrapper/findAllComponents.md   |  23 +++
 docs/zh/api/wrapper/findComponent.md       |  26 ++++
 docs/zh/api/wrapper/get.md                 |  20 +++
 docs/zh/api/wrapper/is.md                  |  14 ++
 docs/zh/api/wrapper/isEmpty.md             |   8 +
 docs/zh/api/wrapper/isVisible.md           |   8 +
 docs/zh/api/wrapper/isVueInstance.md       |   8 +
 docs/zh/api/wrapper/name.md                |   4 +
 docs/zh/api/wrapper/overview.md            |  47 ++++++
 docs/zh/api/wrapper/setMethods.md          |  10 ++
 docs/zh/api/wrapper/trigger.md             |  12 +-
 30 files changed, 486 insertions(+), 69 deletions(-)
 create mode 100644 docs/zh/api/enableAutoDestroy.md
 create mode 100644 docs/zh/api/wrapper/findAllComponents.md
 create mode 100644 docs/zh/api/wrapper/findComponent.md
 create mode 100644 docs/zh/api/wrapper/get.md
 create mode 100644 docs/zh/api/wrapper/overview.md

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 官方的单元测试实用工具库。
 
+<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)
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..fad3ed58a 100644
--- a/docs/zh/api/config.md
+++ b/docs/zh/api/config.md
@@ -4,6 +4,18 @@ Vue Test Utils 包含了一个定义其选项的配置对象。
 
 ### Vue Test Utils 配置选项
 
+### `showDeprecationWarnings`
+
+关闭废弃警告。
+
+示例：
+
+```js
+import { config } from '@vue/test-utils'
+
+config.showDeprecationWarnings = false
+```
+
 ### `stubs`
 
 - 类型：`{ [name: string]: Component | boolean | string }`
@@ -46,7 +58,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: '<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/)
diff --git a/docs/zh/api/options.md b/docs/zh/api/options.md
index dfca20fb9..0a5135db4 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: `
+    <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,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: '<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'],
@@ -67,7 +119,17 @@ const wrapper = shallowMount(Component, {
     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,43 @@ const wrapper = mount(Component, {
 expect(wrapper.vm.$route).toBeInstanceOf(Object)
 ```
 
+## attachTo
+
+- 类型：`HTMLElement | string`
+- 默认值：`null`
+
+指定一个 HTMLElement 或定位到一个 HTML Element 的 CSS 选择器字符串，组件将会被完全挂载到文档中的这个元素。
+
+remove the rendered elements from the document and destroy the component instance.
+当挂载到这个 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 +366,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 +431,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')
 ```
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|Object>|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 的方法。
 
+<div class="vueschool"><a href="https://vueschool.io/lessons/the-wrapper-object?friend=vuejs" target="_blank" rel="sponsored noopener" title="Learn about the Wrapper object in a FREE video lesson from Vue School">通过 Vue School 的免费视频学习 Wrapper 对象</a></div>
+
 ## 属性
 
 ### `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<any> }>`
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..b1e3f6631
--- /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: <div>the actual DOM here...</div>'
+  )
+```
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:
+    <div class="test">
+      <p>My name is Tess Ting</p>
+    </div>
+
+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)
 })
 ```

From ee7677f50f71f5c8c92cb620b57aeb6e57867ccb Mon Sep 17 00:00:00 2001
From: Jinjiang <zhaojinjiang@me.com>
Date: Wed, 10 Jun 2020 09:22:32 +0800
Subject: [PATCH 2/4] Update options.md

---
 docs/zh/api/options.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/zh/api/options.md b/docs/zh/api/options.md
index 0a5135db4..8da59b785 100644
--- a/docs/zh/api/options.md
+++ b/docs/zh/api/options.md
@@ -187,7 +187,7 @@ shallowMount(Component, {
 ```
 
 ::: warning 必备根元素
-由于该特性内部实现的原因，这里的插槽内容不得不返回一个根元素，即使一个作用域插槽是允许返回一个元素数组的。
+由于该特性内部实现的原因，这里的插槽内容必须返回一个根元素，即使一个作用域插槽是允许返回一个元素数组的。
 
 如果你在测试中有这方面的需要，推荐的变通方式是把被测试的组件包裹在另一个组件里，然后挂载那个组件：
 :::
@@ -294,10 +294,9 @@ expect(wrapper.vm.$route).toBeInstanceOf(Object)
 - 类型：`HTMLElement | string`
 - 默认值：`null`
 
-指定一个 HTMLElement 或定位到一个 HTML Element 的 CSS 选择器字符串，组件将会被完全挂载到文档中的这个元素。
+指定一个 `HTMLElement` 或定位到一个 HTML 元素的 CSS 选择器字符串，组件将会被完全挂载到文档中的这个元素。
 
-remove the rendered elements from the document and destroy the component instance.
-当挂载到这个 DOM 时，你需要在测试的结尾调用 `wrapper.destroy()` 以将该元素从文档中移除，并销毁该组件实例。
+当要挂载到 DOM 时，你需要在测试的结尾调用 `wrapper.destroy()` 以将该元素从文档中移除，并销毁该组件实例。
 
 ```js
 const Component = {

From 64ec843f31529218bcdfae00be21bd80bc9ae60e Mon Sep 17 00:00:00 2001
From: Jinjiang <zhaojinjiang@me.com>
Date: Wed, 10 Jun 2020 09:22:53 +0800
Subject: [PATCH 3/4] Update findAllComponents.md

---
 docs/zh/api/wrapper/findAllComponents.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/zh/api/wrapper/findAllComponents.md b/docs/zh/api/wrapper/findAllComponents.md
index b1e3f6631..ce93af3a2 100644
--- a/docs/zh/api/wrapper/findAllComponents.md
+++ b/docs/zh/api/wrapper/findAllComponents.md
@@ -1,6 +1,6 @@
 ## findAllComponents
 
-未所有匹配的 Vue 组件返回一个 [`WrapperArray`](../wrapper-array/)。
+为所有匹配的 Vue 组件返回一个 [`WrapperArray`](../wrapper-array/)。
 
 - **参数：**
 

From 0de0f04e7917c30d90123c3870ea07d60b64dcf4 Mon Sep 17 00:00:00 2001
From: Jinjiang <zhaojinjiang@me.com>
Date: Thu, 11 Jun 2020 23:54:17 +0800
Subject: [PATCH 4/4] Update config.md

---
 docs/zh/api/config.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/zh/api/config.md b/docs/zh/api/config.md
index fad3ed58a..71a17a334 100644
--- a/docs/zh/api/config.md
+++ b/docs/zh/api/config.md
@@ -6,7 +6,10 @@ Vue Test Utils 包含了一个定义其选项的配置对象。
 
 ### `showDeprecationWarnings`
 
-关闭废弃警告。
+- 类型：`Boolean`
+- 默认值：`true`
+
+控制是否展示废弃警告。当设置为 `true` 时，所有的废弃警告都将会在控制台中打印出来。
 
 示例：