Repository files navigation

Archive notice: This repo has been inactive for 7 years and is now archived.Please usethe supported version instead.

Deprecation Notice: this version ofistanbul is deprecated, we will not belanding pull requests or releasing new versions. But don't worry, theIstanbul 2.0API is now available and is being actively developedin the newistanbuljs organization.

Newv0.4.0 now has beautiful HTML reports. Props to Tom MacWright @tmcw for a fantastic job!

• Features and use cases
• Getting started and configuration
• Usage on Windows
• The command line
• Ignoring code for coverage
• API
• Changelog
• License and credits

• All-javascript instrumentation library that tracksstatement, branch,and function coverage.
• Module loader hooks to instrument code on the fly
• Command line tools to run node unit tests "with coverage turned on" and no cooperationwhatsoever from the test runner
• Multiple report formats:HTML,LCOV,Cobertura and more.
• Ability to use asmiddleware when serving JS files that need to be tested on the browser.
• Can be used on thecommand line as well as alibrary
• Based on the awesomeesprima parser and the equally awesomeescodegen code generator
• Well-tested on node (prev, current and next versions) and the browser (instrumentation library only)

Supports the following use cases and more

• transparent coverage of nodejs unit tests
• instrumentation/ reporting of files in batch mode for browser tests
• Server side code coverage for nodejs by embedding it ascustom middleware

$ npm install -g istanbul

The best way to see it in action is to run node unit tests. Say you have a testscripttest.js that runs all tests for your node project without coverage.

Simply:

$ cd /path/to/your/source/root$ istanbul cover test.js

and this should produce acoverage.json,lcov.info andlcov-report/*html under./coverage

Sample of code coverage reports produced by this tool (for this tool!):

HTML reports

Istanbul assumes that thecommand passed to it is a JS file (e.g. Jasmine, vows etc.),this is however not true on Windows where npm wrap bin files in a.cmd file.Since Istanbul can not parse.cmd files you need to reference the bin file manually.

Here is an example using Jasmine 2:

istanbul cover node_modules\jasmine\bin\jasmine.js

In order to use this cross platform (e.i. Linux, Mac and Windows), you can insertthe above line into the script object in your package.json file but with normalslash.

"scripts": {    "test": "istanbul cover node_modules/jasmine/bin/jasmine.js"}

Drop a.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-coverage              checks overall/per-file coverage against thresholds from coverage              JSON files. Exits 1 if thresholds are not met, 0 otherwise      cover   transparently adds coverage information to a node command. Saves              coverage.json and reports at the end of execution      help    shows help      instrument              instruments a file or a directory tree and writes the              instrumented code to the desired output location      report  writes reports for coverage JSON objects produced in a previous              run      test    cover a node command only when npm_config_coverage is set. Use in              an `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

Thecover command can be used to get a coverage object and reports for any arbitrarynode script. By default, coverage information is written under./coverage - thiscan be changed using command-line options.

Thecover command can also be passed an optional--handle-sigint flag toenable writing reports when a user triggers a manual SIGINT of the process that isbeing covered. This can be useful when you are generating coverage for a long lived process.

Thetest command has almost the same behavior as thecover command, except thatit skips coverage unless thenpm_config_coverage environment variable is set.

This command is deprecated since the latest versions of npm do not seem toset thenpm_config_coverage variable.

Instruments a single JS file or an entire directory tree and produces an outputdirectory tree with instrumented code. This should not be required for running nodeunit tests but is useful for tests to be run on the browser.

Writes reports usingcoverage*.json files as the source of coverage information.Reports are available in multiple formats and can be individually configuredusing the istanbul config file. Seeistanbul help report for more details.

Checks the coverage of statements, functions, branches, and lines against theprovided thresholds. Positive thresholds are taken to be the minimum percentagerequired and negative numbers are taken to be the number of uncovered entitiesallowed.

• Skip anif orelse path with/* istanbul ignore if */ or/* istanbul ignore else */ respectively.
• For all other cases, skip the next 'thing' in the source with:/* istanbul ignore next */

Seeignoring-code-for-coverage.md for the spec.

All the features of istanbul can be accessed as a library.

varistanbul=require('istanbul');varinstrumenter=newistanbul.Instrumenter();vargeneratedCode=instrumenter.instrumentSync('function meaningOfLife() { return 42; }','filename.js');

varistanbul=require('istanbul'),collector=newistanbul.Collector(),reporter=newistanbul.Reporter(),sync=false;collector.add(obj1);collector.add(obj2);//etc.reporter.add('text');reporter.addAll(['lcov','clover']);reporter.write(collector,sync,function(){console.log('All reports generated');});

For the gory details consult thepublic API

Istanbul can be used in a multiple process environment by running each processwith Istanbul, writing a unique coverage file for each process, and combiningthe results when generating reports. The method used to perform this willdepend on the process forking API used. For example when using thecluster module you must setup the masterto start child processes with Istanbul coverage, disable reporting, and outputcoverage files that include the PID in the filename. Before each run you mayneed to clear out the coverage data directory.

if(cluster.isMaster){// setup cluster if running with istanbul coverageif(process.env.running_under_istanbul){// use coverage for forked process// disabled reporting and output for child process// enable pid in child process coverage filenamecluster.setupMaster({exec:'./node_modules/.bin/istanbul',args:['cover','--report','none','--print','none','--include-pid',process.argv[1],'--'].concat(process.argv.slice(2))});}// ...// ... cluster.fork();// ...}else{// ... worker code}

For details on the format of the coverage.json object,see here.

istanbul is licensed under theBSD License.

The following third-party libraries are used by this module:

• abbrev:https://github.com/isaacs/abbrev-js - to handle command abbreviations
• async:https://github.com/caolan/async - for parallel instrumentation of files
• escodegen:https://github.com/Constellation/escodegen - for JS code generation
• esprima:https://github.com/ariya/esprima - for JS parsing
• glob:https://github.com/isaacs/node-glob - for loading and matching path expressions
• handlebars:https://github.com/wycats/handlebars.js/ - for report template expansion
• js-yaml:https://github.com/nodeca/js-yaml - for YAML config file load
• mkdirp:https://github.com/substack/node-mkdirp - to create output directories
• nodeunit:https://github.com/caolan/nodeunit - dev dependency for unit tests
• nopt:https://github.com/isaacs/nopt - for option parsing
• once:https://github.com/isaacs/once - to ensure callbacks are called once
• resolve:https://github.com/substack/node-resolve - for resolving a post-require hook module name into its main file.
• rimraf -https://github.com/isaacs/rimraf - dev dependency for unit tests
• which:https://github.com/isaacs/node-which - to resolve a node command to a file for thecover command
• wordwrap:https://github.com/substack/node-wordwrap - for prettier help
• prettify:http://code.google.com/p/google-code-prettify/ - for syntax colored HTML reports. Files checked in underlib/vendor/

• YUI test coverage -https://github.com/yui/yuitest - the grand-daddy of JS coverage tools. Istanbul has been specifically designed to offer an alternative to this library with an easy migration path.
• cover:https://github.com/itay/node-cover - the inspiration for thecover command, modeled after therun command in that tool. The coverage methodology used by istanbul is quite different, however

• mfncooper - for great brainstorming discussions
• reid,davglass, the YUI dudes, for interesting conversations, encouragement, support and gentle pressure to get it done :)

Since all the good ones are taken. Comes from the loose association of ideas acrosscoverage, carpet-area coverage, the country that makes good carpets and so on...