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') + }) +})