Rethink find; simplify, or split find into find and findComponent

[lmiller1990]

Following up this discussion here: #1490. Read that for context!

I think we should consider splitting find into two methods.

• find. This will only work for DOM nodes. It will use the querySelector syntax.
• findComponent. This can find a Vue component. By ref, name, etc.

Usage

• ✅ find("#foo")
• ✅ findComponent(Bar)
• ✅ findComponent(Bar).findComponent(Foo)
• ❌ findComponent(Bar).find("#foo")
• ❌ find("#foo").findComponent(Bar)

The reason I think we should split these is they are really different. One is searching the DOM for nodes; the other is searching for vnodes in Vue's virtual dom. I think this would remove a lot of caveats and simplify things.

I think not allowing them to mix will make tests more simple. Simple is good. findComponent tells the reader you are interested in the component; find shows you are interested in the DOM and what is rendered.

We can either make this change now (with a deprecation warning) to be removed in v1 (hopefully soon). Alternatively, we keep this current behavior, and for v2 (which will be Vue 3 support) we change to this new API.

As an aside, I would be in favor of making findComponent more simple - currently you can find by name/ref/component... can we just pick one? Rather than go with the classic Perl motto "There is more than one way to do things" I much prefer the Python motto "There should be one-- and preferably only one --obvious way to do it". Anyway, let's focus on the splitting of the APIs for now.

[unclejustin]

I really like the idea of having one good way to select something as long as you have some way to pass in optional arguments. Like: wrapper.findComponent(Component, { ref: 'componentOne' }). But it always expects to look for an actual Component.

[Stoom]

Would using ref require all components to have a defined ref attribute? If so I'd be for component name or component.

[lmiller1990]

@Stoom I don't know if I understand your question. find({ ref: 'blah' }) looks for a component with a ref defined by the user.

@unclejustin Having one way to select things with optional arguments isn't one way... it's one way + the amount of arguments you provide. Is there any use case that can't be solved by find("#foo") and find(Component)? By use case, I mean an actual test you can't write without finding by ref. One of my personal goals for any library/app I build is to provide the minimal API needed to solve all the use cases.

If you need to use ref, you are most likely testing implementation details, which is a bad practice. We should not encourage bad practices. But there might be some legitimate use cases I don't know about.

[Stoom]

Ok, that's what I was thinking. If we do find my component then you could also do find my name by doing something like { name: 'foobar' } I think. This comes from working on the stubbing.

[lmiller1990]

name is another option. The problem I see with name over component is finding third party components that may not have name.

Now I think about it, I wonder if we should consider deprecating finding components entirely (ref/name/instance) and only support querySelector syntax.

As convenient as it can be to find by component, I personally prefer libraries that are more simple with an API that consistently works like you expect for all use cases. Sometimes less is more.

Here are some examples that do not work in beta that come up a lot:

• finding functional components (no instance, no name)
• finding many Vuetify components (very common use case). Since they are built by composing components, or they are functional, many of those cannot be found by ref or name or instance. Discussed here: Some stubbed Vuetify components can't be found with find wrapper method #1272 and many other issues

[JessicaSachs]

I'm not in favor of the proposal as it violates our principle of not letting implementation details into our tests. If I refactor my component to use a <v-sheet> instead of a div, my tests will break because I'm suddenly looking for a component instead of a dom element.

IMHO, the best solution would be to support querySelector syntax and ask users to use data-testid on their components.

This will normalize finding across DOM nodes and components. Additionally, data-testid is resilient as a selector strategy to many kinds of refactors.

[lmiller1990]

I agree with @JessicaSachs - I exclusively use find("[data-test='blah']") for this reason. The way I test Vuetify is like this:

<template>
  <v-btn data-test="go">Go</v-btn>
</template>

wrapper.find('[data-test="go]').find('button').trigger('click')

[souldzin]

The reason I think we should split these is they are really different. One is searching the DOM for nodes; the other is searching for vnodes in Vue's virtual dom.

IMHO, as a client of .find I don't really care how it's searching. I just want it to return me a wrapper based on the query I'm giving it.

Okay @souldzin, so why do you like keeping the single .find method?

