POC: Plugin interface with wrapper in closure

[JessicaSachs]

This POC aims to add on to the current work surrounding plugins. I used the branch at #55 to build some plugins. I struggled with the existing API. I was limited from using fat-arrow functions due to the wrapper only being available on this. I wanted a closure where the wrapper would be passed in.

Importance of Plugins

Our intension is that plugins will be a means for users to...

1. create short-hand aliases 🚀
2. implement helper functions 🛠
3. customize Vue Test Utils as they need to 👩🏻‍🎨

The pattern

Certain entities are Pluggable (VueWrapper, DOMWrapper). You can install plugins, which may return objects to be extended onto the instance of wrappers being mounted. This pattern looks like data or setup functions in Vue core and should feel familiar.

Basic example

This plugin will add the width property and myMethod once the wrapper is mounted.

const plugin = (wrapper) => {
  return {
    width: 200,
    myMethod() {}
  }
}

config.plugins.VueWrapper.install(plugin)

Here is a plugin that will provide a new method to clean up the output of text(). (The use case is based off of jest-dom)

// A plugin to add optional whitespace stripping to VueWrapper.text()
const normalize = text =>  text.replace(/\s+/g, ' ').trim()

// HTML-friendly text matcher. Based off of jest-dom
const friendlyTextPlugin = (wrapper) => ({
  normalizeText: () => normalize(wrapper.text()),
})

// installing it into VueWrapper

config.plugins.VueWrapper.install(friendlyTextPlugin)

const wrapper = mount({ template: `<div>    Foo</div>` })
wrapper.normalizeText() // 'Foo'

Weak spots:

1. Install functions are executed every mount

• Perhaps this is ok. If most of the plugins' work is just setting up functions to be called later, this might not be a concern

2. I don't think Pluggable as a class is the right abstraction

• I'm really new to Typescript 😬

[JessicaSachs]

Should decide if we're going to exit the process here or quietly swallow the misconfigured plugin

[lmiller1990]

I think failing loudly is usually a good idea

[lmiller1990]

The louder the better, ideally with "you screwed up and here's where and how to fix it"

[JessicaSachs]

Yeah. I'm fine with that. I wish I had a plugin name to point people at.

[lmiller1990]

hmmm didn't think of that. 🤔

[dobromir-hristov]

Will we have access to private properties on the instance? Like the rootVM?

[JessicaSachs]

Yeah, your original example will work. You can get access to the ComponentPublicInstance under componentVM which is private.

[JessicaSachs]

const namePlugin = wrapper => ({ lowerCaseName: wrapper.componentVM.$.type.name })
config.plugins.VueWrapper.install(namePlugin)
const wrapper = mount({ template: `<h1>Hello</h1>`, name: 'My_Component' })
wrapper.lowerCaseName // 'my_component'

[lmiller1990]

I resolved conflicts, and deployed latest master to my npm account and played around and so far this seems to work great 👍 nice job @JessicaSachs

[cexbrayat]

@ts-ignore should be removed here: you should just need to have the same signature than VueWrapper, i.e VueWrapper<T extends ComponentPublicInstance> and TS will be happy to merge the declarations.
You should also be able to remove all the other @ts-ignore in the file.

[JessicaSachs]

🤔 I will give this a try

[lmiller1990]

To no-one's surprised I changed the types based on @cexbrayat 's recommendation and it worked

[lmiller1990]

Looks good to me! CI is passing and we have no conflicts. We need some docs then we can merge this (this seems like an important feature to document and document well).

[afontcu]

Looks good to me! CI is passing and we have no conflicts. We need some docs then we can merge this (this seems like an important feature to document and document well).

I've been trying to keep docs up to date with vtu-next releases, just to make sure we don't document any POC or temporary feature (I think this is a sensible way of handling docs until we're able to merge repos). What I mean by this is that feel free to merge this up if you feel confident enough with the implementation and release a new alpha, and then we can work out the docs part :)

[lmiller1990]

Ok, let's do it. Great job all

[JessicaSachs]

Nice! Thanks :-) I'll pick up the docs this weekend.