webextension-polyfill/CONTRIBUTING.md

Hi! Thanks for your interest in helping to make the "cross-browser extension" developers life easier by contributing to the webextension-polyfill library.

This document provides some additional information that you may find useful while looking at how to apply changes to this library and submit them for review.

Table of contents

• Building
• Test Suites
• Writing commit messages

Building

To build, assuming you've already installed node >= 6 and npm, simply run:

git clone https://github.com/mozilla/webextension-polyfill.git

cd webextension-polyfill

npm install

npm run test

This will install all the npm dependencies and build both non-minified and minified versions of the final library, and output them to dist/browser-polyfill.js and dist/browser-polyfill.min.js, respectively, and finally execute the unit tests on the generated dist files.

Test Suites

This project provides two test suites:

• unit tests (which only require Node.js to run)
• module bundlers smoke tests
• integration tests (which requires also a stable version of Chrome and Firefox)

Unit Tests

The unit tests run in Node.js with Mocha, and use jsdom and Sinon to mock a browser-like environment for testing the library.

The unit tests are located in the "test/" directory and they have to be named "test/test-*.js".

npm run test run all the unit tests on the non-minified version of the library, whereas npm run test-minified can be used to run the unit tests on the minified version.

Optionally code coverage data can be collected and reported while running the unit tests, by running npm run test-coverage.

Module Bundler smoketests

npm run test-module-bundlers-smoketests runs browserify and webpack, to verify that the most commonly used module bundlers are not raising any unexpected error while building a bundle that requires this library.

Integration Tests

This repository also includes a small set of integration tests, located at "test/integration/". The integration tests use selenium-webdriver to run a set of test extensions (located at "test/fixtures/") on real browsers, currently Chrome (as the browser officially supported by this library) and Firefox (to compare the polyfilled APIs with the ones natively provided on Firefox).

The shell script test/run-browsers-smoketests.sh (executed by the CI service on every pull request) runs this test suite on both the browsers.

To run the integration tests on a single browser:

TEST_BROWSER_TYPE=chrome npm run test-integration

or

TEST_BROWSER_TYPE=firefox npm run test-integration

These tests emit their results using the TAP protocol.

Writing commit messages

The subject of the pull requests and commit messages must adhere to the Angular style of semantic messages. This allows us to auto-generate a changelog without too much noise in it. Additionally, write the commit message in past tense so it will read naturally as a historic changelog.

Examples:

• feat: Added newAmazingAPI namespace to the metadata
• fix: newAmazingAPI.create should reject on errors
• docs: Improved contributor docs
• style: Added no-console linting, cleaned up code
• refactor: Split out myHelperFunction
• perf: Changed myHelperFunction to be 2x faster
• test: Added more tests for newAmazingAPI
• chore: Upgraded yargs to 3.x.x

If you want to use scopes then it would look more like: test(integration): Added test extension for newAmazingAPI.