WebExtensions API Mock

1.0.0 verified Fri May 01 auth: no javascript

Automatically generated sinon stubs for the WebExtensions API, designed to make browser extension testing easy. Version 1.0.0 uses the Firefox 72.0.2 schema and provides TypeScript types. Sinon is a peer dependency, not bundled, to avoid instanceof issues. Includes API and CLI to update schema to latest stable Firefox via webextensions-schema. Produces a fresh sandbox per call, with sinonSandbox exposed. Ideal for unit testing WebExtensions against sinon assertions and stubs.

Common errors

error Cannot find module 'sinon' ↓

cause sinon is a peer dependency and not installed automatically.

fix

npm install --save-dev sinon@^7.5.0

error browserMock is not a constructor ↓

cause Attempting to use new browserMock() instead of calling it as a function.

fix

const browser = browserMock();

error Cannot read property 'create' of undefined ↓

cause Method namespace (e.g., tabs) not available because schema might not include it or upgrade needed.

fix

Run webextensions-api-mock update to get latest schema, or check Firefox version compatibility.

error browser.sinonSandbox.resetHistory is not a function ↓

cause Property name typo (e.g., sinonSandbox vs sinonSandbox).

fix

Use browser.sinonSandbox.resetHistory() (note: 'sinonSandbox' with capital S).

Warnings

deprecated Schema based on Firefox 72.0.2; newer APIs may be missing. ↓

fix Run `webextensions-api-mock update` to sync to latest Firefox stable schema, or manually update via API.

gotcha sinon is a peer dependency, not bundled; version mismatch can cause assertion errors due to instanceof checks. ↓

fix Install sinon as devDependency: npm install --save-dev sinon webextensions-api-mock

gotcha Each call to browserMock() creates a new sinon sandbox; stubs are isolated. Reusing the same browser object across tests may cause state leakage. ↓

fix Create a new browserMock() in each test or use beforeEach to reset via browser.sinonSandbox.reset()

gotcha Event listeners are stubs with .addListener. Triggering with yield() works but does not simulate real event arguments. ↓

fix Pass mock arguments to yield() to simulate event data: browser.tabs.onCreated.addListener.yield({ id: 1, url: '...' });

Install

npm install webextensions-api-mock

yarn add webextensions-api-mock

pnpm add webextensions-api-mock

Imports

default (browserMock)
wrong
```
const browserMock = require('webextensions-api-mock');
```
correct
```
import browserMock from 'webextensions-api-mock';
```
Package is ESM-first. For CommonJS, use const { default: browserMock } = require('webextensions-api-mock');

update

wrong

const { update } = require('webextensions-api-mock');

correct

import { update } from 'webextensions-api-mock';

Named export for updating schema; also callable via CLI: webextensions-api-mock update

browserMock

wrong

const browser = new browserMock();

correct

import browserMock from 'webextensions-api-mock'; const browser = browserMock();

browserMock is a function that creates a new browser object, not a constructor.

Quickstart

Creates a WebExtensions API mock, calls a method, asserts stub behavior, triggers event listeners, and resets history.

import browserMock from 'webextensions-api-mock';
import { assert } from 'sinon';

// Create a fresh browser mock
const browser = browserMock();

// Simulate production code calling browser.tabs.create
(browser.tabs.create as any)({ url: 'https://example.com' });

// Assert the stub was called
assert(browser.tabs.create.calledOnce, 'tabs.create should have been called');

// Trigger an event listener
browser.tabs.onCreated.addListener.yield();

// Reset all stubs via the sandbox
browser.sinonSandbox.resetHistory();