Almost config-free Istanbul code coverage reporter for Mocha usage in Grunt
npm install grunt mocha istanbul --save-dev
npm install grunt-mocha-istanbul --save-dev
Peer dependencies for
istanbul have been removed. You should
npm install the following modules yourself:
istanbul(or a compatible module; see
npm version < 3, you will need to install
grunt as well.
Since Istanbul has 2 versions (ES5 and ES6/harmony), it's up to you to install the desired version of Istanbul, it's now defined as a a peer dependency.
Introduced new task
istanbul_check_coverage to enable coverage checking on more than one test run. See below for example.
mocha_istanbul_checkwas removed and became part of the options under the
Although it's intended for use with Istanbul, you can freely
use this task with other command line compatible tool, by changing the
scriptPath option, such as:
Most of the options that you pass to mocha is available in
gruntinitConfigmocha_istanbul:coverage:src: 'test' // a folder works nicelyoptions:mask: '*.spec.js'coverageSpecial:src: 'testSpecial/*/*.js' 'testUnique/*/*.js' // specifying file patterns works as welloptions:coverageFolder: 'coverageSpecial'mask: '*.spec.js'mochaOptions: '--harmony''--async-only' // any extra optionsistanbulOptions: '--harmony''--handle-sigint'coveralls:src: 'test' 'testSpecial' 'testUnique' // multiple folders also worksoptions:coverage:true // this will make the grunt.event.on('coverage') event listener to be triggeredcheck:lines: 75statements: 75root: './lib' // define where the cover task should consider the root of libraries that are covered by testsreportFormats: 'cobertura''lcovonly'istanbul_check_coverage:default:options:coverageFolder: 'coverage*' // will check both coverage folders and merge the coverage resultscheck:lines: 80statements: 80;grunteventon'coverage'// Check below on the section "The coverage event"done;;gruntloadNpmTasks'grunt-mocha-istanbul';gruntregisterTask'coveralls' 'mocha_istanbul:coveralls';gruntregisterTask'coverage' 'mocha_istanbul:coverage';;
If there's a
mocha.opts file inside the first
src folder or file defined, it will warn if you are overwriting any options.
Coverage is written to
coverage folder by default, in the same level as the
check will fail the build if the thresholds are not met. It's a great possibility for CI-builds.
Mochas parameters, check [http://visionmedia.github.io/mocha/#usage]
An array of strings, any additional mocha parameters, manually set. Eg.:
An array of strings, any additional istanbul parameters, manually set. Eg.:
Allows to override the default istanbul path to use another coverage library, such as ibrik. Need to set the full path to the bin (script that accepts stdin arguments) and is compatible with
Setting this to true makes the task emit a grunt event
coverage, that will contain the lcov data from
the file, containing the following callback
function(lcovcontent, done), and you must manually call
done() when you are finished, else the grunt task will HANG, and won't allow any other tasks to finish. See more information below
Spits out the command line that would be called, just to make sure everything is alright
Setting this exclude files from coverage report, check
istanbul help cover. You may use glob matching in here.
The mask for the tests to be ran. By default, mocha will execute the
test folder and all test files. Will override any files specified in
src and instead use the mask on those files' folders.
Suppresses the output from Mocha and Istanbul
Name of the output of the coverage folder
Name of report formats. You can specify more than one. If you intend to use the
coverage option to
true or do any checks, you must add:
['yourformat','lcovonly'], since it's needed for the
file to be created.
html - produces a bunch of HTML files with annotated source codelcovonly - produces an lcov.info filelcov - produces html + lcov files. This is the default formatcobertura - produces a cobertura-coverage.xml file for easy Hudson integrationtext-summary - produces a compact text summary of coverage, typically to consoletext - produces a detailed text table with coverage for all filesteamcity - produces service messages to report code coverage to TeamCity
The root path to look for files to instrument, defaults to
.. Can help to exclude directories that are not
part of the code whose coverage should be checked.
The type of report to print to console. Can be one of 'summary', 'detail', 'both', or 'none'. By default, Istanbul will print the 'summary' report.
Number of statements threshold to consider the coverage valid
Number of lines threshold to consider the coverage valid
Number of branches threshold to consider the coverage valid
Number of functions threshold to consider the coverage valid
When you set the option
true, you'll receive the
coverage/lcov.info file contents:
grunteventon'coverage'console.loglcov;done; // or done(false); in case of error;
This is mainly useful so you can send it to, for example, coveralls (using coveralls):
grunteventon'coverage'require'coveralls'handleInputlcovif errreturn doneerr;done;;;
This way, Travis-CI can send the Istanbul generated LCOV directly to Coveralls.io website in this example, but you could create any transform for Jenkins, TeamCity, Hudson, etc.