Design / Roadmap

[yyx990803]

Following the forum thread, using this issue to kick off work on an official unit testing utility lib. We are planning to built on top of @eddyerburgh 's Avoriaz, since it seems to be the most mature one currently, and Edd has kindly offered to work on it. Of course, we would also like to pull in ideas from other community solutions and make this a collaborative effort, so I'm pinging some community members that might also be interested in contributing here: @callumacrae, @asselin, @jackmellis, @codebryo, @BosNaufal.

I think the first step is outlining what feature set we are aiming for - here's some high level goals:

• Two rendering modes: deep, real DOM vs. shallow, virtual DOM
• Both modes with ideally the same traversal / event simulation / assertion API
• Ability to easily stub component assets / router / store
• Ability to output a serialized snapshot for Jest snapshot testing
• Test runner agnostic

in the meanwhile, feel free to provide general feedback on some of the needs you've run into while unit testing Vue.

Also @vuejs/collaborators for any potential input.

[eddyerburgh]

The main question for me is should the test utils use a wrapper API, augmented API or simple API?

Wrapper API

const wrapper = mount(Component)
// Access vm
wrapper.vm.someMethod()
// Helper methods
wrapper.find('div')

Augmented API

const augmentedVm = mount(Component)
// Access vm
augmentedVm.someMethod()
// Helper methods
augmentedVm.$find('div')

Simple API

// Access vm
getMountedVm(Component)
// Helper methods
findElement('div', Component)

avoriaz uses the wrapper API. Personally I think it's the best API for this library - it avoids possible collisions that can occur with the augmented API and produces readable and chainable code.

What are people thoughts?

[yyx990803]

@eddyerburgh I prefer wrapper. Simple API can be tedious to import all the methods.

[HerringtonDarkholme]

Thank @eddyerburgh 's great library! I have read avoriaz' doc and it is well done.

Another field worth testing is the events a component emits. For example, a custom input component will likely emit an update event.

It is reasonable for a user to expect utility for testing custom event in the standard toolkit.

[eddyerburgh]

@HerringtonDarkholme Good idea. What would the API look like for that? wrapper.didEmit('update')?

On another note. If we add a find method - should find return an array of wrappers, or a container class?

A container class could default to the first item:

// Array
wrapper.find('div')[0].dispatch('click')
// Container
wrapper.find('div').dispatch('click')

And throw an error message if no element is found:

// Array
wrapper.find('div')[0].is('div') // throws Uncaught TypeError: Cannot read property 'is' of undefined
// Container
wrapper.find('div').is('div') // throws Error, no element matching tag div was found

The downside to a container is it needs a custom API to access wrappers at different indices.

// Array
wrapper.find('div')[1].is('div')
// Container
wrapper.find('div').at(1).is('div')

@pearofducks suggested having two find methods:

wrapper.find('div') - returns the first wrapper found, like querySelector
wrapper.findAll('div') - returns an array of wrappers, like querySelectorAll

What do people think?

[yyx990803]

@eddyerburgh can't the returned wrapper behave like jQuery collections? They have methods but are somewhat array-like (can be accessed via indices and even have iteration methods). That said, .at(1) isn't that bad.

[HerringtonDarkholme]

@eddyerburgh call me old school, but I still feel that jQuery is the most convenient dom traversal library.

For wrapper.find('.my-element').is('div'), I would expect it means "for all elements with class my-element, they are HTMLDivElement". For wrapper.find('div').dispatch('click'), I would expect click events are dispatched to all divs.

That means, any predicate or method is applied on all elements in the collection. If the user want one specific element to test they can simply use at(index). Also, filter or some, like those utility functions in underscore, can be helpful.

What do you think?

[eddyerburgh]

@yyx990803 Yes, it could return an object with properties 0,1,2 etc. But you will get type errors if a wrapper doesn't exist at an index:

