Writing a Wendigo Plugin

The repository https://github.com/angrykoala/wendigo-plugin provides a template to ease the creation of a new plugin

To write a plugin you must write classes defining the new methods and then registering them in Wendigo with registerPlugin before creating a browser.

class MyPlugin {
    constructor(browser) { // The plugin will receive the browser instance in the constructor
        this._browser = browser;
    }

    getHeaderTitle() { // Custom method to find our title
        return this._browser.text("h1.header-title")[0];
    }

    findKoalas() {
        return this._browser.findByTextContaining("koala");
    }

    _beforeOpen(options) { // This hook will be called anytime `browser.open` is executed
        // You can perform actions required for your plugin to run whenever
        // a new page is opened such as setting up cache
        // keep in mind that the page won't be accesible yet
    }

    _beforeClose() { // This hook will be called anytime `browser.close` is executed
        // You can perform actions required for your plugin when the page is
        // close, keep in mind that this will only be called on browser.close and
        // not on any page loading
    }

    _afterOpen(options) { // This hook will be called after the page is opened and loaded
        // You can use this hook to start performing actions with evaluate or
        // adding custom scripts with this._browser.page.addScriptTag
    }
}


class MyPluginAssertions { // The assertions will be under browser.assertions[myPluginName]
    constructor(browser, myPlugin) { // Plugin assertions receive browser and plugin in the constructor
        this._myPlugin = myPlugin;
    }

    thereAreKoalas(count) {
        const koalas = this._myPlugin.findKoalas().length;
        if (!count && koalas === 0) throw new AssertionError("No koalas :("); // node's AssertionError
        else if (count && koalas !== count) throw new AssertionError("No enough koalas :/");
    }

    headerTitle(title) {
        if (this._myPlugin.getHeaderTitle() !== title) throw new AssertionError("Invalid title");
    }
}

Wendigo.registerPlugin("koalafied", MyPlugin, MyPluginAssertions);

const browser=Wendigo.createBrowser();
//... more code ...

browser.koalafied.getHeaderTitle(); // Koalas are great

browser.assert.koalafied.headerTitle("Koalas are great");
browser.assert.koalafied.thereAreKoalas();

Wendigo.registerPlugin receives 3 parameters:

• name: Name to be used to access the plugin, it must be different than other plugins and should not collide with wendigo core modules.
• plugin: Class to be used as plugin accessed under browser.name, this class will receive browser as constructor parameter and 2 methods can be implemented as hooks:
  • _beforeOpen: Called when browser.open is called, before opening the page.
  • _beforeClose: Called when browser.close is called, before closing the page.
• assertion: Class to be used as plugin's assertions, it can be accessed on browser.assertion.name the constructor will receive both the browser and the core plugin as parameters

registerPlugin also accepts a single object containing the data in the following structure:

• name
• plugin
• assertion

Keep in mind that both the plugin and the assertions are optional, but at least one must exists to register the plugin.

Instead of classes, if a plain function is provided as a plugin or assertion, it will be attached directly to browser or browser assertion (without calling new), the function will receive the same arguments as the constructor of the plugin, as well as any extra parameter passed to the function:

function myPluginAssertionFunc(browser, myPlugin, count){
    const koalas = myPlugin.findKoalas().length;
    if (!count && koalas === 0) throw new AssertionError("No koalas :("); // node's AssertionError
    else if (count && koalas !== count) throw new AssertionError("No enough koalas :/");
}

Wendigo.registerPlugin("koalafied", MyPlugin, MyPluginAssertions);
browser.assert.koalafied(); // note the assertion is called directly

Publishing it!

If you want to create a new plugin and publish it in the npm store. Please, follow these steps:

1. Make sure your package exports a single object compatible with the interface described above to make it easier to import. Do not export the classes individually.
2. Make sure your code is tested using Node.js 8 and above.
3. Set Wendigo as a peer dependency in you package.json.
   • If you are writing tests, also set Wendigo as a dev dependency, never as a normal dependency.
4. Wendigo usually follows semantic versioning so your plugin should be compatible with any minor version above the version you wrote it, but a lot of things may break, so it is good to make sure your plugin still works properly in the latest version after a release.
5. Make a PR to update this document withyour plugin.
6. Let people know about it!.