add the wrapper.getComponent method and corresponding documents. (#1714)

* feat: add the wrapper.getComponent method
docs: create the /docs/api/wrapper/getComponent.md, and add the deprecation message to the /docs/api/wrapper/get.md
docs(zh): create the /docs/zh/api/wrapper/getComponent.md, and add the deprecation message to the /docs/zh/api/wrapper/get.md

* Update packages/test-utils/src/wrapper.js

Co-authored-by: Adrià Fontcuberta <[email protected]>

* Update docs/api/wrapper/getComponent.md

Co-authored-by: Adrià Fontcuberta <[email protected]>

* Update docs/zh/api/wrapper/getComponent.md

Co-authored-by: Adrià Fontcuberta <[email protected]>

* Update docs/zh/api/wrapper/getComponent.md

Co-authored-by: Adrià Fontcuberta <[email protected]>

* Update docs/api/wrapper/getComponent.md

Co-authored-by: Adrià Fontcuberta <[email protected]>

Co-authored-by: yinquan <[email protected]>
Co-authored-by: Adrià Fontcuberta <[email protected]>

Author: 3 people

docs/api/wrapper/get.md

@@ -1,5 +1,9 @@
 ## get
 
+::: warning Deprecation warning
+Using `get` to search for a Component is deprecated and will be removed. Use [`getComponent`](./getComponent.md) instead.
+:::
+
 Works just like [find](./find.md) but will throw an error if nothing matching
 the given selector is found. You should use `find` when searching for an element
 that may not exist. You should use this method when getting an element that should

docs/api/wrapper/getComponent.md

@@ -0,0 +1,27 @@
+## getComponent
+
+Works just like [findComponent](./findComponent.md) but will throw an error if nothing matching
+the given selector is found. You should use `findComponent` when searching for an element
+that may not exist. You should use this method when getting an element that should
+exist and it will provide a nice error message if that is not the case.
+
+```js
+import { mount } from '@vue/test-utils'
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
+
+const wrapper = mount(Foo)
+
+// similar to `wrapper.findComponent`.
+// `getComponent` will throw an error if an element is not found. `findComponent` will do nothing.
+expect(wrapper.getComponent(Bar)) // => gets Bar by component instance
+expect(wrapper.getComponent({ name: 'bar' })) // => gets Bar by `name`
+expect(wrapper.getComponent({ ref: 'bar' })) // => gets Bar by `ref`
+
+expect(() => wrapper.getComponent({ name: 'does-not-exist' }))
+  .to.throw()
+  .with.property(
+    'message',
+    "Unable to get a component named 'does-not-exist' within: <div>the actual DOM here...</div>"
+  )
+```

docs/zh/api/wrapper/get.md

@@ -1,5 +1,9 @@
 ## get
 
+::: warning 废弃警告
+使用 `get` 搜索组件的方式已经被废弃并会被移除。请换用 [`getComponent`](./getComponent.md)。
+:::
+
 和 [find](./find.md) 工作起来一样，但是如果未匹配到给定的选择器时会抛出错误。当搜索一个可能不存在的元素时你应该使用 `find`。当获取一个应该存在的元素时你应该使用这个方法，并且如果没有找到的话它会提供一则友好的错误信息。
 
 ```js

docs/zh/api/wrapper/getComponent.md

@@ -0,0 +1,24 @@
+## getComponent
+
+和 [findComponent](./findComponent.md) 工作起来一样，但是如果未匹配到给定的选择器时会抛出错误。当搜索一个可能不存在的元素时你应该使用 `findComponent`。当获取一个应该存在的元素时你应该使用这个方法，并且如果没有找到的话它会提供一则友好的错误信息。
+
+```js
+import { mount } from '@vue/test-utils'
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
+
+const wrapper = mount(Foo)
+
+// 和 `wrapper.findComponent` 相似。
+// 如果 `getComponent` 没有找到任何元素将会抛出一个而错误。`findComponent` 则不会做任何事。
+expect(wrapper.getComponent(Bar)) // => gets Bar by component instance
+expect(wrapper.getComponent({ name: 'bar' })) // => gets Bar by `name`
+expect(wrapper.getComponent({ ref: 'bar' })) // => gets Bar by `ref`
+
+expect(() => wrapper.getComponent({ name: 'does-not-exist' }))
+  .to.throw()
+  .with.property(
+    'message',
+    "Unable to get a component named 'does-not-exist' within: <div>the actual DOM here...</div>"
+  )
+```

packages/test-utils/src/wrapper.js

@@ -237,6 +237,20 @@ export default class Wrapper implements BaseWrapper {
     return found
   }
 
+  /**
+   * Gets first node in tree of the current wrapper that
+   * matches the provided selector.
+   */
+  getComponent(rawSelector: Selector): Wrapper {
+    this.__warnIfDestroyed()
+
+    const found = this.findComponent(rawSelector)
+    if (found instanceof ErrorWrapper) {
+      throw new Error(`Unable to get ${rawSelector} within: ${this.html()}`)
+    }
+    return found
+  }
+
   /**
    * Finds first DOM node in tree of the current wrapper that
    * matches the provided selector.
@@ -248,7 +262,7 @@ export default class Wrapper implements BaseWrapper {
     if (selector.type !== DOM_SELECTOR) {
       warnDeprecated(
         'finding components with `find` or `get`',
-        'Use `findComponent` instead'
+        'Use `findComponent` and `getComponent` instead'
       )
     }