Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 226 lines (147 sloc) 9.078 kB
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
1 ## Istanbul - a JS code coverage tool written in JS
dd3f2d9 @gotwarlost basic README
gotwarlost authored
2
bdc69b3 @gotwarlost Update README.md
gotwarlost authored
3 [![Build Status](https://secure.travis-ci.org/gotwarlost/istanbul.png)](http://travis-ci.org/gotwarlost/istanbul)
4 [![Dependency Status](https://gemnasium.com/gotwarlost/istanbul.png)](https://gemnasium.com/gotwarlost/istanbul)
8487e7e @gotwarlost [skip ci] add coverage badge
gotwarlost authored
5 [![Coverage Status](https://img.shields.io/coveralls/gotwarlost/istanbul.svg)](https://coveralls.io/r/gotwarlost/istanbul?branch=master)
20d1324 @gotwarlost [skip ci] fix badge
gotwarlost authored
6
502d435 @samccone Handle sigint exits
samccone authored
7 [![NPM](https://nodei.co/npm/istanbul.png?downloads=true)](https://nodei.co/npm/istanbul/)
a24f339 @gotwarlost Move status buttons to own line
gotwarlost authored
8
b02bf82 @gotwarlost [skip ci] add TOC to README - attempt 2
gotwarlost authored
9 * [Features and use cases](#features)
729349f @gotwarlost [skip ci] add TOC to README - attempt 3
gotwarlost authored
10 * [Getting started and configuration](#getting-started)
11 * [The command line](#the-command-line)
12 * [Ignoring code for coverage](#ignoring-code-for-coverage)
13 * [API](#api)
a55f13d @gotwarlost [skip ci] fix links
gotwarlost authored
14 * [Changelog](https://github.com/gotwarlost/istanbul/blob/master/CHANGELOG.md)
15 * [License and credits](#license)
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
16
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
17 ### Features
dd3f2d9 @gotwarlost basic README
gotwarlost authored
18
19 * All-javascript instrumentation library that tracks **statement, branch,
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
20 and function coverage**.
dd3f2d9 @gotwarlost basic README
gotwarlost authored
21 * **Module loader hooks** to instrument code on the fly
22 * **Command line tools** to run node unit tests "with coverage turned on" and no cooperation
23 whatsoever from the test runner
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
24 * Multiple report formats: **HTML**, **LCOV**, **Cobertura** and more.
25 * Ability to use as [middleware](https://github.com/gotwarlost/istanbul-middleware) when serving JS files that need to be tested on the browser.
dd3f2d9 @gotwarlost basic README
gotwarlost authored
26 * Can be used on the **command line** as well as a **library**
27 * Based on the awesome `esprima` parser and the equally awesome `escodegen` code generator
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
28 * Well-tested on node (prev, current and next versions) and the browser (instrumentation library only)
dd3f2d9 @gotwarlost basic README
gotwarlost authored
29
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
30 ### Use cases
31
32 Supports the following use cases and more
33
34 * transparent coverage of nodejs unit tests
35 * instrumentation/ reporting of files in batch mode for browser tests
36 * Server side code coverage for nodejs by embedding it as [custom middleware](https://github.com/gotwarlost/istanbul-middleware)
37
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
38 ### Getting started
dd3f2d9 @gotwarlost basic README
gotwarlost authored
39
40 $ npm install -g istanbul
41
42 The best way to see it in action is to run node unit tests. Say you have a test
43 script `test.js` that runs all tests for your node project without coverage.
44
45 Simply:
46
47 $ cd /path/to/your/source/root
48 $ istanbul cover test.js
49
50 and this should produce a `coverage.json`, `lcov.info` and `lcov-report/*html` under `./coverage`
51
52 Sample of code coverage reports produced by this tool (for this tool!):
53
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
54 [HTML reports](http://gotwarlost.github.com/istanbul/public/coverage/lcov-report/index.html)
dd3f2d9 @gotwarlost basic README
gotwarlost authored
55
56
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
57 ### Configuring
58
59 Drop a `.istanbul.yml` file at the top of the source tree to configure istanbul.
60 `istanbul help config` tells you more about the config file format.
dd3f2d9 @gotwarlost basic README
gotwarlost authored
61
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
62 ### The command line
dd3f2d9 @gotwarlost basic README
gotwarlost authored
63
64 $ istanbul help
65
66 gives you detailed help on all commands.
67
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
68 ```
69 Usage: istanbul help config | <command>
70
71 `config` provides help with istanbul configuration
dd3f2d9 @gotwarlost basic README
gotwarlost authored
72
b3483fa @gotwarlost update help for instrument command, update README for changelog and u…
gotwarlost authored
73 Available commands are:
dd3f2d9 @gotwarlost basic README
gotwarlost authored
74
b3483fa @gotwarlost update help for instrument command, update README for changelog and u…
gotwarlost authored
75 check-coverage
01f60f0 @ryan-roemer Add per-file checks, configuration support, and CI fixes.
ryan-roemer authored
76 checks overall/per-file coverage against thresholds from coverage
77 JSON files. Exits 1 if thresholds are not met, 0 otherwise
dd3f2d9 @gotwarlost basic README
gotwarlost authored
78
79
b3483fa @gotwarlost update help for instrument command, update README for changelog and u…
gotwarlost authored
80 cover transparently adds coverage information to a node command. Saves
81 coverage.json and reports at the end of execution
dd3f2d9 @gotwarlost basic README
gotwarlost authored
82
83
b3483fa @gotwarlost update help for instrument command, update README for changelog and u…
gotwarlost authored
84 help shows help
dd3f2d9 @gotwarlost basic README
gotwarlost authored
85
b3483fa @gotwarlost update help for instrument command, update README for changelog and u…
gotwarlost authored
86
87 instrument
88 instruments a file or a directory tree and writes the
89 instrumented code to the desired output location
90
91
92 report writes reports for coverage JSON objects produced in a previous
93 run
94
95
96 test cover a node command only when npm_config_coverage is set. Use in
97 an `npm test` script for conditional coverage
98
99
100 Command names can be abbreviated as long as the abbreviation is unambiguous
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
101 ```
dd3f2d9 @gotwarlost basic README
gotwarlost authored
102
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
103 #### The `cover` command
dd3f2d9 @gotwarlost basic README
gotwarlost authored
104
105 $ istanbul cover my-test-script.js -- my test args
106 # note the -- between the command name and the arguments to be passed
107
108 The `cover` command can be used to get a coverage object and reports for any arbitrary
109 node script. By default, coverage information is written under `./coverage` - this
110 can be changed using command-line options.
111
01f60f0 @ryan-roemer Add per-file checks, configuration support, and CI fixes.
ryan-roemer authored
112 The `cover` command can also be passed an optional `--handle-sigint` flag to
113 enable writing reports when a user triggers a manual SIGINT of the process that is
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
114 being covered. This can be useful when you are generating coverage for a long lived process.
502d435 @samccone Handle sigint exits
samccone authored
115
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
116 #### The `test` command
dd3f2d9 @gotwarlost basic README
gotwarlost authored
117
118 The `test` command has almost the same behavior as the `cover` command, except that
119 it skips coverage unless the `npm_config_coverage` environment variable is set.
120
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
121 **This command is deprecated** since the latest versions of npm do not seem to
122 set the `npm_config_coverage` variable.
dd3f2d9 @gotwarlost basic README
gotwarlost authored
123
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
124 #### The `instrument` command
dd3f2d9 @gotwarlost basic README
gotwarlost authored
125
01f60f0 @ryan-roemer Add per-file checks, configuration support, and CI fixes.
ryan-roemer authored
126 Instruments a single JS file or an entire directory tree and produces an output
127 directory tree with instrumented code. This should not be required for running node
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
128 unit tests but is useful for tests to be run on the browser.
b3483fa @gotwarlost update help for instrument command, update README for changelog and u…
gotwarlost authored
129
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
130 #### The `report` command
b3483fa @gotwarlost update help for instrument command, update README for changelog and u…
gotwarlost authored
131
01f60f0 @ryan-roemer Add per-file checks, configuration support, and CI fixes.
ryan-roemer authored
132 Writes reports using `coverage*.json` files as the source of coverage information.
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
133 Reports are available in multiple formats and can be individually configured
134 using the istanbul config file. See `istanbul help report` for more details.
dd3f2d9 @gotwarlost basic README
gotwarlost authored
135
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
136 #### The `check-coverage` command
8a04104 @markyen Unifies the documentation in the README and usage help
markyen authored
137
138 Checks the coverage of statements, functions, branches, and lines against the
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
139 provided thresholds. Positive thresholds are taken to be the minimum percentage
8a04104 @markyen Unifies the documentation in the README and usage help
markyen authored
140 required and negative numbers are taken to be the number of uncovered entities
141 allowed.
142
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
143 ### Ignoring code for coverage
144
145 * Skip an `if` or `else` path with `/* istanbul ignore if */` or `/* istanbul ignore else */` respectively.
146 * For all other cases, skip the next 'thing' in the source with: `/* istanbul ignore next */`
147
148 See [ignoring-code-for-coverage.md](ignoring-code-for-coverage.md) for the spec.
149
150
151 ### API
dd3f2d9 @gotwarlost basic README
gotwarlost authored
152
f225e1f @gotwarlost [skip ci] add quickstart API
gotwarlost authored
153 All the features of istanbul can be accessed as a library.
01f60f0 @ryan-roemer Add per-file checks, configuration support, and CI fixes.
ryan-roemer authored
154
f225e1f @gotwarlost [skip ci] add quickstart API
gotwarlost authored
155 #### Instrument code
156
157 ```javascript
8a83fe8 @robatron "Instrument code" API example correction
robatron authored
158 var istanbul = require('istanbul');
159 var instrumenter = new istanbul.Instrumenter();
01f60f0 @ryan-roemer Add per-file checks, configuration support, and CI fixes.
ryan-roemer authored
160
d55a2c9 @gotwarlost [skip ci] add quickstart API
gotwarlost authored
161 var generatedCode = instrumenter.instrumentSync('function meaningOfLife() { return 42; }',
162 'filename.js');
f225e1f @gotwarlost [skip ci] add quickstart API
gotwarlost authored
163 ```
164
165 #### Generate reports given a bunch of coverage JSON objects
166
167 ```javascript
01f60f0 @ryan-roemer Add per-file checks, configuration support, and CI fixes.
ryan-roemer authored
168 var istanbul = require('istanbul'),
f225e1f @gotwarlost [skip ci] add quickstart API
gotwarlost authored
169 collector = new istanbul.Collector(),
170 reporter = new istanbul.Reporter(),
171 sync = false;
172
173 collector.add(obj1);
174 collector.add(obj2); //etc.
175
176 reporter.add('text');
177 reporter.addAll([ 'lcov', 'clover' ]);
3493a3e @wlabranche Update README.md
wlabranche authored
178 reporter.write(collector, sync, function () {
f225e1f @gotwarlost [skip ci] add quickstart API
gotwarlost authored
179 console.log('All reports generated');
180 });
181 ```
182
183 For the gory details consult the [public API](http://gotwarlost.github.com/istanbul/public/apidocs/index.html)
184
dd3f2d9 @gotwarlost basic README
gotwarlost authored
185
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
186 ### License
dd3f2d9 @gotwarlost basic README
gotwarlost authored
187
188 istanbul is licensed under the [BSD License](http://github.com/gotwarlost/istanbul/raw/master/LICENSE).
189
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
190 ### Third-party libraries
dd3f2d9 @gotwarlost basic README
gotwarlost authored
191
192 The following third-party libraries are used by this module:
193
194 * abbrev: https://github.com/isaacs/abbrev-js - to handle command abbreviations
195 * async: https://github.com/caolan/async - for parallel instrumentation of files
196 * escodegen: https://github.com/Constellation/escodegen - for JS code generation
197 * esprima: https://github.com/ariya/esprima - for JS parsing
198 * fileset: https://github.com/mklabs/node-fileset - for loading and matching path expressions
199 * handlebars: https://github.com/wycats/handlebars.js/ - for report template expansion
322d765 @gotwarlost Add license blurb for new files, add new third-party libs to README
gotwarlost authored
200 * js-yaml: https://github.com/nodeca/js-yaml - for YAML config file load
dd3f2d9 @gotwarlost basic README
gotwarlost authored
201 * mkdirp: https://github.com/substack/node-mkdirp - to create output directories
202 * nodeunit: https://github.com/caolan/nodeunit - dev dependency for unit tests
203 * nopt: https://github.com/isaacs/nopt - for option parsing
888a9ba @gotwarlost Remove custom code and use the `once` library instead
gotwarlost authored
204 * once: https://github.com/isaacs/once - to ensure callbacks are called once
6b57c88 @gotwarlost update README, version
gotwarlost authored
205 * resolve: https://github.com/substack/node-resolve - for resolving a post-require hook module name into its main file.
dd3f2d9 @gotwarlost basic README
gotwarlost authored
206 * rimraf - https://github.com/isaacs/rimraf - dev dependency for unit tests
207 * which: https://github.com/isaacs/node-which - to resolve a node command to a file for the `cover` command
208 * wordwrap: https://github.com/substack/node-wordwrap - for prettier help
205bdad @gotwarlost Attribute prettify as a third-party dependency
gotwarlost authored
209 * prettify: http://code.google.com/p/google-code-prettify/ - for syntax colored HTML reports. Files checked in under `lib/vendor/`
dd3f2d9 @gotwarlost basic README
gotwarlost authored
210
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
211 ### Inspired by
dd3f2d9 @gotwarlost basic README
gotwarlost authored
212
55210f2 Fix word salad
ananthk authored
213 * 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.
dd3f2d9 @gotwarlost basic README
gotwarlost authored
214 * 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
215
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
216 ### Shout out to
dd3f2d9 @gotwarlost basic README
gotwarlost authored
217
218 * [mfncooper](https://github.com/mfncooper) - for great brainstorming discussions
219 * [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 :)
220
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
221 ### Why the funky name?
dd3f2d9 @gotwarlost basic README
gotwarlost authored
222
01f60f0 @ryan-roemer Add per-file checks, configuration support, and CI fixes.
ryan-roemer authored
223 Since all the good ones are taken. Comes from the loose association of ideas across
220b286 @gotwarlost [skip ci] update readme
gotwarlost authored
224 coverage, carpet-area coverage, the country that makes good carpets and so on...
cb2021d @gotwarlost [skip ci] add TOC to README
gotwarlost authored
225
Something went wrong with that request. Please try again.