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.

You can install nyc as a development dependency and add it to the test stanza in your package.json.

npm i nyc --save-dev

{
  "script": {
    "test": "nyc tap ./test/*.js"
  }
}

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

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.

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.

babel-plugin-istanbul can be used to enable better first-class ES6 support.

1. enable the babel-plugin-istanbul plugin:

  {
    "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 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:

{
  "nyc": {
    "include": [
      "src/*.js"
    ],
    "require": [
      "babel-register"
    ],
    "sourceMap": false,
    "instrument": false
  }
}

That's all there is to it, better ES6 syntax highlighting awaits:

Supporting file extensions can be configured through either the configuration arguments or with the nyc config section in package.json.

nyc --extension .jsx --extension .es6 npm test

{
  "nyc": {
    "extension": [
      ".jsx",
      ".es6"
    ]
  }
}

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%.

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:

nyc report --reporter=lcov

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 ['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.

As an alternative to providing a list of files to exclude, you can provide an include key to specify specific files that should be covered:

{
  "nyc": {
    "include": ["**/build/umd/moment.js"]
  }
}

Note: include defaults to ['**']

By default nyc does not collect coverage for files that have not been required, run nyc with the flag --all to enable this.

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

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.

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": {
    "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,
    "check-coverage": true,
    "report-dir": "./alternative"
  }
}

.nycrc:

{
  "reporter": [
    "lcov",
    "text-summary"
  ],
  "require": [
    "./test/helpers/some-helper.js"
  ]
}

nyc's instrument command can be used to instrument source files outside of the context of your unit-tests:

instrument the entire ./lib folder:

nyc instrument ./lib ./output

nyc is able to show you all Node processes that are spawned when running a test script under it:

$ nyc --show-process-tree npm test
   3 passed
----------|----------|----------|----------|----------|----------------|
File      |  % Stmts | % Branch |  % Funcs |  % Lines |Uncovered Lines |
----------|----------|----------|----------|----------|----------------|
All files |      100 |      100 |      100 |      100 |                |
 index.js |      100 |      100 |      100 |      100 |                |
----------|----------|----------|----------|----------|----------------|
nyc
└─┬ /usr/local/bin/node /usr/local/bin/npm test
  └─┬ /usr/local/bin/node /path/to/your/project/node_modules/.bin/ava
    └── /usr/local/bin/node /path/to/your/project/node_modules/ava/lib/test-worker.js …

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]
    }
  }
}

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-dev

2. update the scripts in your package.json to include these bins:

{
   "script": {
     "test": "nyc tap ./test/*.js",
     "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:

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?.

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:

1. add the codecov and nyc dependencies to your module:

npm install codecov nyc --save-dev

2. update the scripts in your package.json to include these bins:

{
   "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:

after_success: npm run coverage

That's all there is to it!