# webextensions-geckodriver

> Run your WebExtension with GeckoDriver

Latest version **0.7.0** (published 2021-05-07) · MPL-2.0 license · 0 weekly downloads

## Install

```sh
npm install webextensions-geckodriver
pnpm add webextensions-geckodriver
yarn add webextensions-geckodriver
bun add webextensions-geckodriver
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.7.0 |
| Published | 2021-05-07 |
| First published | 2018-03-31 |
| Weekly downloads | 0 |
| License | MPL-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 29.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 14 |
| Author | stoically |
| Maintainers | stoically |

## Links

- npm: https://www.npmjs.com/package/webextensions-geckodriver
- Repository: https://github.com/webexts/webextensions-geckodriver
- Issues: https://github.com/webexts/webextensions-geckodriver/issues
- npm.io page: https://npm.io/package/webextensions-geckodriver

## Dependencies (5)

- [mz](https://npm.io/package/mz.md) ^2.7.0
- [web-ext](https://npm.io/package/web-ext.md) ^6.1.0
- [fx-runner](https://npm.io/package/fx-runner.md) ^1.0.13
- [geckodriver](https://npm.io/package/geckodriver.md) ^1.22.3
- [selenium-webdriver](https://npm.io/package/selenium-webdriver.md) ^4.0.0-beta.3

## Recent versions

- 0.7.0 (latest) — 2021-05-07
- 0.6.1 — 2019-07-18
- 0.6.0 — 2019-07-17
- 0.5.1 — 2019-03-23
- 0.5.0 — 2019-03-23
- 0.4.1 — 2019-03-22
- 0.4.0 — 2018-09-22
- 0.3.1 — 2018-04-02
- 0.3.0 — 2018-03-31
- 0.2.1 — 2018-03-31
- 0.2.0 — 2018-03-31
- 0.1.0 — 2018-03-31

## 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* `<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`](https://github.com/mozilla-jetpack/node-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`](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*, `<object>`, a new [`selenium-webdriver/firefox`](https://www.npmjs.com/package/selenium-webdriver) instance with previously loaded [`geckodriver`](https://www.npmjs.com/package/geckodriver)
* *install*, `<function>`, returns a Promise that resolves when installing is finished, accepts an options `<object>`:
  * *extensionPath*, `<string>`, 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*, `<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')`](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).

---
_Source: https://npm.io/package/webextensions-geckodriver · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._