1 | ## Istanbul - a JS code coverage tool written in JS
|
2 |
|
3 | [![Build Status](https://secure.travis-ci.org/gotwarlost/istanbul.svg?branch=master)](http://travis-ci.org/gotwarlost/istanbul)
|
4 | [![Dependency Status](https://gemnasium.com/gotwarlost/istanbul.svg)](https://gemnasium.com/gotwarlost/istanbul)
|
5 | [![Coverage Status](https://img.shields.io/coveralls/gotwarlost/istanbul.svg)](https://coveralls.io/r/gotwarlost/istanbul?branch=master)
|
6 | [![bitHound Score](https://www.bithound.io/github/gotwarlost/istanbul/badges/score.svg)](https://www.bithound.io/github/gotwarlost/istanbul)
|
7 |
|
8 | [![NPM](https://nodei.co/npm/istanbul.png?downloads=true)](https://nodei.co/npm/istanbul/)
|
9 |
|
10 | **New** `v0.4.0` now has beautiful HTML reports. Props to Tom MacWright @tmcw for a fantastic job!
|
11 |
|
12 | * [Features and use cases](#features)
|
13 | * [Getting started and configuration](#getting-started)
|
14 | * [Usage on Windows](#usage-on-windows)
|
15 | * [The command line](#the-command-line)
|
16 | * [Ignoring code for coverage](#ignoring-code-for-coverage)
|
17 | * [API](#api)
|
18 | * [Changelog](https://github.com/gotwarlost/istanbul/blob/master/CHANGELOG.md)
|
19 | * [License and credits](#license)
|
20 |
|
21 | ### Features
|
22 |
|
23 | * All-javascript instrumentation library that tracks **statement, branch,
|
24 | and function coverage**.
|
25 | * **Module loader hooks** to instrument code on the fly
|
26 | * **Command line tools** to run node unit tests "with coverage turned on" and no cooperation
|
27 | whatsoever from the test runner
|
28 | * Multiple report formats: **HTML**, **LCOV**, **Cobertura** and more.
|
29 | * Ability to use as [middleware](https://github.com/gotwarlost/istanbul-middleware) when serving JS files that need to be tested on the browser.
|
30 | * Can be used on the **command line** as well as a **library**
|
31 | * Based on the awesome `esprima` parser and the equally awesome `escodegen` code generator
|
32 | * Well-tested on node (prev, current and next versions) and the browser (instrumentation library only)
|
33 |
|
34 | ### Use cases
|
35 |
|
36 | Supports the following use cases and more
|
37 |
|
38 | * transparent coverage of nodejs unit tests
|
39 | * instrumentation/ reporting of files in batch mode for browser tests
|
40 | * Server side code coverage for nodejs by embedding it as [custom middleware](https://github.com/gotwarlost/istanbul-middleware)
|
41 |
|
42 | ### Getting started
|
43 |
|
44 | $ npm install -g istanbul
|
45 |
|
46 | The best way to see it in action is to run node unit tests. Say you have a test
|
47 | script `test.js` that runs all tests for your node project without coverage.
|
48 |
|
49 | Simply:
|
50 |
|
51 | $ cd /path/to/your/source/root
|
52 | $ istanbul cover test.js
|
53 |
|
54 | and this should produce a `coverage.json`, `lcov.info` and `lcov-report/*html` under `./coverage`
|
55 |
|
56 | Sample of code coverage reports produced by this tool (for this tool!):
|
57 |
|
58 | [HTML reports](http://gotwarlost.github.com/istanbul/public/coverage/lcov-report/index.html)
|
59 |
|
60 | ### Usage on Windows
|
61 |
|
62 | Istanbul assumes that the `command` passed to it is a JS file (e.g. Jasmine, vows etc.),
|
63 | this is however not true on Windows where npm wrap bin files in a `.cmd` file.
|
64 | Since Istanbul can not parse `.cmd` files you need to reference the bin file manually.
|
65 |
|
66 | Here is an example using Jasmine 2:
|
67 |
|
68 | istanbul cover node_modules\jasmine\bin\jasmine.js
|
69 |
|
70 | In order to use this cross platform (e.i. Linux, Mac and Windows), you can insert
|
71 | the above line into the script object in your package.json file but with normal
|
72 | slash.
|
73 |
|
74 | "scripts": {
|
75 | "test": "istanbul cover node_modules/jasmine/bin/jasmine.js"
|
76 | }
|
77 |
|
78 | ### Configuring
|
79 |
|
80 | Drop a `.istanbul.yml` file at the top of the source tree to configure istanbul.
|
81 | `istanbul help config` tells you more about the config file format.
|
82 |
|
83 | ### The command line
|
84 |
|
85 | $ istanbul help
|
86 |
|
87 | gives you detailed help on all commands.
|
88 |
|
89 | ```
|
90 | Usage: istanbul help config | <command>
|
91 |
|
92 | `config` provides help with istanbul configuration
|
93 |
|
94 | Available commands are:
|
95 |
|
96 | check-coverage
|
97 | checks overall/per-file coverage against thresholds from coverage
|
98 | JSON files. Exits 1 if thresholds are not met, 0 otherwise
|
99 |
|
100 |
|
101 | cover transparently adds coverage information to a node command. Saves
|
102 | coverage.json and reports at the end of execution
|
103 |
|
104 |
|
105 | help shows help
|
106 |
|
107 |
|
108 | instrument
|
109 | instruments a file or a directory tree and writes the
|
110 | instrumented code to the desired output location
|
111 |
|
112 |
|
113 | report writes reports for coverage JSON objects produced in a previous
|
114 | run
|
115 |
|
116 |
|
117 | test cover a node command only when npm_config_coverage is set. Use in
|
118 | an `npm test` script for conditional coverage
|
119 |
|
120 |
|
121 | Command names can be abbreviated as long as the abbreviation is unambiguous
|
122 | ```
|
123 |
|
124 | To get detailed help for a command and what command-line options it supports, run:
|
125 |
|
126 | istanbul help <command>
|
127 |
|
128 | (Most of the command line options are not covered in this document.)
|
129 |
|
130 | #### The `cover` command
|
131 |
|
132 | $ istanbul cover my-test-script.js -- my test args
|
133 | # note the -- between the command name and the arguments to be passed
|
134 |
|
135 | The `cover` command can be used to get a coverage object and reports for any arbitrary
|
136 | node script. By default, coverage information is written under `./coverage` - this
|
137 | can be changed using command-line options.
|
138 |
|
139 | The `cover` command can also be passed an optional `--handle-sigint` flag to
|
140 | enable writing reports when a user triggers a manual SIGINT of the process that is
|
141 | being covered. This can be useful when you are generating coverage for a long lived process.
|
142 |
|
143 | #### The `test` command
|
144 |
|
145 | The `test` command has almost the same behavior as the `cover` command, except that
|
146 | it skips coverage unless the `npm_config_coverage` environment variable is set.
|
147 |
|
148 | **This command is deprecated** since the latest versions of npm do not seem to
|
149 | set the `npm_config_coverage` variable.
|
150 |
|
151 | #### The `instrument` command
|
152 |
|
153 | Instruments a single JS file or an entire directory tree and produces an output
|
154 | directory tree with instrumented code. This should not be required for running node
|
155 | unit tests but is useful for tests to be run on the browser.
|
156 |
|
157 | #### The `report` command
|
158 |
|
159 | Writes reports using `coverage*.json` files as the source of coverage information.
|
160 | Reports are available in multiple formats and can be individually configured
|
161 | using the istanbul config file. See `istanbul help report` for more details.
|
162 |
|
163 | #### The `check-coverage` command
|
164 |
|
165 | Checks the coverage of statements, functions, branches, and lines against the
|
166 | provided thresholds. Positive thresholds are taken to be the minimum percentage
|
167 | required and negative numbers are taken to be the number of uncovered entities
|
168 | allowed.
|
169 |
|
170 | ### Ignoring code for coverage
|
171 |
|
172 | * Skip an `if` or `else` path with `/* istanbul ignore if */` or `/* istanbul ignore else */` respectively.
|
173 | * For all other cases, skip the next 'thing' in the source with: `/* istanbul ignore next */`
|
174 |
|
175 | See [ignoring-code-for-coverage.md](ignoring-code-for-coverage.md) for the spec.
|
176 |
|
177 |
|
178 | ### API
|
179 |
|
180 | All the features of istanbul can be accessed as a library.
|
181 |
|
182 | #### Instrument code
|
183 |
|
184 | ```javascript
|
185 | var istanbul = require('istanbul');
|
186 | var instrumenter = new istanbul.Instrumenter();
|
187 |
|
188 | var generatedCode = instrumenter.instrumentSync('function meaningOfLife() { return 42; }',
|
189 | 'filename.js');
|
190 | ```
|
191 |
|
192 | #### Generate reports given a bunch of coverage JSON objects
|
193 |
|
194 | ```javascript
|
195 | var istanbul = require('istanbul'),
|
196 | collector = new istanbul.Collector(),
|
197 | reporter = new istanbul.Reporter(),
|
198 | sync = false;
|
199 |
|
200 | collector.add(obj1);
|
201 | collector.add(obj2); //etc.
|
202 |
|
203 | reporter.add('text');
|
204 | reporter.addAll([ 'lcov', 'clover' ]);
|
205 | reporter.write(collector, sync, function () {
|
206 | console.log('All reports generated');
|
207 | });
|
208 | ```
|
209 |
|
210 | For the gory details consult the [public API](http://gotwarlost.github.com/istanbul/public/apidocs/index.html)
|
211 |
|
212 |
|
213 | ### Multiple Process Usage
|
214 |
|
215 | Istanbul can be used in a multiple process environment by running each process
|
216 | with Istanbul, writing a unique coverage file for each process, and combining
|
217 | the results when generating reports. The method used to perform this will
|
218 | depend on the process forking API used. For example when using the
|
219 | [cluster module](http://nodejs.org/api/cluster.html) you must setup the master
|
220 | to start child processes with Istanbul coverage, disable reporting, and output
|
221 | coverage files that include the PID in the filename. Before each run you may
|
222 | need to clear out the coverage data directory.
|
223 |
|
224 | ```javascript
|
225 | if(cluster.isMaster) {
|
226 | // setup cluster if running with istanbul coverage
|
227 | if(process.env.running_under_istanbul) {
|
228 | // use coverage for forked process
|
229 | // disabled reporting and output for child process
|
230 | // enable pid in child process coverage filename
|
231 | cluster.setupMaster({
|
232 | exec: './node_modules/.bin/istanbul',
|
233 | args: [
|
234 | 'cover', '--report', 'none', '--print', 'none', '--include-pid',
|
235 | process.argv[1], '--'].concat(process.argv.slice(2))
|
236 | });
|
237 | }
|
238 | // ...
|
239 | // ... cluster.fork();
|
240 | // ...
|
241 | } else {
|
242 | // ... worker code
|
243 | }
|
244 | ```
|
245 |
|
246 | ### Coverage.json
|
247 |
|
248 | For details on the format of the coverage.json object, [see here](./coverage.json.md).
|
249 |
|
250 | ### License
|
251 |
|
252 | istanbul is licensed under the [BSD License](http://github.com/gotwarlost/istanbul/raw/master/LICENSE).
|
253 |
|
254 | ### Third-party libraries
|
255 |
|
256 | The following third-party libraries are used by this module:
|
257 |
|
258 | * abbrev: https://github.com/isaacs/abbrev-js - to handle command abbreviations
|
259 | * async: https://github.com/caolan/async - for parallel instrumentation of files
|
260 | * escodegen: https://github.com/Constellation/escodegen - for JS code generation
|
261 | * esprima: https://github.com/ariya/esprima - for JS parsing
|
262 | * glob: https://github.com/isaacs/node-glob - for loading and matching path expressions
|
263 | * handlebars: https://github.com/wycats/handlebars.js/ - for report template expansion
|
264 | * js-yaml: https://github.com/nodeca/js-yaml - for YAML config file load
|
265 | * mkdirp: https://github.com/substack/node-mkdirp - to create output directories
|
266 | * nodeunit: https://github.com/caolan/nodeunit - dev dependency for unit tests
|
267 | * nopt: https://github.com/isaacs/nopt - for option parsing
|
268 | * once: https://github.com/isaacs/once - to ensure callbacks are called once
|
269 | * resolve: https://github.com/substack/node-resolve - for resolving a post-require hook module name into its main file.
|
270 | * rimraf - https://github.com/isaacs/rimraf - dev dependency for unit tests
|
271 | * which: https://github.com/isaacs/node-which - to resolve a node command to a file for the `cover` command
|
272 | * wordwrap: https://github.com/substack/node-wordwrap - for prettier help
|
273 | * prettify: http://code.google.com/p/google-code-prettify/ - for syntax colored HTML reports. Files checked in under `lib/vendor/`
|
274 |
|
275 | ### Inspired by
|
276 |
|
277 | * 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.
|
278 | * cover: https://github.com/itay/node-cover - the inspiration for the `cover` command, modeled after the `run` command in that tool. The coverage methodology used by istanbul is quite different, however
|
279 |
|
280 | ### Shout out to
|
281 |
|
282 | * [mfncooper](https://github.com/mfncooper) - for great brainstorming discussions
|
283 | * [reid](https://github.com/reid), [davglass](https://github.com/davglass), the YUI dudes, for interesting conversations, encouragement, support and gentle pressure to get it done :)
|
284 |
|
285 | ### Why the funky name?
|
286 |
|
287 | Since all the good ones are taken. Comes from the loose association of ideas across
|
288 | coverage, carpet-area coverage, the country that makes good carpets and so on...
|