Support wrapping an already mounted Vue instance

[emileber]

The other day while testing a class that manually mounts a Vue instance to an element in the page, I wanted to use the Wrapper utilities but found out that I can't just call new Wrapper(myVueInstance); as it seems that Wrapper and WrapperArray are not exposed within the public API.

I didn't dive deep into the code, so I might have missed a way to achieve what I want.

A quick look at the source and the documentation shows that only the following is exposed:

export default {
  createLocalVue,
  config,
  mount,
  shallow,
  TransitionStub,
  TransitionGroupStub
}

I found /pull/328 which is close to what I'd want.

[eddyerburgh]

I'm against exporting these classes.

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).

[emileber]

@eddyerburgh Why? Is there a risk I'm not seeing?

We're already using instances of these and the documentation is already available.

[emileber]

It's just that most utilities provided by Wrapper could be used with arbitrary instances, not limited to the one being tested with mount or shallow.

[eddyerburgh]

The risk in my opinion is bloating the API and making the library more confusing for users.

The docs make a distinction between Wrapper and WrapperArray. But they don't make a distinction between VueWrapper, or Wrapper, and we may add or remove extra Wrappers in the future.

I think that exposing methods like this that deal with the internals encourage users to use vue-test-utils rely on internals that could change in the future. Making sure mount and shallow are the only entry points give us more control to change how it works under the hood.

[emileber]

Is there a way to use mount or shallow with an already mounted Vue instance?

Or just a wrap function similar to the 2 other entry points that deals with already mounted Vue instances, returning the right wrapper according to what was passed.

[eddyerburgh]

No, not at the moment.

When would you have an already mounted instance in a test? Can you post an example in code?

[emileber]

For example, I'm testing our widget API (vanilla JS) which mounts a Vue instance on a optionally passed element:

  render() {
    const doc = this.options.document;
    let el = query(this.options.el);
    if (!el) {
      el = doc.createElement('div');
      doc.body.appendChild(el);
    }

    this.vue = new Vue({
      el,
      render: h => h(App),
    });
  }

And I want to make sure that the passed element is replaced by our Vue instance's element.

// Create a test element
const testClass = 'test-element';
const el = document.createElement('section');
el.classList.add(testClass);
body.append(el);

// Use our element with the widget
const instance = new Widget({ el });
const vue = instance.vue;

it('should replace our element to a Vue instance', () => {
  expect(vue.$el).not.toBe(el);
  expect(vue.$el.classList.contains(testClass)).toBeFalsy();
  expect(body.contains(el)).toBe(false);
});

There's probably a better way to test this, but initially, I wanted to use the Wrapper utilities to check for classes, or to make sure that the element was a <div> and not <section>. Right now, I'm falling back on the DOM API.

Not that it's absolutely necessary, but I wanted to be consistent with the other tests where I'm mounting the components with mount or shallow and was really surprised that the Wrapper class that I was using wasn't even exposed other than as a return value.

[38elements]

@eddyerburgh
Would you please tell me that the specification supports Vue instance or not ?

[eddyerburgh]

@38elements what specification do you mean?

[eddyerburgh]

How about exposing the createWrapper method that takes either a vnode or a Vue instance.

I see that there's a need for this for some users.

[38elements]

There is the description for this in test and document or not. (I mistaked)
The specification is the description for this in test and document or not.
The specification is the description for this in test and document.
I could not find it.

[eddyerburgh]

Ah, so we don't currently support already mounted elements. We could look at adding support.