nyc

What is nyc?

The nyc npm package is a command-line tool that allows for JavaScript code coverage. It is built on top of Istanbul and works well with subprocesses. It is often used for tracking how well your unit-tests exercise your codebase.

What are nyc's main functionalities?

Code Coverage

This feature allows you to collect code coverage information from your tests. You can use it with a test runner like mocha by adding it to your npm scripts in your package.json file.

"scripts": {
  "test": "nyc mocha"
}

Check Coverage Thresholds

nyc can enforce coverage thresholds. If code coverage falls below the specified thresholds, nyc will exit with a failure status. This is useful for maintaining a high standard of test coverage in a project.

"scripts": {
  "test": "nyc --check-coverage --lines 95 --functions 95 --branches 95 mocha"
}

Report Generation

After running your tests with nyc, you can generate various types of coverage reports. This example shows how to generate a report in the 'lcov' format, which can be used with tools that support lcov coverage reports.

"scripts": {
  "coverage": "nyc report --reporter=text-lcov > coverage.lcov"
}

Integration with CI/CD

nyc can be integrated with continuous integration/continuous deployment (CI/CD) systems. In this example, coverage information is piped to the 'coveralls' service to track coverage over time.

"scripts": {
  "coveralls": "nyc report --reporter=text-lcov | coveralls"
}

Other packages similar to nyc

istanbul

Istanbul is the underlying tool that nyc is built upon. It provides a JavaScript code coverage tool that computes statement, line, function, and branch coverage with module loader hooks to instrument code on the fly.

c8

c8 is a code coverage tool that uses Node.js' built-in V8 coverage. It is similar to nyc but does not use instrumented code and is built directly on V8's native coverage features, potentially providing more accurate coverage metrics.

jest

Jest is a delightful JavaScript Testing Framework with a focus on simplicity. It works out of the box for any React project. Jest provides its own way to track code coverage without needing an additional package like nyc.

blanket

Blanket is a simple code coverage library for JavaScript that works both in the browser and with Node.js. It is less commonly used now and has been largely superseded by tools like nyc and istanbul.

README

nyc

a code coverage tool built on istanbul that works for applications that spawn subprocesses.

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

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

Support For Custom Require Hooks (Babel! ES2015!)

nyc supports custom require hooks like babel-register. If necessary 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.

Support For Custom File Extensions (.jsx, .es6)

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

Checking Coverage

nyc exposes istanbul's check-coverage tool. After running your tests with nyc, simply run:

nyc check-coverage --lines 95 --functions 95 --branches 95

This feature makes it easy to fail your tests if coverage drops below a given threshold.

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

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:

nyc report --reporter=lcov

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.

In addition to patterns specified in the package, nyc will always exclude files in node_modules.

For example, the following config will exclude everything in node_modules, any files with the extension .spec.js, and anything in the build directory:

{
  "nyc": {
    "exclude": [
      "**/*.spec.js",
      "build"
    ]
  }
}

Note: exclude defaults to ['test', 'test{,-*}.js'], which would exclude the test directory as well as test.js and test-*.js files

Including Files

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 ['**']

Include Reports For Files That Are Not Required

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

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-core/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 signficantly 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:

{
  "nyc": {
    "lines": 99,
    "check-coverage": false,
    "report-dir": "./alternative"
  }
}

Configuring Istanbul

Behind the scenes nyc uses istanbul. You can place a .istanbul.yml file in your project's root directory to pass config setings to istanbul's code instrumenter:

instrumentation:
  preserve-comments: true

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:

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

npm install coveralls nyc --save

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

{
   "script": {
     "test": "nyc tap ./test/*.js",
     "coverage": "nyc report --reporter=text-lcov | coveralls"
   }
}

1. For private repos, add the environment variable COVERALLS_REPO_TOKEN to travis.

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

Changelog

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)