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