Merge pull request #1304 from tomasbjerre/feature/issue-1298-get-method-on-wrapper

Adding get method to Wrapper

Author: lmiller1990

Diff for: 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 for: 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 for: 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 for: 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: <div>the actual DOM here...</div>'
+  )
+```

Diff for: 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 for: packages/test-utils/types/index.d.ts

@@ -77,6 +77,13 @@ export interface Wrapper<V extends Vue | null> extends BaseWrapper {
   readonly element: HTMLElement
   readonly options: WrapperOptions
 
+  get<R extends Vue> (selector: VueClass<R>): Wrapper<R>
+  get<R extends Vue> (selector: ComponentOptions<R>): Wrapper<R>
+  get (selector: FunctionalComponentOptions): Wrapper<Vue>
+  get (selector: string): Wrapper<Vue>
+  get (selector: RefSelector): Wrapper<Vue>
+  get (selector: NameSelector): Wrapper<Vue>
+
   find<R extends Vue> (selector: VueClass<R>): Wrapper<R>
   find<R extends Vue> (selector: ComponentOptions<R>): Wrapper<R>
   find (selector: FunctionalComponentOptions): Wrapper<Vue>

Diff for: 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 for: 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('<div/>')
+    const wrapper = mountingMethod(compiled)
+    expect(() => wrapper.get('.does-not-exist'))
+      .to.throw()
+      .with.property(
+        'message',
+        'Unable to find .does-not-exist within: <div></div>'
+      )
+  })
+  it('gets the element when element is found', () => {
+    const compiled = compileToFunctions('<div class="does-exist"><div>')
+    const wrapper = mountingMethod(compiled)
+    expect(wrapper.get('.does-exist')).to.be.an('object')
+  })
+})