wrapper.find('div')[3].find('p') // throws Uncaught TypeError: Cannot read property 'is' of undefined

If we used a method like at to access the wrapper, we could throw a custom error message

wrapper.find('div').at(3).find('p') // throws No div tag exists at index 3

It would be nice to throw as many custom error messages as possible. But I'm not sure if it justifies having a more complicated API.

@HerringtonDarkholme I hadn't considered treating the wrapper like that, but it could definitely work.

We should go with an API that's most natural for users. I think a lot of users will be familiar with the jQuery API, so maybe we should use a similar one as you suggest.

[jackmellis]

I get the feeling I'm the only person who doesn't do a lot of DOM traversal in their Unit Tests!

Most of my tests focus around the output of computed properties and methods using different data/prop values. I would leave checking the html layout of my page down to integration testing. Is this not how people test their Vue components?

Personally this is where I feel the wrapper API adds one-too-many layers between the user and the code-under-test. Is there some way we could either integrate or separate these two areas?

On top of the above list (which is all very sensible stuff) I would add the following to my wishlist:

• Be able to set data and prop values after mounting.
• Be able to Vue.use(plugin) without it polluting the global environment and leaking between tests. Some sort of isolated Vue constructor perhaps?
• Be able to mock the behaviour of a child component (so you don't have to use the full component, but you can emit events or render an <input> element)

I like the idea of just rendering to the virtual dom (but it still be explorable). But would this cause issues with components that do this.$el.querySelector(..) etc. ?

[znck]

@jackmellis This is interesting. Add ability to mock/inject methods, vuex store & lifecycle hooks to my wishlist.

[yyx990803]

@eddyerburgh yeah, I think a jQuery-like-object would be natural for most users, but you make a good point about [1] vs. .at(1) - I'm actually leaning towards .at(1) because of the error handling aspect.

@jackmellis good points - with the wrapper API you still have access to the actual vm inside though, so you can just use the wrapper API for stubbing purposes.

[eddyerburgh]

I've made a draft API to get some ideas down - https://github.com/eddyerburgh/vue-test-utils-proposal/blob/master/API.md

[HerringtonDarkholme]

@eddyerburgh Great! I like the consistency of is, did, has prefix to indicate they are assertion method!

I have several questions:

1. the slot option in mount and shallow seems to accept a ComponentOption. But in VueJS runtime slot contains an array of VNode. Does it mean vue-test-util will inflate option to vnode? Or should we change the slot option to accept VNode instead?

2. It seems global is a little bit confusing to me. The doc refers global as Vue.globalMethod. $route is called instance method. Maybe another word like interceptis better? (inject is already used in VueJS)

3. provide/inject is an advanced feature but also desirable here. A provide option must be useful.

4. didEmit returns a boolean. But sometimes we also need to test event's payload. So returning the event might be better?

[codebryo]

@jackmellis I actually like to do unit tests with rendering. Tools like Jest that support a snapshot feature are great for checking the output.

@eddyerburgh when mentioning jQuery, a thing that I felt was most useful and a big win for jquerys popularity is sizzle. What about leveraging sizzle for finding so people can so things like div:first and stuff? Besides that, the container method seems a little nicer as it could be extended with more functionality longterm.

API:
I like the cleaner mount approach of the proposal as this allows for a lot of flexibility.
Regarding the didEmit event, I would also add a function to test the payload, so it could be a second method didEmitWith for example.
The more methods we can provide, that people can even guess when working with the better.

[codebryo]

Regarding setProps - https://github.com/eddyerburgh/vue-test-utils-proposal/blob/master/API.md#setpropsprops

It's always hard to make the right call on this kind of things. For one, it would probably fit a lot of cases that it automatically updates but sometimes it's maybe desired to not update for some reason, then it would help to have it manually.

So if the workflow would look like this:

wrapper.setProps({some: 'data'}).update()

I would prefer it as it leaves all control up to the user and while testing code, the more control you have over things the better.