• Simplicity. This might be a matter of preference, but IMO, it's really nice that there is just one method for Query => Wrapper. It sounds like there are different implementation concerns based on the parameters, but that is an implementation detail and shouldn't be a responsibility of the client.
• Developer expectations. I imagine that part of vue-test-utils API is inspired by enzyme. Keeping this parity would be really nice.
• Ease of test refactoring. Let's say I have a test which has abstracted some commonly used selector in a constant:

const FOO_QUERY = '.foo';

it('...', () => {
  wrapper.find(FOO_QUERY)
  // ...
});

// etc.

Currently, if I look at my code and I realize that we actually have a ref we can use, I can easily update my tests with a single line and I'm done:

- const FOO_QUERY = '.foo';
+ const FOO_QUERY = { ref: 'foo' };

If looking up by component required me to call a whole other method, then I'd have to change every reference to FOO_SELECTOR... Also, it'd make it really hard to write a helper like:

const findFooChild = (sel) => wrapper.find(Foo).find(sel);

It's worth considering the robustness we'd be losing.

But!

If vue-test-utils blows up with:

wrapper.find('.dom-element').find(FooComponent)

Then I'd say vue-test-utils has a 🐛

I much prefer the Python motto "There should be one-- and preferably only one --obvious way to do it".

I'd argue that this supports having a single .find method which accepts various parameters rather than having two methods .find and .findComponent 🤔

[lmiller1990]

Great points above @souldzin. Here is my thoughts:

IMHO, as a client of .find I don't really care how it's searching. I just want it to return me a wrapper based on the query I'm giving it.

I agree with this. The user should not need to think about how things work. They have better things to do, like build apps and deliver value.

Developer expectations. I imagine that part of vue-test-utils API is inspired by enzyme. Keeping this parity would be really nice.

Strong disagree here. While VTU may seem Enzyme inspired, it's really a relic of the time it was created - Enzyme was basically the only testing lib for components out there. Since then, the React world moved on to testing-library from what I can see, ditching things like find(Comp) and shallow. testing-library is recommended in the official React docs, and included in create-react-app by default. We have no need to follow what Enzyme does, although I have a lot of respect for the creators of Enzyme, they are very smart.

If looking up by component required me to call a whole other method, then I'd have to change every reference to FOO_SELECTOR...

If your tests broke when you refactored your code, this is a big red flag - yours tests are fragile. If you didn't change the public API and behavior, why are the tests failing? If you need to select a specific element, the solution is to use a dedicated data-testid selector.

I'd argue that this supports having a single .find method which accepts various parameters rather than having two methods .find and .findComponent 🤔

I do agree two methods is more complex than one.

[JessicaSachs]

My vote is to reduce find's support to querySelectors only. I also think @souldzin is right that there is an existing bug.

I also only want one method.. let's stick to find.

Why do we want to support querySelectors instead of component references?

Because the DOM is the universal language for querying the rendered output. Maintaining another abstraction gets particularly hairy when we lose the component reference in shallowMount or with stubs.

[souldzin]

Thanks for the responsiveness @lmiller1990! Also thanks for creating the discussion 😄

Strong disagree here. While VTU may seem Enzyme inspired, it's really a relic of the time it was created

Thanks for this info! I may have inadvertently revealed when the last time I wrote React test code was 😅

If your tests broke when you refactored your code, this is a big red flag - yours tests are fragile. If you didn't change the public API and behavior, why are the tests failing?

Right. Sorry if this example was misleading.

The idea is about maintaining existing test code. It's much easier for me to write domain-specific test helpers when I don't have to be worried about this function split.

My vote is to reduce find's support to querySelectors only.

@JessicaSachs This is really interesting 🤔

At my organization, we do a lot of shallowMount unit testing (for better or for worse) and IMO it's really nice to expect(wrapper.find(FooComponent).props()).toEqual(..) so that I know this is where my current unit test can stop and the unit tests for FooComponent can begin.

[unclejustin]

Also, thanks for the discussion! The more I try and come up with some rando scenario for using refs with a Component selector the more I can see a way around it i.e. data-testid which is arguably the same amount of work as ref="whatever". I think as long as find works consistently and obviously I'm going to be happy 😅 Although I'm not super pumped about all the broken tests my organization will have to fix 😬