diff --git a/docs/README.md b/docs/README.md
index 88828b481..92bfff594 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -45,6 +45,7 @@ Vue Test Utils is the official unit testing utility library for 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/api/wrapper/README.md b/docs/api/wrapper/README.md
index 80346d1d1..0bf6c0415 100644
--- a/docs/api/wrapper/README.md
+++ b/docs/api/wrapper/README.md
@@ -36,6 +36,7 @@ A `Wrapper` is an object that contains a mounted component or vnode and methods
!!!include(docs/api/wrapper/find.md)!!!
!!!include(docs/api/wrapper/findAll.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)!!!
diff --git a/docs/api/wrapper/find.md b/docs/api/wrapper/find.md
index 98b69c399..04c6c282e 100644
--- a/docs/api/wrapper/find.md
+++ b/docs/api/wrapper/find.md
@@ -31,3 +31,5 @@ expect(barByName.is(Bar)).toBe(true)
const fooRef = wrapper.find({ ref: 'foo' })
expect(fooRef.is(Foo)).toBe(true)
```
+
+See also: [get](../get.md).
diff --git a/docs/api/wrapper/get.md b/docs/api/wrapper/get.md
new file mode 100644
index 000000000..d1ebd7d13
--- /dev/null
+++ b/docs/api/wrapper/get.md
@@ -0,0 +1,23 @@
+## get
+
+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
+exist and it will provide a nice error message if that is not the case.
+
+```js
+import { mount } from '@vue/test-utils'
+
+const wrapper = mount(Foo)
+
+// similar to `wrapper.find`.
+// `get` will throw an error if an element is not found. `find` will do nothing.
+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/packages/test-utils/src/wrapper.js b/packages/test-utils/src/wrapper.js
index 816ec1620..b8beeca16 100644
--- a/packages/test-utils/src/wrapper.js
+++ b/packages/test-utils/src/wrapper.js
@@ -185,6 +185,18 @@ export default class Wrapper implements BaseWrapper {
throwError('filter() must be called on a WrapperArray')
}
+ /**
+ * Gets first node in tree of the current wrapper that
+ * matches the provided selector.
+ */
+ get(rawSelector: Selector): Wrapper {
+ const found = this.find(rawSelector)
+ if (found instanceof ErrorWrapper) {
+ throw new Error(`Unable to find ${rawSelector} within: ${this.html()}`)
+ }
+ return found
+ }
+
/**
* Finds first node in tree of the current wrapper that
* matches the provided selector.
diff --git a/packages/test-utils/types/index.d.ts b/packages/test-utils/types/index.d.ts
index 28d0153b6..42a177e55 100644
--- a/packages/test-utils/types/index.d.ts
+++ b/packages/test-utils/types/index.d.ts
@@ -77,6 +77,13 @@ export interface Wrapper extends BaseWrapper {
readonly element: HTMLElement
readonly options: WrapperOptions
+ get (selector: VueClass): Wrapper
+ get (selector: ComponentOptions): Wrapper
+ get (selector: FunctionalComponentOptions): Wrapper
+ get (selector: string): Wrapper
+ get (selector: RefSelector): Wrapper
+ get (selector: NameSelector): Wrapper
+
find (selector: VueClass): Wrapper
find (selector: ComponentOptions): Wrapper
find (selector: FunctionalComponentOptions): Wrapper
diff --git a/packages/test-utils/types/test/wrapper.ts b/packages/test-utils/types/test/wrapper.ts
index 9e331c729..66c1884b5 100644
--- a/packages/test-utils/types/test/wrapper.ts
+++ b/packages/test-utils/types/test/wrapper.ts
@@ -72,6 +72,13 @@ selector = array.selector
array = wrapper.findAll({ name: 'my-button' })
selector = array.selector
+let gotten = wrapper.get('.foo')
+gotten = wrapper.get(normalOptions)
+gotten = wrapper.get(functionalOptions)
+gotten = wrapper.get(ClassComponent)
+gotten = wrapper.get({ ref: 'myButton' })
+gotten = wrapper.get({ name: 'my-button' })
+
wrapper.setChecked()
wrapper.setChecked(true)
wrapper.setValue('some string')
diff --git a/test/specs/wrapper/get.spec.js b/test/specs/wrapper/get.spec.js
new file mode 100644
index 000000000..5afba8e9b
--- /dev/null
+++ b/test/specs/wrapper/get.spec.js
@@ -0,0 +1,20 @@
+import { compileToFunctions } from 'vue-template-compiler'
+import { describeWithShallowAndMount } from '~resources/utils'
+
+describeWithShallowAndMount('get', mountingMethod => {
+ it('throws describing error when element not found', () => {
+ const compiled = compileToFunctions('')
+ const wrapper = mountingMethod(compiled)
+ expect(() => wrapper.get('.does-not-exist'))
+ .to.throw()
+ .with.property(
+ 'message',
+ 'Unable to find .does-not-exist within: '
+ )
+ })
+ it('gets the element when element is found', () => {
+ const compiled = compileToFunctions('')
+ const wrapper = mountingMethod(compiled)
+ expect(wrapper.get('.does-exist')).to.be.an('object')
+ })
+})