Yet another JS code coverage tool that computes statement, line, function and branch coverage with module loader hooks to transparently add coverage when running tests. Supports all JS coverage use cases including unit tests, server side functional tests
v0.4.0 now has beautiful HTML reports. Props to Tom MacWright @tmcw for a fantastic job!
esprimaparser and the equally awesome
Supports the following use cases and more
$ npm install -g istanbul
The best way to see it in action is to run node unit tests. Say you have a test
test.js that runs all tests for your node project without coverage.
$ cd /path/to/your/source/root $ istanbul cover test.js
and this should produce a
Sample of code coverage reports produced by this tool (for this tool!):
.istanbul.yml file at the top of the source tree to configure istanbul.
istanbul help config tells you more about the config file format.
$ istanbul help
gives you detailed help on all commands.
Usage: istanbul help config | <command>`config` provides help with istanbul configurationAvailable commands are:check-coveragechecks overall/per-file coverage against thresholds from coverageJSON files. Exits 1 if thresholds are not met, 0 otherwisecover transparently adds coverage information to a node command. Savescoverage.json and reports at the end of executionhelp shows helpinstrumentinstruments a file or a directory tree and writes theinstrumented code to the desired output locationreport writes reports for coverage JSON objects produced in a previousruntest cover a node command only when npm_config_coverage is set. Use inan `npm test` script for conditional coverageCommand names can be abbreviated as long as the abbreviation is unambiguous
To get detailed help for a command and what command-line options it supports, run:
istanbul help <command>
(Most of the command line options are not covered in this document.)
$ istanbul cover my-test-script.js -- my test args # note the -- between the command name and the arguments to be passed
cover command can be used to get a coverage object and reports for any arbitrary
node script. By default, coverage information is written under
./coverage - this
can be changed using command-line options.
cover command can also be passed an optional
--handle-sigint flag to
enable writing reports when a user triggers a manual SIGINT of the process that is
being covered. This can be useful when you are generating coverage for a long lived process.
test command has almost the same behavior as the
cover command, except that
it skips coverage unless the
npm_config_coverage environment variable is set.
This command is deprecated since the latest versions of npm do not seem to
Instruments a single JS file or an entire directory tree and produces an output directory tree with instrumented code. This should not be required for running node unit tests but is useful for tests to be run on the browser.
Writes reports using
coverage*.json files as the source of coverage information.
Reports are available in multiple formats and can be individually configured
using the istanbul config file. See
istanbul help report for more details.
Checks the coverage of statements, functions, branches, and lines against the provided thresholds. Positive thresholds are taken to be the minimum percentage required and negative numbers are taken to be the number of uncovered entities allowed.
/* istanbul ignore if */or
/* istanbul ignore else */respectively.
/* istanbul ignore next */
See ignoring-code-for-coverage.md for the spec.
All the features of istanbul can be accessed as a library.
var istanbul = ;var instrumenter = ;var generatedCode = instrumenter;
var istanbul =collector =reporter =sync = false;collector;collector; //etc.reporter;reporter;reporter;
For the gory details consult the public API
Istanbul can be used in a multiple process environment by running each process with Istanbul, writing a unique coverage file for each process, and combining the results when generating reports. The method used to perform this will depend on the process forking API used. For example when using the cluster module you must setup the master to start child processes with Istanbul coverage, disable reporting, and output coverage files that include the PID in the filename. Before each run you may need to clear out the coverage data directory.
ifclusterisMaster// setup cluster if running with istanbul coverageifprocessenvrunning_under_istanbul// use coverage for forked process// disabled reporting and output for child process// enable pid in child process coverage filenamecluster;// ...// ... cluster.fork();// ...else// ... worker code
For details on the format of the coverage.json object, see here.
istanbul is licensed under the BSD License.
The following third-party libraries are used by this module:
covercommand, modeled after the
runcommand in that tool. The coverage methodology used by istanbul is quite different, however
Since all the good ones are taken. Comes from the loose association of ideas across coverage, carpet-area coverage, the country that makes good carpets and so on...