chore: add definitions for findComponent and findAllComponents (#1530)

* chore: add definitions for findComponent and findAllComponents

* docs: Update docs/api/wrapper/findAllComponents.md

Co-authored-by: Adrià Fontcuberta <afontcu@gmail.com>

Co-authored-by: Adrià Fontcuberta <afontcu@gmail.com>

Author: lmiller1990

docs/api/wrapper/README.md

@@ -37,6 +37,8 @@ A `Wrapper` is an object that contains a mounted component or vnode and methods
 !!!include(docs/api/wrapper/exists.md)!!!
 !!!include(docs/api/wrapper/find.md)!!!
 !!!include(docs/api/wrapper/findAll.md)!!!
+!!!include(docs/api/wrapper/findComponent.md)!!!
+!!!include(docs/api/wrapper/findAllComponents.md)!!!
 !!!include(docs/api/wrapper/html.md)!!!
 !!!include(docs/api/wrapper/get.md)!!!
 !!!include(docs/api/wrapper/is.md)!!!

docs/api/wrapper/find.md

@@ -2,11 +2,11 @@
 
 Returns `Wrapper` of first DOM node or Vue component matching selector.
 
-Use any valid [selector](../selectors.md).
+Use any valid DOM selector (uses `querySelector` syntax).
 
 - **Arguments:**
 
-  - `{string|Component} selector`
+  - `{string} selector`
 
 - **Returns:** `{Wrapper}`
 
@@ -20,34 +20,19 @@ import Bar from './Bar.vue'
 const wrapper = mount(Foo)
 
 const div = wrapper.find('div')
-expect(div.is('div')).toBe(true)
+expect(div.exists()).toBe(true)
 
-const bar = wrapper.find(Bar)
-expect(bar.is(Bar)).toBe(true)
-
-const barByName = wrapper.find({ name: 'bar' })
-expect(barByName.is(Bar)).toBe(true)
-
-const fooRef = wrapper.find({ ref: 'foo' })
-expect(fooRef.is(Foo)).toBe(true)
+const byId = wrapper.find('#bar')
+expect(byId.element.id).toBe('bar')
 ```
 
 - **Note:**
 
-  - When chaining `find` calls together, only DOM selectors can be used
+  - You may chain `find` calls together:
 
 ```js
 let button
 
-// Will throw an error
-button = wrapper.find({ ref: 'testButton' })
-expect(button.find(Icon).exists()).toBe(true)
-
-// Will throw an error
-button = wrapper.find({ ref: 'testButton' })
-expect(button.find({ name: 'icon' }).exists()).toBe(true)
-
-// Will work as expected
 button = wrapper.find({ ref: 'testButton' })
 expect(button.find('.icon').exists()).toBe(true)
 ```

docs/api/wrapper/findAllComponents.md

@@ -0,0 +1,23 @@
+## findAllComponents
+
+Returns a [`WrapperArray`](../wrapper-array/) of all matching Vue components.
+
+- **Arguments:**
+
+  - `{Component|ref|name} selector`
+
+- **Returns:** `{WrapperArray}`
+
+- **Example:**
+
+```js
+import { mount } from '@vue/test-utils'
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
+
+const wrapper = mount(Foo)
+const bar = wrapper.findAllComponents(Bar).at(0)
+expect(bar.exists()).toBeTruthy()
+const bars = wrapper.findAllComponents(Bar)
+expect(bar).toHaveLength(1)
+```

docs/api/wrapper/findComponent.md

@@ -0,0 +1,26 @@
+## findComponent
+
+Returns `Wrapper` of first matching Vue component.
+
+- **Arguments:**
+
+  - `{Component|ref|name} selector`
+
+- **Returns:** `{Wrapper}`
+
+- **Example:**
+
+```js
+import { mount } from '@vue/test-utils'
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
+
+const wrapper = mount(Foo)
+
+const bar = wrapper.findComponent(Bar) //=> finds Bar by component instance
+expect(bar.exists()).toBe(true)
+const barByName = wrapper.findComponent({ name: 'bar' }) //=> finds Bar by `name`
+expect(barByName.exists()).toBe(true)
+const barRef = wrapper.findComponent({ ref: 'bar' }) //=> finds Bar by `ref`
+expect(barRef.exists()).toBe(true)
+```

packages/test-utils/types/index.d.ts

@@ -55,6 +55,7 @@ interface BaseWrapper {
   classes(className: string): boolean
   props(): { [name: string]: any }
   props(key: string): any | void
+  overview(): void
 
   is (selector: Selector): boolean
   isEmpty (): boolean
@@ -99,6 +100,18 @@ export interface Wrapper<V extends Vue | null> extends BaseWrapper {
   findAll (selector: RefSelector): WrapperArray<Vue>
   findAll (selector: NameSelector): WrapperArray<Vue>
 
+  findComponent<R extends Vue> (selector: VueClass<R>): Wrapper<R>
+  findComponent<R extends Vue> (selector: ComponentOptions<R>): Wrapper<R>
+  findComponent<Props = DefaultProps, PropDefs = PropsDefinition<Props>>(selector: FunctionalComponentOptions<Props, PropDefs>): Wrapper<Vue>
+  findComponent (selector: RefSelector): Wrapper<Vue>
+  findComponent (selector: NameSelector): Wrapper<Vue>
+
+  findAllComponents<R extends Vue> (selector: VueClass<R>): WrapperArray<R>
+  findAllComponents<R extends Vue> (selector: ComponentOptions<R>): WrapperArray<R>
+  findAllComponents<Props = DefaultProps, PropDefs = PropsDefinition<Props>>(selector: FunctionalComponentOptions<Props, PropDefs>): WrapperArray<Vue>
+  findAllComponents(selector: RefSelector): WrapperArray<Vue>
+  findAllComponents(selector: NameSelector): WrapperArray<Vue>
+
   html (): string
   text (): string
   name (): string
@@ -123,6 +136,7 @@ export interface WrapperArray<V extends Vue> extends BaseWrapper {
 }
 
 interface WrapperOptions {
+  attachTo?: Element | string
   attachedToDocument?: boolean
 }
 

packages/test-utils/types/test/wrapper.ts

@@ -36,6 +36,15 @@ wrapper.trigger('mousedown.enter', {
   button: 0
 })
 
+wrapper.findAllComponents({ name: 'foo' })
+wrapper.findComponent({ name: 'foo' })
+
+wrapper.findAllComponents({ ref: 'foo' })
+wrapper.findComponent({ ref: 'foo' })
+
+wrapper.findAllComponents(ClassComponent)
+wrapper.findComponent(ClassComponent)
+
 /**
  * Tests for Wrapper API
  */

packages/test-utils/types/tsconfig.json

@@ -1,7 +1,8 @@
 {
   "compilerOptions": {
     "lib": ["es2015", "es2017", "dom"],
-    "module": "es2015",
+    "module": "esnext",
+    "target": "ES2017",
     "moduleResolution": "node",
     "strict": true,
     "noEmit": true,