wrapper.refs

Author: matt-oconnell

flow/wrapper.flow.js

@@ -15,8 +15,8 @@ declare interface BaseWrapper { // eslint-disable-line no-undef
     hasClass(className: string): boolean | void,
     hasProp(prop: string, value: string): boolean | void,
     hasStyle(style: string, value: string): boolean | void,
-    find(selector: Selector): Wrapper | void,
-    findAll(selector: Selector): WrapperArray | void,
+    find(selector: Selector | FindOptions): Wrapper | void,
+    findAll(selector: Selector | FindOptions): WrapperArray | void,
     html(): string | void,
     is(selector: Selector): boolean | void,
     isEmpty(): boolean | void,
@@ -36,3 +36,7 @@ declare type WrapperOptions = { // eslint-disable-line no-undef
     attachedToDocument: boolean,
     error?: string
 }
+
+declare type FindOptions = { // eslint-disable-line no-undef
+    ref: string,
+}

src/lib/find-matching-vnodes.js

@@ -0,0 +1,15 @@
+// @flow
+
+import { removeDuplicateNodes, findAllVNodes } from './vnode-utils'
+
+function nodeMatchesRef (node: VNode, refName: string): boolean {
+  return node.data && node.data.ref === refName
+}
+
+export default function findVNodesByRef (vNode: VNode, refName: string): Array<VNode> {
+  const nodes = findAllVNodes(vNode)
+  const refFilteredNodes = nodes.filter(node => nodeMatchesRef(node, refName))
+  // Only return refs defined on top-level VNode to provide the same behavior as selecting via vm.$ref.{someRefName}
+  const mainVNodeFilteredNodes = refFilteredNodes.filter(node => !!vNode.context.$refs[node.data.ref])
+  return removeDuplicateNodes(mainVNodeFilteredNodes)
+}

src/lib/find-vnodes-by-ref.js

@@ -0,0 +1,13 @@
+// @flow
+
+import { removeDuplicateNodes, findAllVNodes } from './vnode-utils'
+
+function nodeMatchesSelector (node: VNode, selector: string): boolean {
+  return node.elm && node.elm.getAttribute && node.elm.matches(selector)
+}
+
+export default function findVNodesBySelector (vNode: VNode, selector: string): Array<VNode> {
+  const nodes = findAllVNodes(vNode)
+  const filteredNodes = nodes.filter(node => nodeMatchesSelector(node, selector))
+  return removeDuplicateNodes(filteredNodes)
+}

src/lib/find-vnodes-by-selector.js

@@ -45,3 +45,26 @@ export function isValidSelector (selector: any): boolean {
 
   return isVueComponent(selector)
 }
+
+export function isValidFindOption (findOptions: any) {
+  if (typeof findOptions !== 'object') {
+    return false
+  }
+
+  if (findOptions === null) {
+    return false
+  }
+
+  const validFindKeys = ['ref']
+  const entries = Object.entries(findOptions)
+
+  if (!entries.length) {
+    return false
+  }
+
+  const isValid = entries.every(([key, value]) => {
+    return validFindKeys.includes(key) && typeof value === 'string'
+  })
+
+  return isValid
+}

src/lib/validators.js

@@ -0,0 +1,28 @@
+// @flow
+
+export function findAllVNodes (vnode: VNode, nodes: Array<VNode> = []): Array<VNode> {
+  nodes.push(vnode)
+
+  if (Array.isArray(vnode.children)) {
+    vnode.children.forEach((childVNode) => {
+      findAllVNodes(childVNode, nodes)
+    })
+  }
+
+  if (vnode.child) {
+    findAllVNodes(vnode.child._vnode, nodes)
+  }
+
+  return nodes
+}
+
+export function removeDuplicateNodes (vNodes: Array<VNode>): Array<VNode> {
+  const uniqueNodes = []
+  vNodes.forEach((vNode) => {
+    const exists = uniqueNodes.some(node => vNode.elm === node.elm)
+    if (!exists) {
+      uniqueNodes.push(vNode)
+    }
+  })
+  return uniqueNodes
+}

src/lib/vnode-utils.js

@@ -1,9 +1,10 @@
 // @flow
 
 import Vue from 'vue'
-import { isValidSelector } from '../lib/validators'
+import { isValidSelector, isVueComponent, isValidFindOption } from '../lib/validators'
 import findVueComponents, { vmCtorMatchesName } from '../lib/find-vue-components'
-import findMatchingVNodes from '../lib/find-matching-vnodes'
+import findVNodesBySelector from '../lib/find-vnodes-by-selector'
+import findVNodesByRef from '../lib/find-vnodes-by-ref'
 import VueWrapper from './vue-wrapper'
 import WrapperArray from './wrapper-array'
 import ErrorWrapper from './error-wrapper'
@@ -174,12 +175,13 @@ export default class Wrapper implements BaseWrapper {
   /**
    * Finds first node in tree of the current wrapper that matches the provided selector.
    */
-  find (selector: string): Wrapper | ErrorWrapper | VueWrapper {
-    if (!isValidSelector(selector)) {
-      throwError('wrapper.find() must be passed a valid CSS selector or a Vue constructor')
+  find (selector: Selector | FindOptions): Wrapper | ErrorWrapper | VueWrapper {
+    const isValidOptionObject = isValidFindOption(selector)
+    if (!isValidSelector(selector) && !isValidOptionObject) {
+      throwError('wrapper.find() must be passed a valid CSS selector, Vue constructor, or valid find option object')
     }
 
-    if (typeof selector === 'object') {
+    if (typeof selector === 'object' && isVueComponent(selector)) {
       if (!selector.name) {
         throwError('.find() requires component to have a name property')
       }
@@ -191,7 +193,18 @@ export default class Wrapper implements BaseWrapper {
       return new VueWrapper(components[0], this.options)
     }
 
-    const nodes = findMatchingVNodes(this.vnode, selector)
+    if (typeof selector === 'object' && isValidOptionObject) {
+      if (!this.isVueComponent) {
+        throwError('$ref selectors can only be used on Vue component wrappers')
+      }
+      const nodes = findVNodesByRef(this.vnode, selector.ref)
+      if (nodes.length === 0) {
+        return new ErrorWrapper(`ref="${selector.ref}"`)
+      }
+      return new Wrapper(nodes[0], this.update, this.options)
+    }
+
+    const nodes = findVNodesBySelector(this.vnode, selector)
 
     if (nodes.length === 0) {
       return new ErrorWrapper(selector)
@@ -202,12 +215,12 @@ export default class Wrapper implements BaseWrapper {
   /**
    * Finds node in tree of the current wrapper that matches the provided selector.
    */
-  findAll (selector: Selector): WrapperArray {
-    if (!isValidSelector(selector)) {
-      throwError('wrapper.findAll() must be passed a valid CSS selector or a Vue constructor')
+  findAll (selector: Selector | FindOptions): WrapperArray {
+    if (!isValidSelector(selector) && !isValidFindOption(selector)) {
+      throwError('wrapper.findAll() must be passed a valid CSS selector, Vue constructor, or valid find option object')
     }
 
-    if (typeof selector === 'object') {
+    if (typeof selector === 'object' && isVueComponent(selector)) {
       if (!selector.name) {
         throwError('.findAll() requires component to have a name property')
       }
@@ -216,11 +229,19 @@ export default class Wrapper implements BaseWrapper {
       return new WrapperArray(components.map(component => new VueWrapper(component, this.options)))
     }
 
+    if (typeof selector === 'object' && isValidFindOption(selector)) {
+      if (!this.isVueComponent) {
+        throwError('$ref selectors can only be used on Vue component wrappers')
+      }
+      const nodes = findVNodesByRef(this.vnode, selector.ref)
+      return new WrapperArray(nodes.map(node => new Wrapper(node, this.update, this.options)))
+    }
+
     function nodeMatchesSelector (node, selector) {
       return node.elm && node.elm.getAttribute && node.elm.matches(selector)
     }
 
-    const nodes = findMatchingVNodes(this.vnode, selector)
+    const nodes = findVNodesBySelector(this.vnode, selector)
     const matchingNodes = nodes.filter(node => nodeMatchesSelector(node, selector))
 
     return new WrapperArray(matchingNodes.map(node => new Wrapper(node, this.update, this.options)))

src/wrappers/wrapper.js

@@ -1,7 +1,7 @@
 <template>
   <div>
     <span>
-      <child-component />
+      <child-component ref="child"/>
     </span>
   </div>
 </template>

test/resources/components/component-with-child.vue

@@ -1,6 +1,6 @@
 <template>
   <div>
-    <AComponent v-for="item in items" :key="item.id" />
+    <AComponent v-for="item in items" :key="item.id" ref="item"/>
   </div>
 </template>
 

test/resources/components/component-with-v-for.vue

@@ -75,7 +75,7 @@ describe('find', () => {
   it('throws an error when passed an invalid DOM selector', () => {
     const compiled = compileToFunctions('<div><a href="/"></a></div>')
     const wrapper = mount(compiled)
-    const message = '[vue-test-utils]: wrapper.find() must be passed a valid CSS selector or a Vue constructor'
+    const message = '[vue-test-utils]: wrapper.find() must be passed a valid CSS selector, Vue constructor, or valid find option object'
     const fn = () => wrapper.find('[href=&6"/"]')
     expect(fn).to.throw().with.property('message', message)
   })
@@ -103,7 +103,7 @@ describe('find', () => {
     expect(wrapper.find(Component)).to.be.instanceOf(Wrapper)
   })
 
-  it('returns correct number of Vue Wrapper when component has a v-for', () => {
+  it('returns correct number of Vue Wrappers when component has a v-for', () => {
     const items = [{ id: 1 }, { id: 2 }, { id: 3 }]
     const wrapper = mount(ComponentWithVFor, { propsData: { items }})
     expect(wrapper.find(Component)).to.be.instanceOf(Wrapper)
@@ -144,13 +144,46 @@ describe('find', () => {
     expect(error.selector).to.equal('Component')
   })
 
+  it('returns Wrapper of elements matching the ref in options object', () => {
+    const compiled = compileToFunctions('<div><p ref="foo"></p></div>')
+    const wrapper = mount(compiled)
+    expect(wrapper.find({ ref: 'foo' })).to.be.instanceOf(Wrapper)
+  })
+
+  it('returns Wrapper of Vue Components matching the ref in options object', () => {
+    const wrapper = mount(ComponentWithChild)
+    expect(wrapper.find({ ref: 'child' })).to.be.instanceOf(Wrapper)
+  })
+
+  it('throws an error when ref selector is called on a wrapper that is not a Vue component', () => {
+    const compiled = compileToFunctions('<div><a href="/"></a></div>')
+    const wrapper = mount(compiled)
+    const a = wrapper.find('a')
+    const message = '[vue-test-utils]: $ref selectors can only be used on Vue component wrappers'
+    const fn = () => a.find({ ref: 'foo' })
+    expect(fn).to.throw().with.property('message', message)
+  })
+
+  it('returns Wrapper matching ref selector in options object passed if nested in a transition', () => {
+    const compiled = compileToFunctions('<transition><div ref="foo"/></transition>')
+    const wrapper = mount(compiled)
+    expect(wrapper.find({ ref: 'foo' })).to.be.instanceOf(Wrapper)
+  })
+
+  it('returns empty Wrapper with error if no nodes are found via ref in options object', () => {
+    const wrapper = mount(Component)
+    const error = wrapper.find({ ref: 'foo' })
+    expect(error).to.be.instanceOf(ErrorWrapper)
+    expect(error.selector).to.equal('ref="foo"')
+  })
+
   it('throws an error if selector is not a valid selector', () => {
     const wrapper = mount(Component)
     const invalidSelectors = [
-      undefined, null, NaN, 0, 2, true, false, () => {}, {}, { name: undefined }, []
+      undefined, null, NaN, 0, 2, true, false, () => {}, {}, { name: undefined }, { ref: 'foo', nope: true }, []
     ]
     invalidSelectors.forEach((invalidSelector) => {
-      const message = '[vue-test-utils]: wrapper.find() must be passed a valid CSS selector or a Vue constructor'
+      const message = '[vue-test-utils]: wrapper.find() must be passed a valid CSS selector, Vue constructor, or valid find option object'
       const fn = () => wrapper.find(invalidSelector)
       expect(fn).to.throw().with.property('message', message)
     })

test/unit/specs/mount/Wrapper/find.spec.js

@@ -82,7 +82,7 @@ describe('findAll', () => {
   it('throws an error when passed an invalid DOM selector', () => {
     const compiled = compileToFunctions('<div><a href="/"></a></div>')
     const wrapper = mount(compiled)
-    const message = '[vue-test-utils]: wrapper.findAll() must be passed a valid CSS selector or a Vue constructor'
+    const message = '[vue-test-utils]: wrapper.findAll() must be passed a valid CSS selector, Vue constructor, or valid find option object'
     const fn = () => wrapper.findAll('[href=&6"/"]')
     expect(fn).to.throw().with.property('message', message)
   })
@@ -161,13 +161,53 @@ describe('findAll', () => {
     expect(preArray.wrappers).to.deep.equal([])
   })
 
+  it('returns an array of Wrapper of elements matching the ref in options object', () => {
+    const compiled = compileToFunctions('<div><div ref="foo" /></div>')
+    const wrapper = mount(compiled)
+    const fooArr = wrapper.findAll({ ref: 'foo' })
+    expect(fooArr).to.be.instanceOf(WrapperArray)
+    expect(fooArr.length).to.equal(1)
+  })
+
+  it('throws an error when ref selector is called on a wrapper that is not a Vue component', () => {
+    const compiled = compileToFunctions('<div><a href="/"></a></div>')
+    const wrapper = mount(compiled)
+    const a = wrapper.find('a')
+    const message = '[vue-test-utils]: $ref selectors can only be used on Vue component wrappers'
+    const fn = () => a.findAll({ ref: 'foo' })
+    expect(fn).to.throw().with.property('message', message)
+  })
+
+  it('returns an array of Wrapper of elements matching the ref in options object if they are nested in a transition', () => {
+    const compiled = compileToFunctions('<transition><div ref="foo" /></transition>')
+    const wrapper = mount(compiled)
+    const divArr = wrapper.findAll({ ref: 'foo' })
+    expect(divArr).to.be.instanceOf(WrapperArray)
+    expect(divArr.length).to.equal(1)
+  })
+
+  it('returns correct number of Vue Wrapper when component has a v-for and matches the ref in options object', () => {
+    const items = [{ id: 1 }, { id: 2 }, { id: 3 }]
+    const wrapper = mount(ComponentWithVFor, { propsData: { items }})
+    const componentArray = wrapper.findAll({ ref: 'item' })
+    expect(componentArray).to.be.instanceOf(WrapperArray)
+    expect(componentArray.length).to.equal(items.length)
+  })
+
+  it('returns VueWrapper with length 0 if no nodes matching the ref in options object are found', () => {
+    const wrapper = mount(Component)
+    const preArray = wrapper.findAll({ ref: 'foo' })
+    expect(preArray.length).to.equal(0)
+    expect(preArray.wrappers).to.deep.equal([])
+  })
+
   it('throws an error if selector is not a valid selector', () => {
     const wrapper = mount(Component)
     const invalidSelectors = [
-      undefined, null, NaN, 0, 2, true, false, () => {}, {}, { name: undefined }, []
+      undefined, null, NaN, 0, 2, true, false, () => {}, {}, { name: undefined }, { ref: 'foo', nope: true }, []
     ]
     invalidSelectors.forEach((invalidSelector) => {
-      const message = '[vue-test-utils]: wrapper.findAll() must be passed a valid CSS selector or a Vue constructor'
+      const message = '[vue-test-utils]: wrapper.findAll() must be passed a valid CSS selector, Vue constructor, or valid find option object'
       const fn = () => wrapper.findAll(invalidSelector)
       expect(fn).to.throw().with.property('message', message)
     })