WebExtensions GeckoDriver

When testing WebExtensions you might want to automatically load them into Firefox and do functional testing with geckodriver.

Installation

npm install --save-dev webextensions-geckodriver

Usage

const webExtensionsGeckoDriver = require('webextensions-geckodriver');
const webExtension = await webExtensionsGeckoDriver('/absolute/path/to/manifest.json');

Loads the WebExtension as Temporary Add-on into a new Firefox instance. See API docs for more details.

Example

manifest.json includes

  "browser_action": {
    "default_title": "Visit Example.com"
  },
  "applications": {
    "gecko": {
      "id": "@examplewebextension",
      "strict_min_version": "57.0"
    }
  }

Test could look like this (using mocha):

const path = require('path');
const assert = require('assert');

const webExtensionsGeckoDriver = require('webextensions-geckodriver');
const {webdriver} = webExtensionsGeckoDriver;

const manifestPath = path.resolve(path.join(__dirname, './path/to/manifest.json'));

describe('Example', () => {
  let geckodriver;

  before(async () => {
    const webExtension = await webExtensionsGeckoDriver(manifestPath);
    geckodriver = webExtension.geckodriver;
  });

  it('should have a Toolbar Button', async () => {
    const button = await geckodriver.wait(webdriver.until.elementLocated(
      // browser_actions automatically have applications.gecko.id as prefix
      // special chars in the id are replaced with _
      webdriver.By.id('_examplewebextension-browser-action')
    ), 1000);
    assert.equal(await button.getAttribute('tooltiptext'), 'Visit Example.com');
  });

  after(() => {
    geckodriver.quit();
  });
});

Full executable example is in the example directory.

API

Exported default function(path[, options])

• path <string>, required, absolute path to the manifest.json file
• options <object>, optional
  • binary <string>, optional, lets you set the binary that is passed to fx-runner. Possible values: firefox, beta, aurora, nightly, firefoxdeveloperedition. Defaults to: firefox.
  • autoInstall, <boolean>, optional, if set to false the extension will not be installed, you can manually do so later by calling install. Defaults to true.
  • webExt <object>, optional, lets you overwrite the parameters that get passed into web-ext.cmd.build
  • fxOptions firefox.Options, optional, a firefox.Options that will be passed to the webdriver

Returns a Promise that resolves with an initialized WebExtensionsGeckodriver instance in case of success, notably with the following properties:

• geckodriver, <object>, a new selenium-webdriver/firefox instance with previously loaded geckodriver
• install, <function>, returns a Promise that resolves when installing is finished, accepts an options <object>:
  • extensionPath, <string>, optional, path to something that installAddon can handle. Defaults to the web-ext build extensionPath.
  • temporary, <boolean>, optional, whether the WebExt should be installed temporary. Defaults to true.
• internalUUID, <function>, returns a Promise that resolves to the Internal UUID of the installed extension
• uninstall, <function>, returns a Promise that resolves when uninstalling is finished, accepts an optional extensions id as <string>

Exported property: webdriver

Return value of require('selenium-webdriver')

Exported property: firefox

Return value of require('selenium-webdriver/firefox')

Travis Configuration

dist: xenial
services:
  - xvfb

language: node_js
addons:
  firefox: latest

node_js:
  - 'lts/*'

Headless Example

const webExtensionsGeckoDriver = require('webextensions-geckodriver');

const {firefox} = webExtensionsGeckoDriver;
// or equivalently:
//   const firefox = require('selenium-webdriver/firefox')

const fxOptions = new firefox.Options()
  .headless()
  .windowSize({height: 1080, width: 1920}) // If you rely on viewport size

webExtensionsGeckoDriver(manifestPath, {fxOptions})

JSDOM

If you're looking for a way to test WebExtensions with JSDOM then webextensions-jsdom might be for you.

Credits

Thanks to Standard8 for the original work in example-webextension.