# nyc
[](https://travis-ci.org/istanbuljs/nyc)
[](https://coveralls.io/r/bcoe/nyc?branch=master)
[](https://www.npmjs.com/package/nyc)
[](https://ci.appveyor.com/project/bcoe/nyc-ilw23)
[](https://conventionalcommits.org)
[](http://devtoolscommunity.herokuapp.com)
_Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com)_.
Istanbul's state of the art command line interface, with support for:
* applications that spawn subprocesses.
* ES2015 transforms, via [babel-plugin-istanbul](https://github.com/istanbuljs/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.
```shell
npm i nyc --save-dev
```
```json
{
"script": {
"test": "nyc mocha"
}
}
```
Alternatively, you can install nyc globally and use it to execute `npm test`:
```shell
npm i nyc -g
```
```shell
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.
```shell
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](https://github.com/evanw/node-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`](http://babeljs.io/docs/usage/require/). nyc can
load the hooks for you, [using the `--require`
flag](#require-additional-modules).
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`](http://babeljs.io/docs/usage/require/))
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._
## Use with `babel-plugin-istanbul` for Babel Support
We recommend using [`babel-plugin-istanbul`](https://github.com/istanbuljs/babel-plugin-istanbul) if your
project uses the babel tool chain:
1. enable the `babel-plugin-istanbul` plugin:
```json
{
"babel": {
"presets": ["es2015"],
"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`](https://npmjs.com/package/cross-env) package to set these environment variables
in your `package.json` scripts in a way that works cross-platform.
2. disable nyc's instrumentation and source-maps, e.g. in `package.json`:
```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`.
```shell
nyc --extension .jsx --extension .mjs npm test
```
```json
{
"nyc": {
"extension": [
".jsx",
".mjs"
]
}
}
```
## Checking coverage
nyc can fail tests if coverage falls below a threshold.
After running your tests with nyc, simply run:
```shell
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:
```shell
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:
```shell
nyc --check-coverage --lines 95 --per-file
```
## Running reports
Once you've run your tests with nyc, simply run:
```bash
nyc report
```
To view your coverage report:
You can use [any reporters that are supported by `istanbul`](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib): `clover`, `cobertura`, `html`, `json-summary`, `json`, `lcov`, `lcovonly`, `none`, `teamcity`, `text-lcov`, `text-summary`, `text`.
```bash
nyc report --reporter=lcov
```
You can find examples of the output for various reporters [here](https://istanbul.js.org/docs/advanced/alternative-reporters).
## 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](https://www.npmjs.com/package/micromatch).
For example, the following config will exclude any files with the extension `.spec.js`,
and anything in the `build` directory:
```json
{
"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 `['test', 'test{,-*}.js', '**/*.test.js', '**/__tests__/**', '**/node_modules/**']`,
which would exclude `test`/`__tests__` directories as well as `test.js`, `*.test.js`,
and `test-*.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:
```json
{
"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.
## Configuring `nyc`
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:**
```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](https://www.npmjs.com/package/@istanbuljs/nyc-config-babel):
```json
{
"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:
```json
{
"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](https://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:
```shell
npm install coveralls nyc --save-dev
```
2. update the scripts in your package.json to include these bins:
```json
{
"script": {
"test": "nyc mocha",
"coverage": "nyc report --reporter=text-lcov | coveralls"
}
}
```
3. For private repos, add the environment variable `COVERALLS_REPO_TOKEN` to travis.
4. add the following to your `.travis.yml`:
```yaml
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](https://codecov.io/) 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:
1. add the codecov and nyc dependencies to your module:
```shell
npm install codecov nyc --save-dev
```
2. update the scripts in your package.json to include these bins:
```json
{
"script": {
"test": "nyc tap ./test/*.js",
"coverage": "nyc report --reporter=text-lcov > coverage.lcov && codecov"
}
}
```
3. For private repos, add the environment variable `CODECOV_TOKEN` to travis.
4. add the following to your `.travis.yml`:
```yaml
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](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.
## 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](https://github.com/istanbuljs/istanbuljs.github.io/tree/development/content).