In-memory WebExtensions API Fake Implementation for testing purposes
npm install webextensions-api-fakeWhen testing WebExtensions you might want a working fake implementation of the API in-memory available without spawning a complete browser.
This package depends on sinon and webextensions-api-mock to have the whole browser WebExtension API available as sinon stubs. You can pass in your own stubbed version of the browser.
``
npm install --save-dev webextensions-api-fake sinon
Important: sinon is a peer dependency, so you have to install it yourself. That's because it can otherwise lead to unexpected assertion behavior when sinon does instanceof checks internally. It also allows to upgrade sinon without the need to bump the version in webextensions-api-fake.
`js
import browserFake from 'webextensions-api-fake';
// or
// const { default: browserFake } = require('webextensions-api-fake');
const browser = browserFake();
`
browser is now a webextensions-api-mock with faked api.
Currently supported API fake implementations based on Firefox57+:
- alarms
- create
- get
- getAll
- clear
- clearAll
- create
- triggers: onCreated
- get
- remove
- triggers: onRemoved
- query
- update
- triggers: onUpdated
- cookies
- get
- getAll
- getAllCookieStores
- remove
- set
- i18n
- getAcceptLanguages
- Returns ['en-US'] by default, can be overwritten by _setAcceptLanguages
- getMessage
- Returns results based on the and default_locale passed as options
- getUILanguage
- Returns by default, can be overwritten by _setUILanguage
- detectLanguage
- Returns a Promise that resolves to the result of
- tabs
- create
- You can pass in any parameter you want to overwrite
- triggers: onCreated. If url is given that doesn't start with about: or moz-ext:: webRequest.onBeforeRequest, webRequest.onCompleted, onUpdated
- update
- triggers: If is given that doesn't start with about: or moz-ext:: webRequest.onBeforeRequest, webRequest.onCompleted, onUpdated
- get
- query
- remove
- triggers: onRemoved
- storage
- local
- get
- remove
- set
- clean
- sync
- get
- remove
- set
- clean
- managed
- get
- remove
- set
- clean
Faked API methods are also directly available with underscore prefix. E.g. browser.tabs._create exposes the browser.tabs.create fake. This can be useful to trigger fake behavior from tests without polluting its sinon call history.
#### Special Fake Methods
- i18n
- \_setAcceptLanguages
- Overwrite the default for getAcceptLanguages
- \_setUILanguage
- Overwrite the default for
- tabs
- \_create - helper method, same as create, but takes a special fake object that you can pass as second parameter with the following properties
- _options_
Given the following production code for your WebExtension:
_example.js_
`js
browser.tabs.onCreated.addListener(async tab => {
await browser.storage.local.set({
lastCreatedTab: tab,
});
});
const firstWeDoThis = async () => {
const container = await browser.contextualIdentities.create({
name: 'My Container',
color: 'blue',
icon: 'fingerprint',
});
await browser.storage.local.set({
lastCreatedContainer: container.cookieStoreId,
});
};
const thenWeDoThat = async () => {
const { lastCreatedContainer } = await browser.storage.local.get(
'lastCreatedContainer'
);
await browser.tabs.create({
cookieStoreId: lastCreatedContainer,
});
};
const myFancyFeature = async () => {
await firstWeDoThis();
await thenWeDoThat();
};
myFancyFeature();
`
You could have a test that looks like this (using mocha, sinon-chai, chai.should and require-reload in this case):
_example.test.js_
`js
const { default: browserFake } = require('webextensions-api-fake');
const reload = require('require-reload')(require);
const sinon = require('sinon');
const sinonChai = require('sinon-chai');
const chai = require('chai');
chai.should();
chai.use(sinonChai);
describe('Useful WebExtension', () => {
beforeEach(async () => {
// fake the browser
global.browser = browserFake();
// execute the production code
reload('./example.js');
// wait a tick to give the production code the chance to execute
return new Promise(resolve => process.nextTick(resolve));
// instead of doing a require and then waiting for the next tick
// it would also be possible to set e.g. global._testEnv = true; in the test
// and in the production code something like
// if (!_testEnv) {
// myFancyFeature();
// } else {
// module.exports = myFancyFeature;
// }
//
// that would make it possible to get the actual function when doing require
});
describe('My Fancy Feature which is executed on load', () => {
it('should work', async () => {
browser.tabs.create.should.have.been.calledWithMatch({
cookieStoreId: sinon.match.string,
});
const tabs = await browser.tabs.query({});
tabs.length.should.equal(1);
});
});
describe('Triggering listeners after loading the production code', () => {
it('should work as well', async () => {
const createdTab = await browser.tabs.create({});
const { lastCreatedTab } = await browser.storage.local.get(
'lastCreatedTab'
);
lastCreatedTab.id.should.equal(createdTab.id);
});
});
});
`
You can find the example in the examples directory and also execute it:
`
npm install
npm run example
If you want to execute your WebExtensions tests using JSDOM, then webextensions-jsdom might be for you.
#### Exported default function([options])
- _options_
Returns a new stubbed browser with newly created and applied fakes.
#### Exported Class: WebExtensionsApiFake
##### Constructor: new WebExtensionsApiFake
##### webExtensionsApiFake.createBrowser([options])
Returns a new stubbed browser without applied fakes.
##### webExtensionsApiFake.fakeApi(browser)
- _browser_
Applies the API fakes to the given browser object. Can be called multiple times with different browser stubs and applies the same fakes (with the same in-memory data) in that case.