Use cases

instrumentation of files in batch mode for browser tests (using yeti for example)

Server side code coverage for nodejs by embedding it as custom middleware

The command line

$ istanbul help

gives you detailed help on all commands.

Usage: istanbul help <command>
Available commands are:
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 coverage
Command names can be abbreviated as long as the abbreviation is unambiguous

The cover command

$ istanbul cover my-test-script.js -- my test args
# note the -- between the command name and the arguments to be passed

The 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.

The test command

The 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 helps you set up conditional coverage for tests. In this case you would
have a package.json that looks as follows.

Note: This needs node 0.6 or better to work. npm for node 0.4.x does
not support the --coverage flag.

The instrument command

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 (using yeti for example).

The report command

Writes reports using coverage*.json files as the source of coverage information. Reports are available in HTML and LCOV formats. Additional report formats may be plugged in at the library level.

Library usage

All the features of istanbul can be accessed as a library using its public API

Changelog

v0.1.19 : make all hooking non-destructive in that already loaded modules are never reloaded.
Add self-test mode so that already loaded istanbul modules can be unloaded prior to hooking.

v0.1.18 : Add option to hook in non-destructive mode; i.e. the require cache is not unloaded when hooking

v0.1.17 : Export some more objects; undocumented for now

v0.1.16 : Fix npm keywords for istanbul which expects an array of strings but was being fed a single string with keywords instead

v0.1.15 : Add the 'check-coverage' command so that Istanbul can be used as a posttest script to enforce minimum coverage