jest-puppeteer-vuetify

⚠️⚠️ This library is deprecated and does not work with the latest version of Vuetify. ⚠️⚠️

This is a utility which both makes it easier to use XPaths with jest and puppeteer, and generates XPaths to locate Vuetify components.

Installation

jest-puppeteer-vuetify is written in Typescript, and so must be built:

yarn
yarn run build

Testing

A Vuetify application, jest-puppeteer-vuetify-test, is included which serves various Vuetify components for testing purposes. It must be running before tests can be run:

cd jest-puppeteer-vuetify-test
yarn
yarn serve

Once jest-puppeteer-vuetify-test is running, tests can be run:

# Headless mode
yarn run test
# Browser popup, extended jest test timeout
yarn run test-debug

jest-xpaths

Puppeteer and expect-puppeteer prefer using CSS selectors whenever possible. They do have some support for XPath locators, but they cannot be used for everything that CSS selectors can be used for. Sadly, many elements generated by Vuetify cannot practically be identified with CSS selectors, so sometimes XPaths are required. To help remedy this, the jest-xpaths module registers several new methods on the Jest expect object. For instance:

await expect(page).toFillXPath('//input[@id="username"]', 'DandiDan');
await expect(page).toClickXPath('//input[@id="submit"]');

This module is still a work in progress. If you think it should be capable of something that it doesn't do yet, feel free to augment it.

vuetify-xpaths

Despite XPaths sometimes being the only option for locating Vuetify elements, they can still be painful to write and maintain. To help with this, we have the vuetify-xpaths helper which generates XPaths (element locators) for common Vuetify elements. For example, to fill a text field labelled Username and click a button labelled Submit, you can do this:

await expect(page).toFillXPath(vTextField('Username'), 'DandiDan');
await expect(page).toClickXPath(vBtn('Submit'));

Usage

The canonical argument to any vElement is a destructured object. The arguments are unique to each element, but generally will have a content argument and a cssClass argument. If the argument is not an object, it is assumed to be content.

If content is falsy or absent, like vFoo() or vFoo({content: null}), the XPath will match any v-foo.
If content is a string, like vFoo('Hello') or vFoo({content: 'World'}), the XPath will match any v-foo which contains the string.
If content is a valid XPath, like vFoo(vBar()), the XPath will match any v-foo which contains a v-bar. Note that vBar is not necessarily an immediate child of vFoo; vFoo(vBar()) will also match <v-foo><div><v-bar /></div></v-foo>.
If content is an array, every element in the array is treated as a separate content. vFoo(['Hello', vBar()]) will match any v-foo which contains both a v-bar element and the text Hello.

The same assumptions are generally made for different arguments. Here are some examples selectors and DOM elements they will locate:

vFoo({ contents: vBar('Hello World!'), cssClass: ['world', 'hello'] })

<v-foo class='hello world'>
  <v-bar>
    Hello World!
  </v-bar>
</v-foo>

The second argument will generally be an object whose options will vary based on the element. Most elements have a cssClass option which will only match elements with the given class.

If cssClass is falsy, nothing will be done.
If cssClass is a string, like vFoo(null, 'text-center'), it will match all v-foo which have the class text-center. This is roughly equivalent to the CSS selector .v-foo.text-center.
If cssClass is an array, like vFoo(null, ['text-center', 'text--blue']), it will match all v-foo which have both classes text-center and text--blue. This is roughly equivalent to the CSS selector .v-foo.text-center.text--blue.

Other secondary options will generally behave like contents or like cssClass, depending on whether they identify DOM properties or CSS classes.

Because generated XPaths are strings, generally speaking they can be composed with string concatenation. vFoo() + vBar() will match any v-bar which is contained in a v-foo.

This module is still a work in progress. It relies on the internal behavior of Vuetify and is liable to break with any Vuetify update. If existing methods don't work in your use case or there is a missing method, feel free to fix it.

Add support for multiple Vuetify versions

There is demand for this utility in different versions of Vuetify. Different Vuetify version have different elements. For example, 1.5 has v-list-tiles while 2.3 has v-list-items. Differentiating and testing these is challenging.

To start with, we only need to support 1.5 and 2.3 (currently the latest stable). I propose keeping a single package with different files exported for different versions. Instead of exporting vuetify-xpaths.js, we export vuetify-xpaths-1.5 and vuetify-xpaths-2.3.
Initially I think it's OK for these files to be copy/pasted. Once we have a grasp of the scale of the differences, maybe we can figure out a scheme to define all the methods in the base version (1.5) and have subsequent version apply some diff mutation to that base to minimize duplicate code. It's entirely possible that the differences are too substantial to merit this.

Testing is also difficult. We would need a new test app for each supported version, since each app can only have one version of Vuetify as a dependency. We should start with a copy/paste and similarly see if we can arrange some kind of dependency+diff chain to avoid supporting the same app multiple times.

All of this requires that we have reasonably complete support for a single version. Copy/pasting to a separate version will be much, much harder to maintain if we are still trying to add new methods, potentially across versions.

girder / jest-puppeteer-vuetify Goto Github PK