nyc
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.
- ES2015 transforms, via babel-plugin-istanbul, or source-maps.
Instrumenting your code
You can install nyc as a development dependency and add it to the test stanza in your package.json.
npm i nyc --save-dev
{
"scripts": {
"test": "nyc mocha"
}
}
Alternatively, you can install nyc globally and use it to execute npm test
:
npm i nyc -g
nyc npm test
nyc accepts a wide variety of configuration arguments, run nyc --help
for
thorough documentation.
Configuration arguments should be provided prior to the program that nyc
is executing. As an example, the following command executes npm test
,
and indicates to nyc that it should output both an lcov
and a text-lcov
coverage report.
nyc --reporter=lcov --reporter=text-lcov npm test
Accurate stack traces using source-maps
When produce-source-map
is set to true, then the instrumented source files will
include inline source maps for the instrumenter transform. When combined with
source-map-support,
stack traces for instrumented code will reflect their original lines.
Support for custom require hooks (babel, typescript, etc.)
nyc supports custom require hooks like
babel-register
. nyc can
load the hooks for you, using the --require
flag.
Source maps are used to map coverage information back to the appropriate lines
of the pre-transpiled code. You'll have to configure your custom require hook
to inline the source-map in the transpiled code. For Babel that means setting
the sourceMaps
option to inline
.
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.
babel-plugin-istanbul
for Babel Support
Use with We recommend using babel-plugin-istanbul
if your
project uses the babel tool chain:
- enable the
babel-plugin-istanbul
plugin:
{
"babel": {
"presets": ["env"],
"env": {
"test": {
"plugins": ["istanbul"]
}
}
}
}
Note: With this configuration, the Istanbul instrumentation will only be active when NODE_ENV
or BABEL_ENV
is test
.
We recommend using the cross-env
package to set these environment variables
in your package.json
scripts in a way that works cross-platform.
- disable nyc's instrumentation and source-maps, e.g. in
package.json
:
{
"nyc": {
"require": [
"babel-register"
],
"sourceMap": false,
"instrument": false
},
"scripts": {
"test": "cross-env NODE_ENV=test nyc mocha"
}
}
That's all there is to it, better ES2015+ syntax highlighting awaits:
Support for alternate file extensions (.jsx, .mjs)
Supporting file extensions can be configured through either the configuration arguments or with the nyc
config section in package.json
.
nyc --extension .jsx --extension .mjs npm test
{
"nyc": {
"extension": [
".jsx",
".mjs"
]
}
}
Checking coverage
nyc can fail tests if coverage falls below a threshold. After running your tests with nyc, simply run:
nyc check-coverage --lines 95 --functions 95 --branches 95
nyc also accepts a --check-coverage
shorthand, which can be used to
both run tests and check that coverage falls within the threshold provided:
nyc --check-coverage --lines 100 npm test
The above check fails if coverage falls below 100%.
To check thresholds on a per-file basis run:
nyc check-coverage --lines 95 --per-file
Running reports
Once you've run your tests with nyc, simply run:
nyc report
To view your coverage report:
You can use any reporters that are supported by istanbul
: clover
, cobertura
, html
, json-summary
, json
, lcov
, lcovonly
, none
, teamcity
, text-lcov
, text-summary
, text
.
nyc report --reporter=lcov
You can find examples of the output for various reporters here.
Excluding files
You can tell nyc to exclude specific files and directories by adding
an nyc.exclude
array to your package.json
. Each element of
the array is a glob pattern indicating which paths should be omitted.
Globs are matched using micromatch.
For example, the following config will exclude any files with the extension .spec.js
,
and anything in the build
directory:
{
"nyc": {
"exclude": [
"**/*.spec.js",
"build"
]
}
}
Note: Since version 9.0 files under
node_modules/
are excluded by default. add the exclude rule!**/node_modules/
to stop this.
Note: exclude defaults to
['coverage/**', 'test/**', 'test{,-*}.js', '**/*.test.js', '**/__tests__/**', '**/node_modules/**']
, which would excludetest
/__tests__
directories as well astest.js
,*.test.js
, andtest-*.js
files. Specifying your own exclude property overrides these defaults.
Including files
As an alternative to providing a list of files to exclude
, you can provide
an include
key with a list of globs to specify specific files that should be covered:
{
"nyc": {
"include": ["**/build/umd/moment.js"]
}
}
Note: include defaults to
['**']
Use the
--all
flag to include files that have not been required in your tests.
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 babel-register --require babel-polyfill mocha
Caching
You can run nyc
with the optional --cache
flag, to prevent it from
instrumenting the same files multiple times. This can significantly
improve runtime performance.
nyc
Configuring 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 .nycrc
file:
package.json:
{
"description": "These are just examples for demonstration, nothing prescriptive",
"nyc": {
"check-coverage": true,
"per-file": true,
"lines": 99,
"statements": 99,
"functions": 99,
"branches": 99,
"include": [
"src/**/*.js"
],
"exclude": [
"src/**/*.spec.js"
],
"reporter": [
"lcov",
"text-summary"
],
"require": [
"./test/helpers/some-helper.js"
],
"extension": [
".jsx"
],
"cache": true,
"all": true,
"report-dir": "./alternative"
}
}
Publish, and reuse, your nyc configuration
nyc allows you to inherit other configurations using the key extends
. As an example,
an alternative way to configure nyc for babel-plugin-istanbul
would be to use the
@istanbuljs/nyc-config-babel preset:
{
"nyc": {
"extends": "@istanbuljs/nyc-config-babel"
}
}
To publish and resuse your own nyc
configuration, simply create an npm module that
exports an index.json
with your nyc
config.
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:
{
"nyc": {
"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).
Integrating with coveralls
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:
- add the coveralls and nyc dependencies to your module:
npm install coveralls nyc --save-dev
- update the scripts in your package.json to include these bins:
{
"scripts": {
"test": "nyc mocha",
"coverage": "nyc report --reporter=text-lcov | coveralls"
}
}
-
For private repos, add the environment variable
COVERALLS_REPO_TOKEN
to travis. -
add the following to your
.travis.yml
:
after_success: npm run coverage
That'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?
.
Integrating with codecov
nyc npm test && nyc report --reporter=text-lcov > coverage.lcov && codecov
codecov is a great tool for adding coverage reports to your GitHub project, even viewing them inline on GitHub with a browser extension:
Here's how to get nyc
integrated with codecov and travis-ci.org:
- add the codecov and nyc dependencies to your module:
npm install codecov nyc --save-dev
- update the scripts in your package.json to include these bins:
{
"scripts": {
"test": "nyc tap ./test/*.js",
"coverage": "nyc report --reporter=text-lcov > coverage.lcov && codecov"
}
}
-
For private repos, add the environment variable
CODECOV_TOKEN
to travis. -
add the following to your
.travis.yml
:
after_success: npm run coverage
That's all there is to it!
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.
More tutorials
You can find more tutorials at http://istanbul.js.org/docs/tutorials
Other advanced features
Take a look at http://istanbul.js.org/docs/advanced/ and please feel free to contribute documentation.