Instrument
Producing instrumented source
The nyc instrument command can produce instrumented source files.
These files are suitable for client side deployment during end to end testing.
You can either pre-instrument your source, or write instrumented source to a stream.
Run nyc instrument --help to display a full list of available command options.
Pre-instrumented source
You can create pre-instrumented source code by running:
nyc instrument <input> [output]<input> can be any file or directory within the project root directory.
The [output] directory is optional and can be located anywhere, if not set the instrumented code will be sent to stdout.
For example, nyc instrument . ./output will produce instrumented versions of any source files it finds in . and store them in ./output.
The --delete option will remove the existing output directory before instrumenting.
The --in-place option will allow you to run the instrument command.
The --complete-copy option will copy all remaining files from the input directory to the output directory.
When using --complete-copy nyc will not copy the contents of a .git folder to the output directory.
Note: --complete-copy will dereference any symlinks during the copy process, this may stop scripts running properly from the output directory.
Streaming instrumentation
nyc instrument <input> will stream instrumented source directly to stdout and that output can then be piped to another process.
You can use this behaviour to create a server that dynamically instruments files on request.
The following example shows streaming instrumentation middleware capable of instrumenting files on request.
app.use((req, res, next) => {
const myOptions = ""
const filename = myHelper.getFilename(req)
const nyc = cp.spawn(nyc instrument ${myOptions} ${filename})
nyc.stdout.pipe(res)
})---
Profiling
Profiling:
The self-coverage tool can provide a fairly interesting information on how nyc performs in real world test suites. Doing this is a bit involved, detailed steps follow.
Note: This assumes your locally cloned development version of nyc is in /user/dev/nyc, and that you are profiling against the AVA test suite in /user/dev/ava. Adapt as required.
Initial Setup (NYC)
We must use npm link, and ensure we have fresh "self-coverage" scripts generated.
Go to the local clone of nyc
cd /user/dev/nycLink the local clone globally
npm linkCreate the self-coverage instrumented files
node ./build-self-coverageInitial Setup (Test Project)
CD to the real world test suite you want to profile against
cd /user/dev/avaLink the globally linked nyc into your local node_modules
npm link nycThis will likely not work with tap --coverage, since tap will try to use its own older copy of nyc instead of your globally linked one. Modify the test script in your test project so it uses the nyc binary directly, and disable taps version with the --no-cov flag:
package.json:
{
"scripts" : {
"test": "nyc tap --no-cov test/*.js"
}
}Each Run
Clear existing self coverage (trash ~== rm -rf)
cd /user/dev/nyc
trash ./.self_coverageClear the .nyc_cache folder in your test project
cd /user/dev/ava
trash ./.nyc_cacheRun your test suite
npm testGo back to the nyc folder and create a self-coverage report
cd /user/dev/nyc
npm run reportA detailed profile of your test run now exists in /user/dev/nyc/coverage/lcov-report
Note: trash is a safer version of rm -rf. Install via npm i trash-cli. More info.
WARNING: Self coverage can cause some confusing problems.
If index.covered.js exists, it will be used instead of the normal file. This means your changes to index.js will not have an effect until you recreate or delete the self coverage files. Unless you are trying to do some profiling, you should probably delete them so the regular files are used.
You can delete the self coverage scripts and use the regular ones as follows:
Go to nyc directory and remove the self coverage scripts
cd /user/dev/nyc
npm run cleanYou can rerun node ./build-self-coverage scripts as desired to re-enable self-coverage.
---
Setup Codecov
Integrating with codecov.io
codecov is a great tool for adding coverage reports to your GitHub project, even viewing them inline on GitHub with a browser extension.
Quick start
Assuming your npm test does not run nyc and you have the npx executable (npm v5.2+), have your CI runner execute the following:
npx nyc --reporter=lcov npm test && npx codecovWithout npx - Travis CI example using npm scripts
1. add the codecov and nyc dependencies:
npm install codecov nyc --save-dev2. update the scripts in your package.json to include these lines (replace mocha with your test runner):
{
"scripts": {
"test": "nyc --reporter=lcov mocha",
"coverage": "codecov"
}
}3. For private repos, add the environment variable CODECOV_TOKEN to Travis CI.
4. add the following to your .travis.yml:
after_success: npm run coverage---
Setup Coveralls
Integrating with coveralls.io
coveralls.io is a great tool for adding
coverage reports to your GitHub project. Here's how to get nyc
integrated with coveralls and travis-ci.org:
1. add the coveralls and nyc dependencies to your module:
npm install coveralls nyc --save-dev2. update the scripts in your package.json to include these bins:
{
"scripts": {
"test": "nyc mocha",
"coverage": "nyc report --reporter=text-lcov | coveralls"
}
}3. For private repos, add the environment variable COVERALLS_REPO_TOKEN to Travis CI.
4. add the following to your .travis.yml:
after_success: npm run coverageThat's all there is to it!
Note: by default coveralls.io adds comments to pull-requests on GitHub, this can feel intrusive. To disable this, click on your repo on coveralls.io and uncheck LEAVE COMMENTS?.---
CHANGELOG
Changelog
All notable changes to this project will be documented in this file. See standard-version for commit guidelines.
18.0.0 (2026-02-22)
⚠ BREAKING CHANGES
* deps: transitive dependencies now require node 20 || >=22.
Bug Fixes
* deps: update dependencies pulling in old glob (#1612) (0707729)
17.1.0 (2024-09-19)
Features
* deps: bump foreground-child from ^2.0.0 to ^3.0.0 (#1546) (af74d1e)
Bug Fixes
* reduce size of serialized JSON output (#1570) (ae657b6)
17.0.0 (2024-04-19)
⚠ BREAKING CHANGES
* minimum Node version now 18
Bug Fixes
* deps: address security alerts in deps (#1555) (b6ed598)
Build System
* minimum Node version now 18 (9ef340e)
16.0.0 (2024-04-10)
⚠ BREAKING CHANGES
* minimum Node version now 18
Bug Fixes
* deps: address security alerts in deps (#1555) (b6ed598)
Build System
* minimum Node version now 18 (9ef340e)
15.1.0 (2020-06-01)
Features
* experimental: Support using --all with node.js ESM (#1320) (992359a)
15.0.1 (2020-04-02)
Bug Fixes
* Data merge concurrency limit to prevent OOM (#1293) (df34c1c), closes #1263
* Ignore insignificant lines when coalesce text report (#1300) (3a577f0), closes istanbuljs/istanbuljs#525
15.0.0 (2019-12-20)
⚠ BREAKING CHANGES
* The flow and jsx parser plugins are no longer
enabled by default.
* Node.js 8 is now required to run nyc
* Remove NYC_ROOT_ID and NYC_INSTRUMENTER environmental
variables.
* The root field has been removed from processinfo
files.
Features
* Add --use-spawn-wrap=true option (#1169) (df4de4d)
* Add .cjs, .mjs, .ts, .tsx, .jsx to default extensions (#1110) (914b776), closes #1103
* Allow nyc instrument to instrument code in place (#1149) (7783284)
* Drop node.js 6, upgrade dependencies (#1134) (00c3b34)
* Filenames relative to project cwd in coverage reports (#1212) (5258e9f)
* Use @istanbuljs/schema for yargs setup (#1194) (fd40d49)
* Use istanbul-lib-processinfo (#1145) (7943413)
* Use source base name to prefix cache files (#1144) (5c1b7a9)
Bug Fixes
* Avoid source-map module during signal-exit handler (#1191) (83eb629)
* Better error handling for main execution, reporting (#1229) (dfd629d)
* Correct handling of source-maps for pre-instrumented files (#1216) (8411a26), closes #1208
* Drop coverage produced by nyc --all for files that were tested (#1155) (fc1bbbf), closes #1113 #1124 #1148
* Honor eager setting (false by default) (#1179) (c18fb0a)
* Remove vestigial environment variables (#1078) (cfd3da0)
14.1.1 (2019-05-09)
Bug Fixes
* check-coverage: make the --temp-dir option visible (#1101) (b5b67de)
* cli: Report error if unwanted positional arguments are received (#1100) (57debc1), closes #401
14.1.0 (2019-04-24)
Bug Fixes
* Do not crash when nyc is run inside itself. (#1068) (c4fcf5e), closes #1067
* Exit with code 1 when nyc doesn't know what to do. (#1070) (21fb2c8)
* Purge source-map cache before reporting if cache is disabled. (#1080) (3d9eaa4)
* Use correct config property for parser plugins (#1082) (a7bc7ae)
Features
* add support for yaml configuration file (#1054) (ca37ffa)
14.0.0 (2019-04-15)
Bug Fixes
* Add cwd option to instrument command (#1024) (051d95a)
* Add config values to hash salt (#988) (7ac325d), closes #522
* Exclude negated not working with '--all' switch (#977) (91de23c)
* Make --all work for transpiled code (#1047) (18e04ba)
* Resolve absolute paths in nyc instrument (#1012) (3cb1861), closes #1014
* Set processinfo pid/ppid to actual numbers (#1057) (32f75b0)
* Use a single instance of nyc for all actions of main command. (#1059) (b909575)
Features
* Add delete option to instrument command (#1005) (d6db551)
* Add include and exclude options to instrument command (#1007) (8da097e)
* Add processinfo index, add externalId (#1055) (8dcf180)
* Add support for nyc.config.js (#1019) (3b203c7)
* Add support to exclude files on coverage report generation (#982) (509c6aa)
* Add test-exclude args to check-coverage and report subcommands. (0fc217e)
* Always build the processinfo temp dir (#1061) (c213469)
* Enable es-modules option for nyc instrument command (#1006) (596b120)
* Fix excludeAfterRemap functionality. (36bcc0b)
* Implement nyc instrument --complete-copy (#1056) (2eb13c6)
* Remove bundling (#1017) (b25492a)
* Support turning off node_modules default exclude via exclude-node-modules option (#912) (b7e16cd)
* Add support for --exclude-node-modules to subcommands. (#1053) (e597c46)
BREAKING CHANGES
* The --exclude-after-remap option is now functional and enabled by default. This causes the include, exclude and extension lists to be processed after using source maps to determine the original filename of sources.
* Add a file named 'index.json' to the .nyc_output/processinfo directory, which has a different format from the other files in this dir.
* Change the data type of the pid/ppid fields in processinfo files
* nyc instrument now honors include and exclude settings, potentially resulting in some files that were previously instrumented being ignored.
* The plugins option has been renamed to parser-plugins.
* The logic involving include/exclude processing has changed. Results should be verified to ensure all desired sources have coverage data.
* nyc instrument now enables the --es-module option by default. This can cause failures to instrument scripts which violate 'use strict' rules.
<a name="13.3.0"></a>
13.3.0 (2019-02-14)
Bug Fixes
* update dependencies due to vulnerabilities (#992) (e8cc59b), closes #991
Features
* Support nyc report --check-coverage (#984) (dd48410)
<a name="13.2.0"></a>
13.2.0 (2019-01-27)
Bug Fixes
* Create directory for merge destination. (#979) (921d386), closes #976
* missing command temp-directory (#928) (28b6d09), closes #927
* nyc processing files not covered by include when all is enabled. (#914) (40afc5f), closes #913 #782
Features
* avoid hardcoded HOME for spawn-wrap working dir (#957) (ff834aa), closes #951
* document the fact that cacheDir is configurable (#968) (35cd49a)
* Option Plugins (#948) (df2730d)
<a name="13.1.0"></a>
13.1.0 (2018-09-06)
Features
* Bump dependencies. (#915) (0b3d2cf)
* Rename --temp-directory option to --temp-dir (#897) (ccf42df)
<a name="13.0.1"></a>
13.0.1 (2018-07-24)
Bug Fixes
* add flag to allow control of instrumenter esModules option, default to looser parsing (#863) (6b6cd5e)
* Enable es-modules by default. (#889) (d0b76e2), closes #796
* Update caching-transform options. (#873) (52b69ef)
* use uuid/v4 to generate unique identifiers. (#883) (7483ed9)
<a name="13.0.0"></a>
13.0.0 (2018-06-08)
Bug Fixes
* source was being instrumented twice, due to upstream fix in ista… (#853) (d0f654c)
Features
* allow rows with 100% statement, branch, and function coverage to be skipped in text report (#859) (893345a)
BREAKING CHANGES
* --hook-run-in-context, and --hook-run-in-this-context are no longer true by default (they should be enabled if you're using a library like requirejs).
<a name="12.0.2"></a>
12.0.2 (2018-06-03)
Bug Fixes
* don't bundle istanbul-lib-instrument due to Node 6 issues (b4c325b)
* stop bundling istanbul-lib-instrument due to npm issue on Node 6 (#854) (ddc9331)
<a name="12.0.1"></a>
12.0.1 (2018-05-31)
<a name="12.0.0"></a>
12.0.0 (2018-05-31)
Chores
* upgrade to newest version of istanbul codebase (#848) (19b7d21)
BREAKING CHANGES
* babel@7 drops Node.js 4 support
<a name="11.9.0"></a>
11.9.0 (2018-05-31)
Features
* add option that allows instrument to exit on error (#850) (1329a3b)
<a name="11.8.0"></a>
11.8.0 (2018-05-14)
Features
* merge together multiple istanbul format reports (#840) (9def3eb)
<a name="11.7.3"></a>
11.7.3 (2018-05-10)
<a name="11.7.2"></a>
11.7.2 (2018-05-08)
<a name="11.7.1"></a>
11.7.1 (2018-04-17)
<a name="11.7.0"></a>
11.7.0 (2018-04-16)
Features
* allow 0-line files to be ignored in coverage output (#808) (24e5979)
* load coverage files individually instead of all at once, addressing memory issues (#806) (05fea60)
<a name="11.6.0"></a>
11.6.0 (2018-03-13)
Bug Fixes
* removes unused split-lines dependency. (#787) (b4032ce)
* update to yargs version that allows extending configs with no extension (#790) (2d51562)
Features
* allow usage of ignoreClassMethods from istanbul (#785) (c6b30ba)
<a name="11.5.0"></a>
11.5.0 (2018-02-13)
Bug Fixes
* coverage reportDir should respect --cwd (#764) (b0d6dae)
* typo in option definition (#758) (6a734b6)
Features
* add command line options to control compacting and comment removal (#754) (2030e0c)
* resolve custom cache directory to absolute path (#766) (dd48707)
<a name="11.4.1"></a>
11.4.1 (2017-12-14)
Bug Fixes
* explicitly update spawn-wrap (#748) (4e4f428)
<a name="11.4.0"></a>
11.4.0 (2017-11-28)
Bug Fixes
* always invoke instrumenter callback, set appropriate exit-code (#703) (7ea96ba)
Features
* allow alternate path for .nycrc to be specified (#724) (785fccb)
<a name="11.3.0"></a>
11.3.0 (2017-10-23)
Features
* add --exclude-after-remap option for users who pre-instrument their codebase (#697) (cdfdff3)
* add option to hook vm.runInContext (#680) (f04b7a9)
* allow instrument-only to produce sourcemaps (#674) (f31d7a6)
<a name="11.2.1"></a>
11.2.1 (2017-09-06)
Bug Fixes
* apply exclude logic before remapping coverage (#667) (a10d478)
* create temp directory when --no-clean flag is set #663 (#664) (3bd1527)
<a name="11.2.0"></a>
11.2.0 (2017-09-05)
Bug Fixes
* remove excluded files from coverage before writing (#649) (658dba4)
Features
* add possibility to filter coverage-maps (#637) (dd40dc5)
* allow cwd to be configured see #620 (0dcceda)
<a name="11.1.0"></a>
11.1.0 (2017-07-16)
Features
* add support for per file coverage checking (#591) (bbadc1f)
* upgrade to version of spawn-wrap that supports .EXE (#626) (8768afe)
<a name="11.0.3"></a>
11.0.3 (2017-06-25)
Bug Fixes
* update help link to list of reporters (#601) (b1eb4d6)
* upgrade to spawn-wrap version that works with babel-register (#617) (923b062)
<a name="11.0.2"></a>
11.0.2 (2017-06-02)
<a name="11.0.1"></a>
11.0.1 (2017-06-01)
<a name="11.0.0"></a>
11.0.0 (2017-05-31)
Bug Fixes
* add support for ES6 modules (f18f780)
Features
* allow .nycrc.json (#580) (a1a457f)
* upgrade to version of yargs with support for presets (33829b8)
BREAKING CHANGES
* new version of find-up requires dropping 0.10/0.12 support (which we had already been planning).
<a name="10.3.2"></a>
10.3.2 (2017-05-05)
Bug Fixes
* we should not create a cache folder if cache is false (#567) (213206f)
<a name="10.3.1"></a>
10.3.1 (2017-05-04)
Bug Fixes
* introduced a bug that resulted in source-maps not being loaded appropriately on second test run (#566) (1bf74fd)
<a name="10.3.0"></a>
10.3.0 (2017-04-29)
Bug Fixes
* source-maps were not being cached in the parent process when --all was being used (#556) (ff73b18)
Features
* add support for --no-clean, to disable deleting raw coverage output (#558) (1887d1c)
<a name="10.2.0"></a>
10.2.0 (2017-03-28)
Bug Fixes
* fix bug related to merging coverage reports see #482 (81229a0)
* revert defaulting to empty file-coverage report, this caused too many issues (25aec77)
Features
* allow babel cache to be enabled (#517) (98ebdff)
* exclude the coverage/ folder by default 🚀 (#502) (50adde4)
* upgrade to version of yargs with extend support (#541) (95cc09a)
<a name="10.1.2"></a>
10.1.2 (2017-01-18)
Bug Fixes
* revert defaulting to empty file-coverage report, this caused too many issues (25aec77)
<a name="10.1.1"></a>
10.1.1 (2017-01-18)
Bug Fixes
* fix bug related to merging coverage reports see #482 (81229a0)
<a name="10.1.0"></a>
10.1.0 (2017-01-17)
Bug Fixes
* address edge-cases related to --all when instrumentation is disabled (#482) (8c58d68)
* pass configuration options to --check-coverage (#483) (1022b16)
Features
* allow eager instantiation of instrumenter (#490) (8b58c05)
* reporting watermarks can now be set in nyc config stanza (#469) (0a1d72a)
* upgrade to istanbul-lib-instrument with support for 'const foo = function () {}' name preservation. upgrade to istanbul-lib-hook with fix for ts-node. (#494) (d8d2de0)
<a name="10.0.2"></a>
10.0.2 (2017-01-02)
Bug Fixes
* upgrade to newer istanbul-lib-instrument, with fixes for inferred function names (#479) (e01ec8c)
<a name="10.0.1"></a>
10.0.1 (2016-12-27)
Bug Fixes
* upgrade spawn-wrap and istanbul-lib-instrument (#477) (e0ef1d5)
<a name="10.0.0"></a>
10.0.0 (2016-11-22)
Bug Fixes
* debug-log should be production dependency (a3c7f83)
Features
* cache now turned on by default (#454) (0dd970c)
BREAKING CHANGES
* nyc's cache is now enabled by default
<a name="9.0.1"></a>
9.0.1 (2016-11-14)
Bug Fixes
* addresses several test-exclude edge-cases. addresses perf issue with yargs (#442)
<a name="9.0.0"></a>
9.0.0 (2016-11-13)
Features
* adds support for source-map production (#439) (31488f5)
* allow an alternate cache folder to be provided (#443) (b6713a3)
* node_modules is again excluded by default when custom exclude is provided (#442) (2828538)
BREAKING CHANGES
* /node_modules/ is again excluded by default.
<a name="8.4.0"></a>
8.4.0 (2016-10-30)
Bug Fixes
* hot-fix bad release of nyc (c487eb3)
* reverts _maybeInstrumentSource logic, so that exclude is still applied (#429) (b90d26f)
* update core istanbul libraries (#426) (4945dac)
Features
* coverage information is now returned for process tree (#416) (92dedda)
* read coverage header when using "noop" instrumenter (#420) (63a8758)
<a name="8.3.1"></a>
8.3.1 (2016-10-06)
Bug Fixes
* swap to version of test-exclude that does not warn (#410) (78aac45)
* update istanbul-lib-source-maps to 1.0.2 (#411) (9c89945)
<a name="8.3.0"></a>
8.3.0 (2016-09-15)
Bug Fixes
* add a feature which allows us to bust the cache when breaking changes are introduced (#394) (b7a413a)
* add shim for check-coverage on node 0.10 (#386) (9ebaea8)
* upgrade to newer versions of source-map, signal-exit, and instrument (#389) (a9bdf0f), closes #379
Features
* add support for .nycrc (#391) (1c2349b)
* refactored config to fix precedence of config vs. args (#388) (99dbbb3), closes #379
<a name="8.2.0"></a>
8.2.0 (2016-09-02)
Bug Fixes
* upgrade standard, and a few other dependencies. fix standard nits (#375) (64c68b7)
Features
* gather process tree information (#364) (fabe5f3)
<a name="8.1.0"></a>
8.1.0 (2016-08-14)
Bug Fixes
* serialization using ',' was breaking globs (#353) (22929db)
Features
* implicitly assume node when the command starts with an option (#350) (2bb52cd)
<a name="8.0.0"></a>
8.0.0 (2016-08-12)
Bug Fixes
* make nyc instrument work in subdirectories (#343) (a82cf49)
* upgrade to versions of coverage/instrument that solve out-of-bound errors (#349) (bee0328)
Features
* upgrade to new test-exclude; with support for node_modules, and empty exclude (#348) (d616ffc)
BREAKING CHANGES
* node_modules is no longer automatically excluded, and an empty array of exclude rules can now be provided.
<a name="7.1.0"></a>
7.1.0 (2016-07-24)
Bug Fixes
* make --all flag work with files with extensions other than .js (#326) (d0a8674)
* workaround for Windows path issue nodejs/node#6624 (6b1fed0)
Features
* nyc no longer tries to run arguments passed to the instrumented bin (#322) (e0a8c0b)
* use istanbul-lib-hook to wrap require and support vm hooks (#308) (2b64cf8)
<a name="7.0.0"></a>
7.0.0 (2016-07-09)
Bug Fixes
* avoid pid collisions. (#301) (f67bff7)
* disable the babel/nyc cache (#303) (104b3da)
Features
* adds instrument command line option (#298) (e45b51b)
* nyc is being refactored to become the official Istanbul 1.0 bin (#286) (61a05ea)
BREAKING CHANGES
* significant chunks of nyc's API have been reworked, to use the Istanbul 1.0 API: source-map support, instrumentation, the check-coverage command, etc.
<a name="6.6.1"></a>
6.6.1 (2016-06-14)
Bug Fixes
* the package tree of bundled dependencies was incorrect (7bdccf5)
<a name="6.6.0"></a>
6.6.0 (2016-06-14)
Features
* add "instrument" option as alternative to specifying noop instrumenter (#278) (ea028b9)
<a name="6.5.1"></a>
6.5.1 (2016-06-14)
Bug Fixes
* upgrade foreground-child dependency (#276) (1b9e4a8)
<a name="6.5.0"></a>
6.5.0 (2016-06-13)
Bug Fixes
* cleanup dependencies (#254) (a20d03d)
* discard more bad source map positions (#255) (0838a0e)
* Update AppVeyor config with ~faster npm install (#252) (df591f4)
Features
* make __coverage__ the default approach we advocate for ES2015 coverage (#268) (9fd2295)
<a name="6.4.4"></a>
6.4.4 (2016-05-07)
Bug Fixes
* upgraded dependencies, add missing lodash bundled dependency (#250)(32042fc)
<a name="6.4.3"></a>
6.4.3 (2016-05-06)
Bug Fixes
* must bundle dependencies on npm<3.x or they will flatten (we need a better long-term solution)(9826f11)
<a name="6.4.2"></a>
6.4.2 (2016-05-02)
Bug Fixes
* update: update strip-bom to version 3.0.0 (#240)(24f55e7)
* upgrade spawn-wrap to version that works with new shelljs (#242)(b16053c)
<a name="6.4.1"></a>
6.4.1 (2016-04-27)
Bug Fixes
* strip any duplicate extensions from --extension (#237) (0946f82)
<a name="6.4.0"></a>
6.4.0 (2016-04-11)
Bug Fixes
* adds CLI integration testing, where there was no integration testing before. (3403ca1)
Features
* cli: --include and --exclude are now accepted as CLI options, thanks @rpominov \o/ see #207 (f8a02b4)
<a name="6.3.0"></a>
6.3.0 (2016-04-08)
Features
* better docs for excluding, thanks @kentcdodds \o/ (22b06fe)
* updating dependencies (spawn wrap with npm patches \o/) (ac841b8)
<a name="6.2.1"></a>
6.2.1 (2016-04-05)
Bug Fixes
* bundling: .gitignore was interfering with bundle (0e4adae)
<a name="6.2.0"></a>
6.2.0 (2016-04-05)
Bug Fixes
* bundle dependencies: start bundling dependencies, which should address some issues we have seen with (6116077)
* exit code: use test program’s exit code even with --check-coverage (00bbeb2)
Features
* conventional changelog: introducing conventional-changelog for changelog generation (f594c5e)
* exclude patterns: introduces new exclude-patterns based on @kentcdodds' coding conventions. (51b1777)
* update dependencies: new foreground-child and spawn-wrap have landed \o/ (1a0ad0b)
v6.1.1 (2016/03/13 14:23 +7:00)
- #194 hot-fix for --all with multiple extensions (@bcoe)
v6.1.0 (2016/03/12 15:00 +7:00)
- #191 upgrade to non-singleton version of yargs (@bcoe)
- #185 default to long-form option names so that they can be overridden in package.json (@rapzo)
- #180 fix bug with findUp (@bcoe)
- #178 --all should handle extensions other than .js. (@lloydcotten)
- #177 add .editorconfig (@JaKXz)
v6.0.0 (2016/02/20 +7:00)
- #167 all of nyc's settings can now
be configured in package.json (@bcoe)
- #164 coverage tracking now uses absolute paths, awesome \o/ (@novemberborn)
- #163 support for extensions other than .js (@lloydcotten)
v5.6.0 (2016/02/03 +7:00)
- #159 skip should continue working with source-maps (@novemberborn)
- #160 don't instrument files outside of the current working directory (@novemberborn)
v5.5.0 (2016/01/24 +07:00)
- #152 upgrade to newest version of foreground-child (@isaacs)
- #150 guard against illegal positions in source-map (@novemberborn)
v5.4.0 (2016/01/20 +07:00)
- #147 fix for foreground-child on Windows (@isaacs)
- #145 allow coverage output directory to be specified (@bcoe)
- #143 run files included via --all through transpilers (@bcoe)
- #139 documentation updates (@tcurdt)
- #138 Split CLI from spawn wrapper (@isaacs)
v5.3.0 (2016/01/05 14:07 -08:00)
- #132 Move config to top level nyc argument. (@jamestalmage)
v5.2.0 (2016/01/02 17:13 -08:00)
- #126 Add --check-coverage shorthand, which fails tests if coverage slips below threshold (@bcoe)
- #123 Upgrade spawn-wrap, foreground-child (@isaacs)
- #122 Use module for finding cache directory (@jamestalmage)
v5.1.1 (2015/12/30 14:52 -08:00)
- #121 Fix for --all functionality. (@jamestalmage)
v5.1.0 (2015/12/27 20:36 -08:00)
- #108 Adds cache functionality. this is a big one, thanks! (@jamestalmage)
- #118 Stop bundling spawn-wrap dependency (@bcoe)
- #114 Update to latest versions of tap, glob, rimraf (@isaacs)
- #107 Get test-suite running on Windows (@bcoe)
v5.0.1 (2015/12/14 09:09 -07:00)
- #94 Windows failed if argument had no replace() method. (@bcoe)
v5.0.0 (2015/12/09 11:03 -07:00)
- #87 make spawn() work on Windows (@bcoe)
- #84 glob based include/exclude of files (@Lalem001)
- #78 improvements to sourcemap tests (@novemberborn)
- #73 improvements to require tests (@novemberborn)
- #65 significant improvements to require hooks (@novemberborn)
- #64 upgrade Istanbul (@novemberborn)
v4.0.0 (2015/11/29 10:13 -07:00)
- #58 adds support for Babel (@bcoe)
v3.2.2 (2015/09/11 22:02 -07:00)
- #47 make the default exclude rules work on Windows (@bcoe)
- #45 pull in patched versions of spawn-wrap and foreground-child, which support Windows (@bcoe)
- #44 Adds --all option which adds 0% coverage reports for all files in project, regardless of whether code touches them (@ronkorving)
v3.1.0 (2015/08/02 19:04 +00:00)
- #38 fixes for windows spawning (@rmg)
v3.0.1 (2015/07/25 20:51 +00:00)
- #33 spawn istanbul in a way that is less likely to break [email protected] (@bcoe)
v3.0.0 (2015/06/28 19:49 +00:00)
- #31 Combine instrumentation and reporting steps, based
on @Raynos' suggestion (@bcoe)
v2.4.0 (2015/06/24 15:57 +00:00)
- #30 Added check-coverage functionality, thanks
@Raynos! (@bcoe)
v2.3.0 (2015/06/04 06:43 +00:00)
- #27 upgraded tap, and switched tests to using tap --coverage (@bcoe)
- #25 support added for multiple reporters, thanks @jasisk! (@jasisk)
v2.2.0 (2015/05/25 21:05 +00:00)
- b2e4707 change location of nyc_output to .nyc_output. Added note about coveralls comments. (@sindresorhus)
v2.1.3 (2015/05/25 06:30 +00:00)
- 376e328 handle corrupt JSON files in nyc_output (@bcoe)
v2.1.1 (2015/05/25 02:52 +00:00)
- b39dec5 new signal-exit handles process.exit() in process.on('exit') (@isaacs)
v2.1.0 (2015/05/23 20:55 +00:00)
- ad13b30 added CHANGELOG.md \o/ (@bcoe)
- 53fef48 put tests around @shackpank's work on .istanbul.yml (@bcoe)
- da81c54 upgrade spawn-wrap and foreground-child (@isaacs)
- 4f69327 pin tap until new version of nyc can be pulled in (@bcoe)
v2.0.6 (2015/05/23 06:52 +00:00)
- cd70a41 upgrade signal-exit (@bcoe)
v2.0.5 (2015/05/20 05:44 +00:00)
- #11 Merge pull request #11 from bcoe/exlude-docs (@bcoe)
v2.0.4 (2015/05/19 04:58 +00:00)
- 4d920ef ensure that writing code coverage always happens last (@bcoe)
v2.0.3 (2015/05/18 01:52 +00:00)
- 94d2693 [email protected] (@isaacs)
v2.0.1 (2015/05/18 01:46 +00:00)
- 62c2cb0 upgrade signal-exit dependency (@bcoe)
v2.0.0 (2015/05/16 21:38 +00:00)
- d27794e got rid of nyc-report bin (@bcoe)
- 64c9824 added better documentation and CLI. (@bcoe)
v1.4.1 (2015/05/16 19:23 +00:00)
- ae05346 pulled in new version of signal-exit (@bcoe)
v1.4.0 (2015/05/16 09:11 +00:00)
- 8ca6e16 pulled in signal-exit module (@bcoe)
v1.3.0 (2015/05/15 15:56 +00:00)
- 0f701da pulled in new spawn-wrap, various bug fixes (@isaacs)
v1.2.0 (2015/05/13 20:21 +00:00)
- 2611ba4 handle signals when writing coverage report (@bcoe)
v1.1.3 (2015/05/11 18:31 +00:00)
- 8b362d6 istanbul has a text lcov report now \o/ (@bcoe)
v1.1.2 (2015/05/11 06:52 +00:00)
- 48b21cf added coverage and build badges (@bcoe)
v1.1.0 (2015/05/10 01:32 +00:00)
- 6c3f8a6 pulled in @isaacs spawn-wrap module (@isaacs)
- d8956f1 we now pass cwd around using the process.env.NYC_CWD variable (@bcoe)
---
README
nyc
[](https://github.com/bcoe/c8/actions/workflows/ci.yaml)
[](https://www.npmjs.com/package/nyc)
[](https://conventionalcommits.org)
_Having problems? want to contribute? join our community slack_.
Istanbul's state of the art command line interface, with support for:
* applications that spawn subprocesses.
* source mapped coverage of Babel and TypeScript projects
How Istanbul works
Istanbul instruments your ES5 and ES2015+ JavaScript code with line counters, so that you can track how well your unit-tests exercise your codebase.
The nyc command-line-client for Istanbul works well with most JavaScript testing frameworks: tap, mocha, AVA, etc.
Installation & Usage
Use your package manager to add it as a dev dependency: npm i -D nyc or yarn add -D nyc.
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):
{
"scripts": {
"test": "mocha",
"coverage": "nyc npm run test"
}
}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.
{
"scripts": {
"test": "npx nyc@latest mocha"
}
}This is a good way of testing upcoming releases of nyc, usually on the next tag.
Note: If you use jest or tap, you do not need to install nyc.
Those runners already have the IstanbulJS libraries to provide coverage for you.
Follow their documentation to enable and configure coverage reporting.
Configuring nyc
nyc accepts a wide variety of configuration arguments, run npx nyc --help for thorough documentation.
Configuration arguments on the command-line should be provided prior to the program that nyc is executing.
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.
nyc --reporter=lcov --reporter=text-summary avaBabel projects
Please start with the pre-configured [@istanbuljs/nyc-config-babel] preset.
You can add your custom configuration options as shown below.
TypeScript projects
Please start with the pre-configured @istanbuljs/nyc-config-typescript preset.
#### Adding your overrides
nyc allows you to inherit other configurations using the key extends in the package.json stanza, .nycrc, or YAML files.
You can then add the specific configuration options you want that aren't in that particular shared config, e.g.
{
"extends": "@istanbuljs/nyc-config-typescript",
"all": true,
"check-coverage": true
}Configuration files
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:
| File name | File Association |
|------------------|---------------------------------------------|
| .nycrc | JSON |
| .nycrc.json | JSON |
| .nycrc.yaml | YAML |
| .nycrc.yml | YAML |
| nyc.config.js | ESM / CommonJS export based on package type |
| nyc.config.cjs | CommonJS export |
| nyc.config.mjs | ESM export |
Common Configuration Options
See nyc --help for all options available.
You can set these in any of the files listed above, or from the command line.
This table is a quick TLDR for the rest of this readme and there are more advanced docs available.
| Option name | Description | Type | Default |
| ----------- | ----------- | ---- | ------- |
| all | Whether or not to instrument all files (not just the ones touched by your test suite) | Boolean | false |
| check-coverage | Check whether coverage is within thresholds, fail if not | Boolean | false |
| extension | List of extensions that nyc should attempt to handle in addition to .js | Array<String> | ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx'] |
| include | See [selecting files for coverage] for more info | Array<String> | ['']|
| exclude | See [selecting files for coverage] for more info | Array<String> | list |
| reporter | May be set to a built-in coverage reporter or an npm package (dev)dependency | Array<String> | ['text'] |
| report-dir | Where to put the coverage report files | String | ./coverage |
| skip-full | Don't show files with 100% statement, branch, and function coverage | Boolean | false |
| temp-dir | Directory to output raw coverage information to | String | ./.nyc_output |
Configuration can also be provided by nyc.config.js if programmed logic is required:
'use strict';const defaultExclude = require('@istanbuljs/schema/default-exclude');
const isWindows = require('is-windows');
let platformExclude = [
isWindows() ? 'lib/posix.js' : 'lib/win32.js'
];
module.exports = {
exclude: platformExclude.concat(defaultExclude)
};
Publish and reuse your nyc configuration(s)
To publish and reuse your own nyc configuration, simply create an npm module that exports your JSON config (via index.json or a CJS index.js).
A more advanced use case would be to combine multiple shared configs in a nyc.config.js file:
'use strict';const babelConfig = require('@istanbuljs/nyc-config-babel');
const hookRunInThisContextConfig = require('@istanbuljs/nyc-config-hook-run-in-this-context');
module.exports = {
...babelConfig,
...hookRunInThisContextConfig,
all: true,
'check-coverage': true
};
Selecting files for coverage
By default, nyc only collects coverage for source files that are visited during a test.
It does this by watching for files that are require()'d during the test.
When a file is require()'d, nyc creates and returns an instrumented version of the source, rather than the original.
Only source files that are visited during a test will appear in the coverage report and contribute to coverage statistics.
nyc will instrument all files if the --all flag is set or if running nyc instrument.
In this case all files will appear in the coverage report and contribute to coverage statistics.
nyc will only collect coverage for files that are located under cwd, and then only files with extensions listed in the extension array.
You can reduce the set of instrumented files by adding include and exclude filter arrays to your config.
These allow you to shape the set of instrumented files by specifying glob patterns that can filter files from the default instrumented set.
The exclude array may also use exclude negated glob patterns, these are specified with a ! prefix, and can restore sub-paths of excluded paths.
Globs are matched using minimatch.
We use the following process to remove files from consideration:
1. Limit the set of instrumented files to those files in paths listed in the include array.
2. Remove any files that are found in the exclude array.
3. Restore any exclude negated files that have been excluded in step 2.
Using include and exclude arrays
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.
If the include array is left undefined all eligible files will be included, equivalent to setting include: [''].
Multiple include globs can be specified on the command line, each must follow a --include, -n switch.
If there are paths specified in the exclude array, then the set of instrumented files will not feature eligible files found in those paths.
You can also specify negated paths in the exclude array, by prefixing them with a !.
Negated paths can restore paths that have been already been excluded in the exclude array.
Multiple exclude globs can be specified on the command line, each must follow a --exclude, -x switch.
The default exclude list is defined in the @istanbuljs/schema module.
Specifying your own exclude property completely replaces these defaults.
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.
It will also exclude any files with the extension .spec.js.
{
"all": true,
"include": [
"src//*.js"
],
"exclude": [
"/*.spec.js"
]
}Note: Be wary of automatic OS glob expansion when specifying include/exclude globs with the CLI.
To prevent this, wrap each glob in single quotes.
Including files within node_modules
We always add /node_modules/ to the exclude list, even if not specified in the config.
You can override this by setting --exclude-node-modules=false.
For example, "excludeNodeModules: false" in the following nyc config will prevent node_modules from being added to the exclude rules.
The set of include rules then restrict nyc to only consider instrumenting files found under the lib/ and node_modules/@my-org/ directories.
The exclude rules then prevent nyc instrumenting anything in a test folder and the file node_modules/@my-org/something/unwanted.js.
{
"all": true,
"include": [
"lib/",
"node_modules/@my-org/"
],
"exclude": [
"node_modules/@my-org/something/unwanted.js",
"/test/"
],
"excludeNodeModules": false
}Setting the project root directory
nyc runs a lot of file system operations relative to the project root directory.
During startup nyc will look for the default project root directory.
The default project root directory is the first directory found that contains a package.json file when searching from the current working directory up.
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.
You can change the project root directory with the --cwd option.
nyc uses the project root directory when:
* looking for source files to instrument
* creating globs for include and exclude rules during file selection
* loading custom require hooks from the require array
nyc may create artifact directories within the project root, with these defaults:
* the report directory, <project-root>/coverage
* the cache directory, <project-root>/node_modules/.cache/nyc
* the temp directory, <project-root>/.nyc_output
Require additional modules
The --require flag can be provided to nyc to indicate that additional modules should be required in the subprocess collecting coverage:
nyc --require esm mochaInteraction with --all flag
The --require flag also operates on the main nyc process for use by --all.
For example, in situations with nyc --all --instrument false and [babel-plugin-istanbul] set up the --all option only works if --require @babel/register is passed to nyc.
Passing it to mocha would cause the tests to be instrumented but unloaded sources would not be seen.
The [@istanbuljs/nyc-config-babel] package handles this for you!
Caching
nyc's default behavior is to cache instrumented files to disk to prevent instrumenting source files multiple times, and speed nyc execution times.
You can disable this behavior by running nyc with the --cache false flag.
You can also change the default cache directory from ./node_modules/.cache/nyc by setting the --cache-dir flag.
Coverage thresholds
You can set custom coverage thresholds that will fail if check-coverage is set to true and your coverage drops below those thresholds.
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):
{
"branches": 80,
"lines": 80,
"functions": 80,
"statements": 80
}To do this check on a per-file basis (as opposed to in aggregate), set the per-file option to true.
High and low watermarks
Several of the coverage reporters supported by nyc display special information for high and low watermarks:
* high-watermarks represent healthy test coverage (in many reports this is represented with green highlighting).
* low-watermarks represent sub-optimal coverage levels (in many reports this is represented with red highlighting).
You can specify custom high and low watermarks in nyc's configuration:
{
"watermarks": {
"lines": [80, 95],
"functions": [80, 95],
"branches": [80, 95],
"statements": [80, 95]
}
}Parsing Hints (Ignoring Lines)
There may be some sections of your codebase that you wish to purposefully
exclude from coverage tracking, to do so you can use the following parsing
hints:
/ istanbul ignore if */: ignore the next if statement.
/ istanbul ignore else */: ignore the else portion of an if statement.
/ istanbul ignore next */: ignore the next _thing_ in the source-code (
functions, if statements, classes, you name it).
/ istanbul ignore file */: ignore an entire source-file (this should be
placed at the top of the file).
Ignoring Methods
You can ignore every instance of a method simply by adding its name to the ignore-class-method array in your nyc config.
{
"ignore-class-method": ["render"]
}Combining reports from multiple runs
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.
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:
{
"scripts": {
"cover": "npm run cover:unit && npm run cover:integration && npm run cover:report",
"cover:unit": "nyc --silent npm run test:unit",
"cover:integration": "nyc --silent --no-clean npm run test:integration",
"cover:report": "nyc report --reporter=lcov --reporter=text"
}
}What about nyc merge?
The nyc merge command is for producing one _raw coverage output file_ that combines the results from many test runs.
So if you had the above setup and needed to produce a single coverage.json for some external tool, you could do:
{
"scripts": {
"cover:merge": "npm run cover:unit && npm run cover:integration && nyc merge .nyc_output coverage.json"
}
}Source-Map support for pre-instrumented codebases
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.
_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.
Otherwise nyc's reports will exclude any files that source-maps remap to folders covered under exclude rules._
Integrating with coveralls
Integrating with codecov
Producing instrumented source
Integrating with TAP formatters
Many testing frameworks (Mocha, Tape, Tap, etc.) can produce TAP output. tap-nyc is a TAP formatter designed to look nice with nyc.
Tutorials and Advanced Documentation
See more nyc tutorials and advanced nyc documentation.
Please feel free to contribute documentation to help us improve.
nyc for enterprise
Available as part of the Tidelift Subscription.
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.
[@babel/register]: https://www.npmjs.com/package/@babel/register
[babel-plugin-istanbul]: https://github.com/istanbuljs/babel-plugin-istanbul
[@istanbuljs/nyc-config-babel]: https://www.npmjs.com/package/@istanbuljs/nyc-config-babel
[selecting files for coverage]: #selecting-files-for-coverage
---