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