Gathering detailed insights and metrics for nyc
An interesting fact about npm is that it started as a weekend project by its creator, Isaac Z. Schlueter, in 2009. It was officially launched in January 2010.
Gathering detailed insights and metrics for nyc
An interesting fact about npm is that it started as a weekend project by its creator, Isaac Z. Schlueter, in 2009. It was officially launched in January 2010.
npm install nyc
56.1
Supply Chain
95.9
Quality
80.6
Maintenance
100
Vulnerability
5,613 Stars
853 Commits
360 Forks
55 Watching
3 Branches
103 Contributors
Updated on 14 Nov 2024
Minified
Minified + Gzipped
JavaScript (100%)
Cumulative downloads
Total Downloads
Last day
39.4%
1,080,834
Compared to previous day
Last week
38.7%
5,423,273
Compared to previous week
Last month
19.2%
19,245,631
Compared to previous month
Last year
18.4%
180,177,327
Compared to previous year
27
Having problems? want to contribute? join our community slack.
Istanbul's state of the art command line interface, with support for:
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.
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):
1{ 2 "scripts": { 3 "test": "mocha", 4 "coverage": "nyc npm run test" 5 } 6}
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
.
1{ 2 "scripts": { 3 "test": "npx nyc@latest mocha" 4 } 5}
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.
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.
1nyc --reporter=lcov --reporter=text-summary ava
Please start with the pre-configured @istanbuljs/nyc-config-babel
preset.
You can add your custom configuration options as shown below.
Please start with the pre-configured @istanbuljs/nyc-config-typescript
preset.
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.
1{ 2 "extends": "@istanbuljs/nyc-config-typescript", 3 "all": true, 4 "check-coverage": true 5}
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 | CommonJS export |
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:
1'use strict'; 2 3const defaultExclude = require('@istanbuljs/schema/default-exclude'); 4const isWindows = require('is-windows'); 5 6let platformExclude = [ 7 isWindows() ? 'lib/posix.js' : 'lib/win32.js' 8]; 9 10module.exports = { 11 exclude: platformExclude.concat(defaultExclude) 12};
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:
1'use strict'; 2 3const babelConfig = require('@istanbuljs/nyc-config-babel'); 4const hookRunInThisContextConfig = require('@istanbuljs/nyc-config-hook-run-in-this-context'); 5 6module.exports = { 7 ...babelConfig, 8 ...hookRunInThisContextConfig, 9 all: true, 10 'check-coverage': true 11};
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:
include
array.exclude
array.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
.
1{ 2 "all": true, 3 "include": [ 4 "src/**/*.js" 5 ], 6 "exclude": [ 7 "**/*.spec.js" 8 ] 9}
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.
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
.
1{ 2 "all": true, 3 "include": [ 4 "lib/**", 5 "node_modules/@my-org/**" 6 ], 7 "exclude": [ 8 "node_modules/@my-org/something/unwanted.js", 9 "**/test/**" 10 ], 11 "excludeNodeModules": false 12}
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:
require
arraynyc may create artifact directories within the project root, with these defaults:
<project-root>/coverage
<project-root>/node_modules/.cache/nyc
<project-root>/.nyc_output
The --require
flag can be provided to nyc
to indicate that additional modules should be required in the subprocess collecting coverage:
1nyc --require esm mocha
--all
flagThe --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
setup 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!
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.
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):
1{ 2 "branches": 80, 3 "lines": 80, 4 "functions": 80, 5 "statements": 80 6}
To do this check on a per-file basis (as opposed to in aggregate), set the per-file
option to true
.
Several of the coverage reporters supported by nyc display special information for high and low watermarks:
You can specify custom high and low watermarks in nyc's configuration:
1{ 2 "watermarks": { 3 "lines": [80, 95], 4 "functions": [80, 95], 5 "branches": [80, 95], 6 "statements": [80, 95] 7 } 8}
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).You can ignore every instance of a method simply by adding its name to the ignore-class-method
array in your nyc
config.
1{ 2 "ignore-class-method": ["render"] 3}
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:
1{ 2 "scripts": { 3 "cover": "npm run cover:unit && npm run cover:integration && npm run cover:report", 4 "cover:unit": "nyc --silent npm run test:unit", 5 "cover:integration": "nyc --silent --no-clean npm run test:integration", 6 "cover:report": "nyc report --reporter=lcov --reporter=text" 7 } 8}
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:
1{ 2 "scripts": { 3 "cover:merge": "npm run cover:unit && npm run cover:integration && nyc merge .nyc_output coverage.json" 4 } 5}
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.
Many testing frameworks (Mocha, Tape, Tap, etc.) can produce TAP output. tap-nyc is a TAP formatter designed to look nice with nyc.
See more nyc tutorials and advanced nyc documentation.
Please feel free to contribute documentation to help us improve.
nyc
for enterpriseAvailable 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.
No vulnerabilities found.
Reason
license file detected
Details
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
security policy file detected
Details
Reason
0 existing vulnerabilities detected
Reason
Found 10/22 approved changesets -- score normalized to 4
Reason
dependency not pinned by hash detected -- score normalized to 3
Details
Reason
3 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 2
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
project is not fuzzed
Details
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
Score
Last Scanned on 2024-11-04
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn Morevite-plugin-istanbul
vite-plugin-istanbul ========================== [![Codacy grade](https://img.shields.io/codacy/grade/a0c628b128c044269faefc1da74382f7?style=for-the-badge&logo=codacy)](https://www.codacy.com/gh/iFaxity/vite-plugin-istanbul/dashboard) [![npm (scoped)](http
@istanbuljs/load-nyc-config
Utility function to load nyc configuration
@istanbuljs/schema
Schemas describing various structures used by nyc and istanbuljs
@temporalio/nyc-test-coverage
Temporal.io SDK code coverage integration