Accountapprovers, confirm
126
edits
Changes
Add code coverage docs
WebExtension JavaScript code follows the Mozilla
with the following differences:
* All JavaScript files or inline <code><script></code> nodes must begin with <code>"use strict";</code>
* 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, <code>catch</code> guard expressions, the <code>__proto__</code> property, or the <code>yield</code> operator in non-star-functions.
* Use [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions arrow functions] in preference to function expressions where appropriate.
* Use [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters rest parameters] in preference to the <code>arguments</code> object where possible.
* Use [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters default parameters] for optional arguments where appropriate.
* Use [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator spread expressions] in preference to <code>.apply()</code> where possible.
ESLint will enforce most of these rules.
All WebExtension directories in <code>mozilla-central</code> 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 <code>mach eslint</code> command. This requires that you have [[https://docs.npmjs.com/ NPM]] installed (and, if you're on Linux, it may require that you [[https://docs.npmjs.com/getting-started/fixing-npm-permissions fix NPM permissions]]).
To setup ESLint, you need to run the following once:
=== 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 [[http://eslint.org/docs/user-guide/integrations.html 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 [[DevTools/CodingStandards#JS_linting_with_ESLint|developer tools hacking]] section of the wiki.
==== Vim ====
The easiest way to integrate ESLint with Vim is using the [[https://github.com/scrooloose/syntastic Syntastic plugin]].
The following assumes that you use the [[https://github.com/VundleVim/Vundle.vim 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:
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 [https://developer.mozilla.org/en-US/docs/Mozilla/QA/Automated_testing some information on MDN] about the various test suites used in Mozilla code. WebExtension code primarilly uses:
;Mochitests
: These reside under <code>toolkit/components/extensions/test/mochitest/</code>, and are used to test most APIs that live in the <code>toolkit/components/extensions/</code> directory.
;Browser chrome mochitests
: These reside under <code>browser/components/extensions/test/browser/</code>, and are used to test most APIs that live in the <code>browser/components/extensions/</code> directory.
;xpcshell tests
: These reside under <code>toolkit/components/extensions/test/xpcshell/</code>, and are used to test low-level modules which do not require a browser UI, including those under <code>toolkit/modules/addons/</code>, <code>toolkit/components/utils/simpleServices.js</code>, 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:
;[https://people.mozilla.org/~kmaglione/webextension-test-coverage/ Total code coverage]
: This is code coverage for all code run in either the main browser process or in a tab content process.
;[https://people.mozilla.org/~kmaglione/webextension-test-coverage/default/ Main process code coverage]
: This is code coverage for code run in the main browser process, excluding code run only in a content process.
;[https://people.mozilla.org/~kmaglione/webextension-test-coverage/content/ 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 [https://people.mozilla.org/~kmaglione/webext-coverage.patch 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
