1 | # nyc
|
2 |
|
3 | [![Build Status](https://travis-ci.org/istanbuljs/nyc.svg?branch=master)](https://travis-ci.org/istanbuljs/nyc)
|
4 | [![Coverage Status](https://coveralls.io/repos/istanbuljs/nyc/badge.svg?branch=)](https://coveralls.io/r/istanbuljs/nyc?branch=master)
|
5 | [![NPM version](https://img.shields.io/npm/v/nyc.svg)](https://www.npmjs.com/package/nyc)
|
6 | [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
|
7 | [![community slack](https://devtoolscommunity.herokuapp.com/badge.svg)](http://devtoolscommunity.herokuapp.com)
|
8 |
|
9 | _Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com)_.
|
10 |
|
11 | Istanbul's state of the art command line interface, with support for:
|
12 |
|
13 | * applications that spawn subprocesses.
|
14 | * source mapped coverage of Babel and TypeScript projects
|
15 |
|
16 | ## Installation & Usage
|
17 |
|
18 | Use your package manager to add it as a dev dependency: `npm i -D nyc` or `yarn add -D nyc`.
|
19 | You can use nyc to call npm scripts (assuming they don't already have nyc executed in them), like so (replace `mocha` with your test runner everywhere you see it):
|
20 | ```json
|
21 | {
|
22 | "scripts": {
|
23 | "test": "mocha",
|
24 | "coverage": "nyc npm run test"
|
25 | }
|
26 | }
|
27 | ```
|
28 |
|
29 | You can use also `npx` instead of installing nyc as a dependency, but you might get updates you are not ready for; to get around this, pin to a specific major version by specifying, e.g. `nyc@14`.
|
30 |
|
31 | ```json
|
32 | {
|
33 | "scripts": {
|
34 | "test": "npx nyc@latest mocha"
|
35 | }
|
36 | }
|
37 | ```
|
38 |
|
39 | This is a good way of testing upcoming releases of nyc, usually on the `next` tag.
|
40 |
|
41 | **Note**: If you use [`jest`](https://npm.im/jest) or [`tap`](https://www.node-tap.org/), you do not need to install `nyc`.
|
42 | Those runners already have the IstanbulJS libraries to provide coverage for you.
|
43 | Follow their documentation to enable and configure coverage reporting.
|
44 |
|
45 | ## Configuring `nyc`
|
46 |
|
47 | nyc accepts a wide variety of configuration arguments, run `npx nyc --help` for thorough documentation.
|
48 |
|
49 | Configuration arguments on the command-line should be provided prior to the program that nyc is executing.
|
50 | As an example, the following command executes `ava`, and indicates to nyc that it should output both an `lcov` (`lcov.info` + html report) and a `text-summary` coverage report.
|
51 |
|
52 | ```shell
|
53 | nyc --reporter=lcov --reporter=text-summary ava
|
54 | ```
|
55 |
|
56 | ### Babel projects
|
57 |
|
58 | Please start with the pre-configured [`@istanbuljs/nyc-config-babel`] preset.
|
59 | You can add your custom configuration options as shown below.
|
60 |
|
61 | ### TypeScript projects
|
62 |
|
63 | Please start with the pre-configured [`@istanbuljs/nyc-config-typescript`](https://www.npmjs.com/package/@istanbuljs/nyc-config-typescript) preset.
|
64 |
|
65 | #### Adding your overrides
|
66 |
|
67 | nyc allows you to inherit other configurations using the key `extends` in the `package.json` stanza, `.nycrc`, or YAML files.
|
68 | You can then add the specific configuration options you want that aren't in that particular shared config, e.g.
|
69 | ```json
|
70 | {
|
71 | "nyc": {
|
72 | "extends": "@istanbuljs/nyc-config-typescript",
|
73 | "all": true,
|
74 | "check-coverage": true
|
75 | }
|
76 | }
|
77 | ```
|
78 |
|
79 | ### Configuration files
|
80 |
|
81 | Any configuration options that can be set via the command line can also be specified in the `nyc` stanza of your package.json, or within a seperate configuration file - a variety of flavors are available:
|
82 |
|
83 | | File name | File Association |
|
84 | |-----------------|------------------|
|
85 | | `.nycrc` | JSON |
|
86 | | `.nycrc.json` | JSON |
|
87 | | `.nycrc.yaml` | YAML |
|
88 | | `.nycrc.yml` | YAML |
|
89 | | `nyc.config.js` | CommonJS export |
|
90 |
|
91 | ### Common Configuration Options
|
92 |
|
93 | See `nyc --help` for all options available.
|
94 | You can set these in any of the files listed above, or from the command line.
|
95 | This table is a quick TLDR for the rest of this readme and there are more advanced docs available.
|
96 |
|
97 | | Option name | Description | Type | Default |
|
98 | | ----------- | ----------- | ---- | ------- |
|
99 | | `all` | Whether or not to instrument all files (not just the ones touched by your test suite) | `Boolean` | `false` |
|
100 | | `check-coverage` | Check whether coverage is within thresholds, fail if not | `Boolean` | `false` |
|
101 | | `extension` | List of extensions that nyc should attempt to handle in addition to `.js` | `Array<String>` | `['.js']` |
|
102 | | `include` | See [selecting files for coverage] for more info | `Array<String>` | `['**']`|
|
103 | | `exclude` | See [selecting files for coverage] for more info | `Array<String>` | [list](https://github.com/istanbuljs/istanbuljs/blob/master/packages/test-exclude/default-exclude.js) |
|
104 | | `reporter` | [Coverage reporters to use](https://istanbul.js.org/docs/advanced/alternative-reporters/) | `Array<String>` | `['text']` |
|
105 | | `report-dir` | Where to put the coverage report files | `String` | `./coverage` |
|
106 | | `skip-full` | Don't show files with 100% statement, branch, and function coverage | `Boolean` | `false` |
|
107 | | `temp-dir` | Directory to output raw coverage information to | `String` | `./.nyc_output` |
|
108 |
|
109 | Configuration can also be provided by `nyc.config.js` if programmed logic is required:
|
110 | ```js
|
111 | 'use strict';
|
112 | const {defaultExclude} = require('test-exclude');
|
113 | const isWindows = require('is-windows');
|
114 |
|
115 | let platformExclude = [
|
116 | isWindows() ? 'lib/posix.js' : 'lib/win32.js'
|
117 | ];
|
118 |
|
119 | module.exports = {
|
120 | exclude: platformExclude.concat(defaultExclude)
|
121 | };
|
122 | ```
|
123 |
|
124 | ### Publish and reuse your nyc configuration(s)
|
125 |
|
126 | To publish and reuse your own `nyc` configuration, simply create an npm module that exports your JSON config (via [`index.json`](https://github.com/istanbuljs/istanbuljs/blob/master/packages/nyc-config-typescript/) or a CJS [`index.js`](https://github.com/istanbuljs/istanbuljs/blob/master/packages/nyc-config-hook-run-in-this-context/)).
|
127 |
|
128 | A more advanced use case would be to combine multiple shared configs in a `nyc.config.js` file:
|
129 | ```js
|
130 | const babelConfig = require('@istanbuljs/nyc-config-babel');
|
131 | const hookRunInThisContextConfig = require('@istanbuljs/nyc-config-hook-run-in-this-context');
|
132 |
|
133 | module.exports = {
|
134 | ...babelConfig,
|
135 | ...hookRunInThisContextConfig,
|
136 | all: true,
|
137 | 'check-coverage': true
|
138 | };
|
139 | ```
|
140 |
|
141 | ## Selecting files for coverage
|
142 |
|
143 | By default, nyc only collects coverage for source files that are visited during a test.
|
144 | It does this by watching for files that are `require()`'d during the test.
|
145 | When a file is `require()`'d, nyc creates and returns an instrumented version of the source, rather than the original.
|
146 | Only source files that are visited during a test will appear in the coverage report and contribute to coverage statistics.
|
147 |
|
148 | nyc will instrument all files if the `--all` flag is set or if running `nyc instrument`.
|
149 | In this case all files will appear in the coverage report and contribute to coverage statistics.
|
150 |
|
151 | nyc will only collect coverage for files that are located under `cwd`, and then only `*.js` files or files with extensions listed in the `extension` array.
|
152 |
|
153 | You can reduce the set of instrumented files by adding `include` and `exclude` filter arrays to your config.
|
154 | These allow you to shape the set of instrumented files by specifying glob patterns that can filter files from the default instrumented set.
|
155 | The `exclude` array may also use exclude negated glob patterns, these are specified with a `!` prefix, and can restore sub-paths of excluded paths.
|
156 |
|
157 | Globs are matched using [minimatch](https://www.npmjs.com/package/minimatch).
|
158 |
|
159 | We use the following process to remove files from consideration:
|
160 | 1. Limit the set of instrumented files to those files in paths listed in the `include` array.
|
161 | 2. Remove any files that are found in the `exclude` array.
|
162 | 3. Restore any exclude negated files that have been excluded in step 2.
|
163 |
|
164 | ### Using include and exclude arrays
|
165 |
|
166 | If there are paths specified in the `include` array, then the set of instrumented files will be limited to eligible files found in those paths.
|
167 | If the `include` array is left undefined all eligible files will be included, equivalent to setting `include: ['**']`.
|
168 | Multiple `include` globs can be specified on the command line, each must follow a `--include`, `-n` switch.
|
169 |
|
170 | If there are paths specified in the `exclude` array, then the set of instrumented files will not feature eligible files found in those paths.
|
171 | You can also specify negated paths in the `exclude` array, by prefixing them with a `!`.
|
172 | Negated paths can restore paths that have been already been excluded in the `exclude` array.
|
173 | Multiple `exclude` globs can be specified on the command line, each must follow a `--exclude`, `-x` switch.
|
174 |
|
175 | The default `exclude` list is defined in the [test-exclude module](https://github.com/istanbuljs/istanbuljs/blob/master/packages/test-exclude/default-exclude.js).
|
176 | Specifying your own exclude property completely replaces these defaults.
|
177 |
|
178 | For example, the following config will collect coverage for every file in the `src` directory regardless of whether it is `require()`'d in a test.
|
179 | It will also exclude any files with the extension `.spec.js`.
|
180 |
|
181 | ```json
|
182 | {
|
183 | "nyc": {
|
184 | "all": true,
|
185 | "include": [
|
186 | "src/**/*.js"
|
187 | ],
|
188 | "exclude": [
|
189 | "**/*.spec.js"
|
190 | ]
|
191 | }
|
192 | }
|
193 | ```
|
194 |
|
195 | **Note:** Be wary of automatic OS glob expansion when specifying include/exclude globs with the CLI.
|
196 | To prevent this, wrap each glob in single quotes.
|
197 |
|
198 | ### Including files within `node_modules`
|
199 |
|
200 | We always add `**/node_modules/**` to the exclude list, even if not specified in the config.
|
201 | You can override this by setting `--exclude-node-modules=false`.
|
202 |
|
203 | For example, in the following config, `"excludeNodeModules: false"` will prevent `node_modules` from being added to the exclude rules.
|
204 | The set of include rules then restrict nyc to only consider instrumenting files found under the `lib/` and `node_modules/@my-org/` directories.
|
205 | The exclude rules then prevent nyc instrumenting anything in a `test` folder and the file `node_modules/@my-org/something/unwanted.js`.
|
206 |
|
207 | ```json
|
208 | {
|
209 | "nyc": {
|
210 | "all": true,
|
211 | "include": [
|
212 | "lib/**",
|
213 | "node_modules/@my-org/**"
|
214 | ],
|
215 | "exclude": [
|
216 | "node_modules/@my-org/something/unwanted.js",
|
217 | "**/test/**"
|
218 | ],
|
219 | "excludeNodeModules": false
|
220 | }
|
221 | }
|
222 | ```
|
223 |
|
224 | ## Setting the project root directory
|
225 |
|
226 | nyc runs a lot of file system operations relative to the project root directory.
|
227 | During startup nyc will look for the *default* project root directory.
|
228 | The *default* project root directory is the first directory found that contains a `package.json` file when searching from the current working directory up.
|
229 | If nyc fails to find a directory containing a `package.json` file, it will use the current working directory as the *default* project root directory.
|
230 | You can change the project root directory with the `--cwd` option.
|
231 |
|
232 | nyc uses the project root directory when:
|
233 | * looking for source files to instrument
|
234 | * creating globs for include and exclude rules during file selection
|
235 | * loading custom require hooks from the `require` array
|
236 |
|
237 | nyc may create artefact directories within the project root, with these defaults:
|
238 | * the report directory, `<project-root>/coverage`
|
239 | * the cache directory, `<project-root>/node_modules/.cache/nyc`
|
240 | * the temp directory, `<project-root>/.nyc_output`
|
241 |
|
242 | ## Require additional modules
|
243 |
|
244 | The `--require` flag can be provided to `nyc` to indicate that additional modules should be required in the subprocess collecting coverage:
|
245 |
|
246 | ```
|
247 | nyc --require esm mocha
|
248 | ```
|
249 |
|
250 | ### Interaction with `--all` flag
|
251 |
|
252 | The `--require` flag also operates on the main nyc process for use by `--all`.
|
253 | For example, in situations with `nyc --all --instrument false` and [`babel-plugin-istanbul`] setup the `--all` option only works if `--require @babel/register` is passed to nyc.
|
254 | Passing it to mocha would cause the tests to be instrumented but unloaded sources would not be seen.
|
255 | The [`@istanbuljs/nyc-config-babel`] package handles this for you!
|
256 |
|
257 | ## Caching
|
258 |
|
259 | `nyc`'s default behavior is to cache instrumented files to disk to prevent instrumenting source files multiple times, and speed `nyc` execution times.
|
260 | You can disable this behavior by running `nyc` with the `--cache false` flag.
|
261 | You can also change the default cache directory from `./node_modules/.cache/nyc` by setting the `--cache-dir` flag.
|
262 |
|
263 | ## Coverage thresholds
|
264 |
|
265 | You can set custom coverage thresholds that will fail if `check-coverage` is set to `true` and your coverage drops below those thresholds.
|
266 | For example, in the following configuration, dropping below 80% branch, line, functions, or statements coverage would fail the build (you can have any combination of these):
|
267 |
|
268 | ```json
|
269 | {
|
270 | "nyc": {
|
271 | "branches": 80,
|
272 | "lines": 80,
|
273 | "functions": 80,
|
274 | "statements": 80
|
275 | }
|
276 | }
|
277 | ```
|
278 |
|
279 | To do this check on a per-file basis (as opposed to in aggregate), set the `per-file` option to `true`.
|
280 |
|
281 | ### High and low watermarks
|
282 |
|
283 | Several of the coverage reporters supported by nyc display special information for high and low watermarks:
|
284 |
|
285 | * high-watermarks represent healthy test coverage (in many reports this is represented with green highlighting).
|
286 | * low-watermarks represent sub-optimal coverage levels (in many reports this is represented with red highlighting).
|
287 |
|
288 | You can specify custom high and low watermarks in nyc's configuration:
|
289 |
|
290 | ```json
|
291 | {
|
292 | "nyc": {
|
293 | "watermarks": {
|
294 | "lines": [80, 95],
|
295 | "functions": [80, 95],
|
296 | "branches": [80, 95],
|
297 | "statements": [80, 95]
|
298 | }
|
299 | }
|
300 | }
|
301 | ```
|
302 |
|
303 | ## Parsing Hints (Ignoring Lines)
|
304 |
|
305 | There may be some sections of your codebase that you wish to purposefully
|
306 | exclude from coverage tracking, to do so you can use the following parsing
|
307 | hints:
|
308 |
|
309 | * `/* istanbul ignore if */`: ignore the next if statement.
|
310 | * `/* istanbul ignore else */`: ignore the else portion of an if statement.
|
311 | * `/* istanbul ignore next */`: ignore the next _thing_ in the source-code (
|
312 | functions, if statements, classes, you name it).
|
313 | * `/* istanbul ignore file */`: ignore an entire source-file (this should be
|
314 | placed at the top of the file).
|
315 |
|
316 | ## Ignoring Methods
|
317 |
|
318 | There may be some methods that you want to universally ignore out of your classes
|
319 | rather than having to ignore every instance of that method:
|
320 |
|
321 | ```json
|
322 | {
|
323 | "nyc": {
|
324 | "ignore-class-method": "render"
|
325 | }
|
326 | }
|
327 | ```
|
328 |
|
329 | ## Combining reports from multiple runs
|
330 | If for whatever reason you have different test runners in your project or a different series of test runs for different kinds of tests, nyc will automatically combine the coverage report for you if configured correctly with the `--no-clean` flag and the `report` command.
|
331 | Originally inspired by @janiukjf in #1001, here's an example, where the `test:*` scripts (not shown) invoke only your test runner(s) and not nyc:
|
332 |
|
333 | ```json
|
334 | {
|
335 | "scripts": {
|
336 | "cover": "npm run cover:unit && npm run cover:integration && npm run cover:report",
|
337 | "cover:unit": "nyc --silent npm run test:unit",
|
338 | "cover:integration": "nyc --silent --no-clean npm run test:integration",
|
339 | "cover:report": "nyc report --reporter=lcov --reporter=text"
|
340 | }
|
341 | }
|
342 | ```
|
343 |
|
344 | ### What about `nyc merge`?
|
345 |
|
346 | The `nyc merge` command is for producing one _raw coverage output file_ that combines the results from many test runs.
|
347 | So if you had the above setup and needed to produce a single `coverage.json` for some external tool, you could do:
|
348 |
|
349 | ```json
|
350 | {
|
351 | "scripts": {
|
352 | "cover:merge": "npm run cover:unit && npm run cover:integration && nyc merge .nyc_output coverage.json"
|
353 | }
|
354 | }
|
355 | ```
|
356 |
|
357 | ## Source-Map support for pre-instrumented codebases
|
358 |
|
359 | If you opt to pre-instrument your source-code (rather than using a just-in-time transpiler like [`@babel/register`]) nyc supports both inline source-maps and `.map` files.
|
360 |
|
361 | _Important: If you are using nyc with a project that pre-instruments its code, run nyc with the configuration option `--exclude-after-remap` set to `false`.
|
362 | Otherwise nyc's reports will exclude any files that source-maps remap to folders covered under exclude rules._
|
363 |
|
364 | ## [Integrating with coveralls](./docs/setup-coveralls.md)
|
365 |
|
366 | ## [Integrating with codecov](./docs/setup-codecov.md)
|
367 |
|
368 | ## [Producing instrumented source](./docs/instrument.md)
|
369 |
|
370 | ## Integrating with TAP formatters
|
371 |
|
372 | Many testing frameworks (Mocha, Tape, Tap, etc.) can produce [TAP](https://en.wikipedia.org/wiki/Test_Anything_Protocol) output. [tap-nyc](https://github.com/MegaArman/tap-nyc) is a TAP formatter designed to look nice with nyc.
|
373 |
|
374 | ## More tutorials
|
375 |
|
376 | You can find more tutorials at http://istanbul.js.org/docs/tutorials
|
377 |
|
378 | ## Other advanced features
|
379 |
|
380 | Take a look at http://istanbul.js.org/docs/advanced/ and please feel free to [contribute documentation](https://github.com/istanbuljs/istanbuljs.github.io/tree/development/content).
|
381 |
|
382 | [`@babel/register`]: https://www.npmjs.com/package/@babel/register
|
383 | [`babel-plugin-istanbul`]: https://github.com/istanbuljs/babel-plugin-istanbul
|
384 | [`@istanbuljs/nyc-config-babel`]: https://www.npmjs.com/package/@istanbuljs/nyc-config-babel
|
385 | [selecting files for coverage]: #selecting-files-for-coverage
|