nyc

nyc npm test

a code coverage tool built on istanbul that works 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

you can pass a list of Istanbul reporters that you'd like to run:

nyc --reporter=lcov --reporter=text-lcov 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"
  }
}

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.

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

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

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

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