diff --git a/docs/api/wrapper/get.md b/docs/api/wrapper/get.md
index 5462c668d..fa3c679d4 100644
--- a/docs/api/wrapper/get.md
+++ b/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
diff --git a/docs/api/wrapper/getComponent.md b/docs/api/wrapper/getComponent.md
new file mode 100644
index 000000000..b354e9d2b
--- /dev/null
+++ b/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:
the actual DOM here...
"
+ )
+```
diff --git a/docs/zh/api/wrapper/get.md b/docs/zh/api/wrapper/get.md
index fca5c1316..317fa2aa7 100644
--- a/docs/zh/api/wrapper/get.md
+++ b/docs/zh/api/wrapper/get.md
@@ -1,5 +1,9 @@
## get
+::: warning 废弃警告
+使用 `get` 搜索组件的方式已经被废弃并会被移除。请换用 [`getComponent`](./getComponent.md)。
+:::
+
和 [find](./find.md) 工作起来一样,但是如果未匹配到给定的选择器时会抛出错误。当搜索一个可能不存在的元素时你应该使用 `find`。当获取一个应该存在的元素时你应该使用这个方法,并且如果没有找到的话它会提供一则友好的错误信息。
```js
diff --git a/docs/zh/api/wrapper/getComponent.md b/docs/zh/api/wrapper/getComponent.md
new file mode 100644
index 000000000..be3507f31
--- /dev/null
+++ b/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: the actual DOM here...
"
+ )
+```
diff --git a/packages/test-utils/src/wrapper.js b/packages/test-utils/src/wrapper.js
index c56a899c5..3b3160949 100644
--- a/packages/test-utils/src/wrapper.js
+++ b/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'
)
}