WebExtensions/Hacking

Code Style

WebExtension JavaScript code follows the Mozilla coding style guide, with the following differences:

• === may be used in favor of == when doing so makes sense.
• The opening brace in function statements or expressions should be on the same line as the function keyword.
• let or const should be used in place of var wherever possible.
• Function arguments and variable names should never use Hungarian Notation.
• All JavaScript files or inline <script> nodes must begin with "use strict";
• All members in multi-line object or array literals must be followed by a comma, including the last.
• Do not use proprietary, Mozilla-specific JavaScript extensions, including array and generator comprehensions, catch guard expressions, the __proto__ property, or the yield operator in non-star-functions.
• Use arrow functions in preference to function expressions where appropriate.
• Use rest parameters in preference to the arguments object where possible.
• Use default parameters for optional arguments where appropriate.
• Use spread expressions in preference to .apply() where possible.

ESLint will enforce most of these rules.

Checking your code with ESLint

All WebExtension directories in mozilla-central are configured with a set of ESLint rules, which all code is required to pass. Many of these rules help to catch serious errors, such as references to non-existent variables, or a missing trailing comma turning an array literal into an array dereference, so it is extremely important that you check you code against them before it lands.

The simplest way to check your code is using the mach eslint command. This requires that you have NPM installed (and, if you're on Linux, it may require that you fix NPM permissions).

To setup ESLint, you need to run the following once:

./mach eslint --setup

This should install ESLint, along with the necessary plugins. After that's done, you can check the files you've been working on with the following:

./mach eslint path/to/file.js

Or you can check all WebExtension code with:

./mach eslint toolkit/components/extensions browser/components/extensions toolkit/modules/addons

Integrating ESLint with your editor

Since manually checking your code isn't always practical (and is easy to forget), it's best to integrate automatic checking with your code editor. Many editors have integration plugins, or built-in support.

Some editors may need special settings to work well with our codebase. Feel free to add other editors below, as you see fit.

There is some additional useful information in the developer tools hacking section of the wiki.

Vim

The easiest way to integrate ESLint with Vim is using the Syntastic plugin.

The following assumes that you use the Vundle package manager. It should be easy enough to adapt to any other package manager you happen to prefer, though.

You should configure Syntastic roughly as follows:

" Initialize Vundle.
filetype off
call vundle#rc()

" Enable the Syntastic bundle.
Bundle 'scrooloose/syntastic'

" Enable ESLint in Syntasitc.
let g:syntastic_javascript_checkers = ['eslint']

" Enable the HTML plugin, and enable JavaScript linting for HTML files.
let g:syntastic_javascript_eslint_args = ['--plugin', 'html']
let g:syntastic_filetype_map = { "html": "javascript" }

After you've added this to your configuration (and have installed Vundle, if necessary), launch Vim and run:

:BundleInstall

This will install the Syntastic plugin. After this, you should be good to go.

Version control hooks

The mozilla-central tree contains a Mercurial plugin to automatically check any changed files, using ESLint, when you commit. This can be enabled by adding the following to your global .hgrc file, or to .hg/hgrc in your repository:

[extensions]
# Replace "~/src/mozilla-central/" with the full path to your mozilla-central repository.
mozeslint = ~/src/mozilla-central/tools/mercurial/eslintvalidate.py

On non-Windows systems, this can be achieved with:

printf '[extensions]\nmozeslint = %s/tools/mercurial/eslintvalidate.py' "$(pwd)" >>.hg/hgrc

Now Mercurial will check your code for you, and show any warnings or errors, every time you commit.

Unit tests

All WebExtension code is required to be covered by comprehensive unit tests. There is some information on MDN about the various test suites used in Mozilla code. WebExtension code primarilly uses:

Mochitests

These reside under toolkit/components/extensions/test/mochitest/, and are used to test most APIs that live in the toolkit/components/extensions/ directory.

Browser chrome mochitests

These reside under browser/components/extensions/test/browser/, and are used to test most APIs that live in the browser/components/extensions/ directory.

xpcshell tests

These reside under toolkit/components/extensions/test/xpcshell/, and are used to test low-level modules which do not require a browser UI, including those under toolkit/modules/addons/, toolkit/components/utils/simpleServices.js, and various pieces of C++ code.

Code coverage tests

Ideally, our test suite should exercise as close to 100% of our codebase as possible. 100% coverage may not always be practical, or desirable, but it's still an ideal we'd like to strive for. To that end, we run code coverage tests weekly, for the above three main test suites. If you land any code in a given week, it's best to check the end-of-week coverage tests to make sure it has adequate test coverage.

The test results are published in three separate sets:

Total code coverage

This is code coverage for all code run in either the main browser process or in a tab content process.

Main process code coverage

This is code coverage for code run in the main browser process, excluding code run only in a content process.

Content process code coverage

This is code coverage for code run in a tab content process, excluding code run only in the main browser process.

In general, the total code coverage numbers are what we focus on. However, it is extremely important code which is expected to run in both the main browser process and in a content process to be tested in both. If you know that your code falls into this category, please check that it's tested appropriately.

The above results are generated using this patch, which could generously be described as a fairly gross hack. If you'd like to run the tests yourself, you can do so with something like the following:

# Install the Instanbul code coverage tool
npm install istanbul

# Apply the code coverage patch
hg import https://people.mozilla.org/~kmaglione/webext-coverage.patch

# Instrument all WebExtension code, run the various test suites, and
# generate the coverage output files.
# Make sure that $OBJDIR points to the objdir of your current build.
./toolkit/components/extensions/test_coverage.sh $OBJDIR