webextensions-geckodriver
v0.7.0
Published
Run your WebExtension with GeckoDriver
Downloads
22
Readme
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 themanifest.json
file - options
<object>
, optional- binary
<string>
, optional, lets you set thebinary
that is passed tofx-runner
. Possible values:firefox
,beta
,aurora
,nightly
,firefoxdeveloperedition
. Defaults to:firefox
. - autoInstall,
<boolean>
, optional, if set tofalse
the extension will not be installed, you can manually do so later by callinginstall
. Defaults totrue
. - webExt
<object>
, optional, lets you overwrite the parameters that get passed intoweb-ext.cmd.build
- fxOptions
firefox.Options
, optional, afirefox.Options
that will be passed to the webdriver
- binary
Returns a Promise that resolves with an initialized WebExtensionsGeckodriver
instance in case of success, notably with the following properties:
- geckodriver,
<object>
, a newselenium-webdriver/firefox
instance with previously loadedgeckodriver
- install,
<function>
, returns a Promise that resolves when installing is finished, accepts an options<object>
:- extensionPath,
<string>
, optional, path to something thatinstallAddon
can handle. Defaults to theweb-ext
build extensionPath. - temporary,
<boolean>
, optional, whether the WebExt should be installed temporary. Defaults totrue
.
- extensionPath,
- internalUUID,
<function>
, returns a Promise that resolves to theInternal 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.