Improving `find` and `findAll` API for asserting presence of stubs

[lmiller1990]

What problem does this feature solve?

If I want to assert a stub was rendered, I have to do the following:

Demo component:

<!-- component.vue -->
<template>
  <div>
    <Hello />
  </div>
</div>

I want to assert Hello is rendered one time.

// test
const HelloStub = {
  'name': "Hello"
  render: h => h('div')
}

const wrapper = shallow(Component}

expect(wrapper.find(HelloStub).exists()).toBe(true)

I always need to create a minimal:

const HelloStub = { name: "Hello", render: h => h("div") }

That is an extra (correctly formatted) four lines - over half the test.

My current workflow simply defines a helper:

const createStub = name => ({ name, render: h => h("div") })

Which adds an extra line for the import, and another for create the stub in every test. 1/3 of the test is, in my opinion, unnecessary boilerplate setup.

What does the proposed API look like?

I find myself defining and importing the above helper function in every project, and importing it to many tests. One idea would be to add this method to vue-test-utils. This goes against one design goal, "keeping the API surface small and straightforward". However, it supports one other goal, "The problem should also be common enough to justify the addition". I think asserting components are rendered is done is many tests.

I had two proposed APIs:

1. include helper in vue-test-utils

import { shallowMount, createStub } from "@vue/test-utils" 

const Hello = createStub("Hello")
const wrapper = shallowMount(Component)

expect(Component.find(Hello).exists()).toBe(true)

2. passing a string to find, and findAll checks for stubs

import { shallowMount } from "@vue/test-utils" 

const wrapper = shallowMount(Component)

expect(Component.find("Hello").exists()).toBe(true)

Since Vue components cannot clash with existing HTML elements, it is easy to know when find receives a HTML element like <div>, and when it's looking for an actual component. In the case of an a actual component, find should look for stubs instead of html elements.

I like the second solution more because it leads to more compact code, and doesn't change overall API very much.

I am happy to implement either.

[eddyerburgh]

I think a createStub utility would probably be useful.

The second option is a good idea. I think users would find this more intuitive than using a component as a selector.

You could match a vNode using the tag property in the componentOptions object.

Although in your example you can assert that Hello is rendered using the component as a selector:

const wrapper = mount(Component)
wrapper.find(Hello)

I'm happy to review PRs for either feature.

[lmiller1990]

Regarding the second option, I noticed we can do:

find({ name: 'blah })

But I would still rather do

find("Blah")

I have a decent implementation (using tag) but I noticed if we just pass a string to find it will first interpret it as a HTMLElement, like div.

So, I think we would need to update isDomElement validator to not only check if the passed selector is a String, but also a valid element. The best option might be something like this library. Or should we avoid pulling in more deps? @eddyerburgh

Alternatively, we could not add this, and stick with { name } and createStub.

[eddyerburgh]

@lmiller1990 Yes you can pull that library in 👍

The name selector only works with named components, but we can use the tag selector for unnamed components.

Can you add tests for unnamed components registered with different names and casings. There are utils in shared/util for converting between casing.

I'm excited about this PR, it's definitely going to improve the dev experience 😄

[38elements]

@eddyerburgh
@lmiller1990

I think that {name: 'foo'} is more explicit and easier to read.
I object to changing name selector.

[eddyerburgh]

We aren't changing the name selector, we'll use the tagname instead.

const SomeComp = {
   name: 'a-name'
}

const TestComponent = {
  template: '<div><some-comp /></div>',
  components: {SomeComp}
}

const wrapper = mount(TestComponent)
wrapper.find('a-name').exists() // false
wrapper.find('some-comp').exists() // true
wrapper.find('SomeComp').exists() // false
wrapper.find({name: 'a-name'}).exists() // true

[38elements]

@eddyerburgh
@lmiller1990

I am sorry.
I misunderstood it.

[lmiller1990]

There is an open PR to add this API:

wrapper = shallowMount(ComponentWithChild)

expect(wrapper.find("child-component").exists()).toBe(true)

Which lets users do find("tag") rather than find({ name }) or find(Component).

There is some objection (see #692 and it's previous PR, #681 ). Here is my thoughts why I like this better than the existing APIs:

1. name API: ({ name: ... }) doesn't feel very intuitive. We allow querySelector like syntax for find, ({ name }) doesn't conform to this. Also, name is not always the same as the tag, and has nothing to do with what is actually rendered, which is what find is used to assert.

2. component API: find(Component) is okay, but I don't really like having to import every component I want to find to every test. It's just a bunch of boilerplate. It's easy enough to make shallowMount and mount global, in the same way describe is, but this is not an option for components.

The least amount of typing and reduced boilerplate is find({ name }), but I don't like this that much. If the name is different for the component (it shouldn't be, but it happens) I have to go and find the .vue file, and check the name. Then if someone else looks at the test, they will likely have the same thought (we are looking for ({ name: foo-component }), but actually this component only renders <bar-component>).

We can still continue to allow for { name: 'foo' } to be used, as well.

I don't want to drag this out for too long, if people have too strong an opinion we can just drop it. That's my thoughts.