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 well for applications that spawn subprocesses.

Instrumenting Your Code

Simply run your tests with nyc, and it will collect coverage information for each process and store it in nyc_output:

nyc npm test

If you're so inclined, you can simply add nyc to the test stanza in your package.json:

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

Running Reports

Once you've run your tests with nyc, simply run:

nyc report

To view your coverage report:

--------------------|-----------|-----------|-----------|-----------|
File                |   % Stmts |% Branches |   % Funcs |   % Lines |
--------------------|-----------|-----------|-----------|-----------|
   ./               |     85.96 |        50 |        75 |     92.31 |
      index.js      |     85.96 |        50 |        75 |     92.31 |
   ./test/          |     98.08 |        50 |        95 |     98.04 |
      nyc-test.js   |     98.08 |        50 |        95 |     98.04 |
   ./test/fixtures/ |       100 |       100 |       100 |       100 |
      sigint.js     |       100 |       100 |       100 |       100 |
      sigterm.js    |       100 |       100 |       100 |       100 |
--------------------|-----------|-----------|-----------|-----------|
All files           |     91.89 |        50 |     86.11 |     95.24 |
--------------------|-----------|-----------|-----------|-----------|

you can use any reporters that are supported by istanbul:

nyc report --reporter=lcov

Excluding Files

By default nyc does not instrument files in node_modules, or test for coverage. You can override this setting in your package.json, by adding the following configuration:

{"config": {
  "nyc": {
    "exclude": [
      "node_modules/"
    ]
  }
}}

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. add the environment variable COVERALLS_REPO_TOKEN to travis, this is used by the coveralls bin.

2. add the following to your .travis.yml:

after_success: npm run coverage

That's all there is to it!

Changelog

v2.0.6 (2015/05/23 06:52 +00:00)

• cd70a41 upgrade signal-exit (@bcoe)