107 lines
3.9 KiB
Markdown
107 lines
3.9 KiB
Markdown
|
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](#building)
|
||
|
|
* [Test Suites](#test-suites)
|
||
|
|
* [Writing commit messages](#writing-commit-messages)
|
||
|
|
|
||
|
|
## Building
|
||
|
|
|
||
|
|
To build, assuming you've already installed [node >= 6](https://nodejs.org) and
|
||
|
|
[npm](https://www.npmjs.com/), simply run:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
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 (which requires also browserify and webpack to be installed globally)
|
||
|
|
- integration tests (which requires also a stable version of Chrome and Firefox)
|
||
|
|
|
||
|
|
### Unit Tests
|
||
|
|
|
||
|
|
The unit tests run in Node.js with [Mocha](https://mochajs.org), and use jsdom and
|
||
|
|
[Sinon](https://sinonjs.org) 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
|
||
|
|
|
||
|
|
The shell script `test/run-module-bundlers-smoketests.sh` 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 Travis CI service on every
|
||
|
|
pull request) runs this test suite on both the browsers.
|
||
|
|
|
||
|
|
To run the integration tests on a single browser:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
TEST_BROWSER_TYPE=chrome npm run test-integration
|
||
|
|
```
|
||
|
|
or
|
||
|
|
|
||
|
|
```sh
|
||
|
|
TEST_BROWSER_TYPE=firefox npm run test-integration
|
||
|
|
```
|
||
|
|
|
||
|
|
These tests emit their results using the TAP protocol. To get a nicer output on the console
|
||
|
|
you may want to pipe the results to `tap-nirvana`, e.g.
|
||
|
|
|
||
|
|
```sh
|
||
|
|
TEST_BROWSER_TYPE=chrome npm run test-integration | ./node_modules/.bin/tap-nirvana
|
||
|
|
```
|
||
|
|
|
||
|
|
## Writing commit messages
|
||
|
|
|
||
|
|
The subject of the pull requests and commit messages must adhere to the Angular style of
|
||
|
|
[semantic messages](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits).
|
||
|
|
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`.
|