https://github.com/stoically/webextensions-geckodriver
Run your WebExtension with GeckoDriver based on the manifest.json for testing purposes
https://github.com/stoically/webextensions-geckodriver
Last synced: about 1 year ago
JSON representation
Run your WebExtension with GeckoDriver based on the manifest.json for testing purposes
- Host: GitHub
- URL: https://github.com/stoically/webextensions-geckodriver
- Owner: stoically
- License: mpl-2.0
- Created: 2018-03-31T16:37:43.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-05-07T01:52:20.000Z (about 5 years ago)
- Last Synced: 2025-04-14T17:12:13.572Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 140 KB
- Stars: 13
- Watchers: 3
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
### WebExtensions GeckoDriver
When testing [WebExtensions](https://developer.mozilla.org/Add-ons/WebExtensions) you might want to automatically load them into Firefox and do functional testing with [geckodriver](https://github.com/mozilla/geckodriver).
### Installation
```
npm install --save-dev webextensions-geckodriver
```
### Usage
```js
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](#api) 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`):
```js
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](example/).
### API
#### Exported default function(path[, options])
* *path* ``, required, absolute path to the `manifest.json` file
* *options* ``, optional
* *binary* ``, optional, lets you set the `binary` that is passed to [`fx-runner`](https://github.com/mozilla-jetpack/node-fx-runner). Possible values: `firefox`, `beta`, `aurora`, `nightly`, `firefoxdeveloperedition`. Defaults to: `firefox`.
* *autoInstall*, ``, optional, if set to `false` the extension will not be installed, you can manually do so later by calling `install`. Defaults to `true`.
* *webExt* ``, optional, lets you overwrite the parameters that get passed into [`web-ext.cmd.build`](https://github.com/mozilla/web-ext#using-web-ext-in-nodejs-code)
* *fxOptions* `firefox.Options`, optional, a [`firefox.Options`](https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/firefox_exports_Options.html) 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*, ``, a new [`selenium-webdriver/firefox`](https://www.npmjs.com/package/selenium-webdriver) instance with previously loaded [`geckodriver`](https://www.npmjs.com/package/geckodriver)
* *install*, ``, returns a Promise that resolves when installing is finished, accepts an options ``:
* *extensionPath*, ``, optional, path to something that [`installAddon`](https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/firefox_exports_Driver.html) can handle. Defaults to the `web-ext` build extensionPath.
* *temporary*, ``, optional, whether the WebExt should be installed temporary. Defaults to `true`.
* *internalUUID*, ``, returns a Promise that resolves to the `Internal UUID` of the installed extension
* *uninstall*, ``, returns a Promise that resolves when uninstalling is finished, accepts an optional extensions id as ``
#### Exported property: `webdriver`
Return value of [`require('selenium-webdriver')`](https://www.npmjs.com/package/selenium-webdriver)
#### Exported property: `firefox`
Return value of [`require('selenium-webdriver/firefox')`](https://www.npmjs.com/package/selenium-webdriver)
### Travis Configuration
```
dist: xenial
services:
- xvfb
language: node_js
addons:
firefox: latest
node_js:
- 'lts/*'
```
### Headless Example
```js
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`](https://github.com/webexts/webextensions-jsdom) might be for you.
### Credits
Thanks to [Standard8](https://github.com/Standard8) for the original work in [example-webextension](https://github.com/Standard8/example-webextension).