feat: export createWrapper and add createWrapperArray functions

[Toilal]

In some use case, it can be handy to manually create Wrapper and WrapperArray instances.

For example, you can find elements with findAll method, then filter them manually with wrappers property and Array.filter method, and finally create a new filtered WrapperArray instance.

const wrapper = mount(SomeComponent)
const filteredSubComponents = createWrapperArray(wrapper.findAll(SubComponent).wrappers.filter(w => !!w.vm.v))
...

[emileber]

Could we export the types as well? Wrapper and WrapperArray

[eddyerburgh]

@emileber we could definitely export the types, would you like to make a PR?

Personally I'm hesitant to export these methods. I appreciate it could be useful to create a wrapper array for some users, but it's a low-level function. Most users won't be aware of how to create WrapperArrays, and I don't think we should make them aware.

We only expose a few methods as methods to use:

• mount
• shallow
• createLocalVue

(We also expose components, but they aren't featured in the top-level API in the docs).

I feel like createWrapper and createWrapperArray add a lot of noise, for a niche use-case.

That's my thoughts. If others feel like this is a really valuable feature then we could add, but I'm against adding it to the API.

[Toilal]

By exporting types, do you mean exporting classes ? Because types are already exported for TypeScript users.

If classes Wrapper and WrapperArray are exported it will be just same as exporting createArray and createWrapperArray, but user will have to use new keyword and constructor parameters are less obvious than those factory methods.

But anyway, instead of this pull request, would you consider adding a filtering feature on all methods involving a selector (find/findAll/...) by adding an optional predicate function parameter ? It would really help for my use case (filtering out non-visible elements: #327)

[Toilal]

and maybe a filter method on WrapperArray ?

const wrapper = mount(SomeComponent)
const filteredSubComponents = wrapper.findAll(SubComponent).filter(w => !!w.vm.v)

[38elements]

How about changing wrapperArray.length from a fixed value to getter ?

Currently, wrapperArray.length is a fixed value.

vue-test-utils/src/wrappers/wrapper-array.js

Lines 7 to 14 in fce6e6e

	export default class WrapperArray implements BaseWrapper {
	wrappers: Array<Wrapper | VueWrapper>;
	length: number;
	constructor (wrappers: Array<Wrapper | VueWrapper>) {
	this.wrappers = wrappers || []
	this.length = this.wrappers.length
	}

wrapperArray.length becomes getter, as below.

export default class WrapperArray implements BaseWrapper {
  wrappers: Array<Wrapper | VueWrapper>;
  length: number;

  constructor (wrappers: Array<Wrapper | VueWrapper>) {
    this.wrappers = wrappers || []
  }
  
  get length() {
    return this.wrappers.length
  }
  
  // ...
}

const wrapper = mount(SomeComponent)
const wrapperArray = wrapper.findAll(SubComponent)
wrapperArray.wrappers = wrapperArray.wrappers.filter(w => !!w.vm.v)

[Toilal]

You may have a look to #334 as an alternative. I can't see any other use case than "filtering" for manually creating WrapperArray.

[emileber]

@Toilal By exporting the types, I just meant exposing the Wrapper and WrapperArray classes outside of this lib. Making it possible for devs to manually wrap an existing Vue instance and use the wrapper utilities.

Unless it's already possible and I just didn't see where in the doc?

[eddyerburgh]

@emileber I thought you meant exposing the flow types. I don't think we should expose the Wrapper and WrapperArray classes. What is your use case? Also, please make an issue so we can discuss this further

[eddyerburgh]

@38elements I like your suggestion 😀

[38elements]

The following code works.

const wrapper = mount(ComponentWithProps)
const foo = wrapper.findAll('div') 
const WrapperArray = foo.constructor
const bar = new WrapperArray(foo.wrappers)
expect(bar.length).to.equal(3)

[emileber]

@38elements While it could work, it could eventually fail if the return value of findAll was to change. Since it's not in the public API, we should avoid such hacks.

[eddyerburgh]

Thinking about it, I think this could be the best solution to the problems you've had (we could also add the filter method as you suggested @Toilal )

[phanan]

Chiming in here. Exported Wrapper and WrapperArray can be useful to create additional helpers. Think plugins/utils for vue-test-utils.

[emileber]

@phanan What do you have in mind?

[phanan]

@emileber I'm writing a helper library on top of vue-test-utils which provides additional methods or wrappers – those may come in handy but don't belong to the core.

[emileber]

@phanan Something like vue-test-utils-utils? hehe See #337 which initially was about exposing Wrapper and WrapperArray.

[eddyerburgh]

We need to add validation to createWrapper and createWrapperArray when we expose them. Can you add tests that check createWrapper and createWrapperArray work correctly, and that they validate the input. The tests should be top-level (e.g. test/unit/specs/createWrapper.spec.js)

[eddyerburgh]

Can you write a few tests for this method and add validation (so check that Wrappers is an array of wrappers and throw an error if not)

[eddyerburgh]

@Toilal are you able to make the changes?

[38elements]

#328 (comment)

Chiming in here. Exported Wrapper and WrapperArray can be useful to create additional helpers. Think plugins/utils for vue-test-utils.

I agree with this comment.
I think providing Wrapper class and WrapperArray class is better than createWrapper().