Debian Codegraph @

nyc/README.md

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