ueokande / lanthan

A test framework for WebExtensions

lanthan

Lanthan is a test framework for WebExtensions. It provides a remote WebExtensions API to enable web browser automation and assertion. Lanthan utilizes selenium-webdriver to install and control your browser from the local.

Install

Install lanthan via npm as the following:

$ npm install -D lanthan

Install lanthan via yarn as the following:

$ npm add -D lanthan

or add a package on the "devDependencies" field of your package.json:

{
  "devDependencies": {
    "lanthan": "0.0.2"
  }
}

Quick start

There are four examples of lanthan usage. You can see a full version of the script in examples directory.

Setup and tear-down lanthan (examples/01_setup_teardown.js)

A lanthan package provides a builder class Builder to create a browser session and APIs to access it. Import Builder from lanthan package as the following:

// Common JS
const { Builder } = require('lanthan');

// ES Module
import { Builder } from 'lanthan';

The Builder provides a static method forBrowser() to initialize a builder for the browser. Only "firefox" is supported currently. Then the build() method launch a browser and asynchronously returns Lanthan object to access the browser

let lanthan = await Builder
  .forBrowser('firefox')  // Lanthan currently supports only Firefox
  .build();

To close the session of the browser, invoke quit() method:

await lanthan.quit();

Get a WebExtensions API (examples/02_webext_api.js)

The lanthan session provides a remote WebExtensions API. The API is compatible with WebExtensions, but the API is available outside of the browser. That means the API lanthan allows you to control and assert a browser status on the local (Node.js).

The getWebExtBrowser() of the Lanthan object returns an object which provides WebExtensions API compatible object:

// get WebExtensions API
let browser = lanthan.getWebExtBrowser();

For example, to create and get tabs by the API:

// Create new tabs
await browser.tabs.create({ url: 'https://example.com/' });
await browser.tabs.create({ url: 'https://example.org/' });

// Get all tabs;
let tabs = await browser.tabs.query({});

// Assert that the number of the tabs is three
assert.strictEqual(tabs.length, 3);

Get a WebDriver API (examples/03_webdriver_api.js)

The lanthan session also provides a WebDriver API. That is convenient to make test automation. The WebDriver API allows you to sending key events, assert DOM elements, execute JavaScript and so on.

The getWebDriver() of the Lanthan object returns an object which provides selenium WebDriver API:

// Get WebDriver API
let webdriver = lanthan.getWebDriver();

For example, to open a page and click an element:

// Open https://example.com/
await webdriver.navigate().to('https://example.com/');

let a = webdriver.findElement(By.css('a'));
await a.click();

For more details of WebDriver API, see also Selenium project and selenium-webdriver documentation.

Spy an add-on (examples/04_spy_addon.js)

Lanthan installs a daemon add-on to control Firefox remotely via HTTP. The daemon add-on is an independent add-on, but it can spy to existing add-on on the local. By the spying to the add-on, the lanthan's remote server is mixed-in into the target add-on. So remote WebExtensions API allows you to access internal state such as local storage of the target add-on.

You can see a sample add-on in [example/addon][]. The add-on counts up pressed keys and store counts to local storage by the page origin. Lanthan spied to the local add-on by spyAddon() and load it as a temporary add-on:

let lanthan = await Builder
  .forBrowser('firefox')  // Lanthan currently supports only Firefox
  .spyAddon(path.join(__dirname, 'addon'))  // Spy to the add-on
  .build();

The remote WebExtensions API can access the local storage of the add-on:

let { count } = await browser.storage.local.get('count');
assert.strictEqual(count['https://example.com'], 1);
assert.strictEqual(count['https://example.org'], 3);
assert.strictEqual(count['https://example.net'], undefined);

Licence

MIT