Skip to content

Latest commit

 

History

History
490 lines (363 loc) · 15.2 KB

README.md

File metadata and controls

490 lines (363 loc) · 15.2 KB
Raw

nyc

Build Status Coverage Status NPM version Conventional Commits community slack

Having problems? want to contribute? join our community slack.

Istanbul's state of the art command line interface, with support for:

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
{
  "scripts": {
    "test": "nyc mocha"
  }
}

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

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

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) 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 if your project uses the babel tool chain:

  1. enable the babel-plugin-istanbul plugin:
  {
    "babel": {
      "presets": ["@babel/preset-env"],
      "env": {
        "test": {
          "plugins": ["istanbul"]
        }
      }
    }
  }

Note: With this configuration, the Istanbul instrumentation will only be active when NODE_ENV or BABEL_ENV is test unless the environment is a valid entry in "env" within the .babelrc file.

We recommend using the cross-env package to set these environment variables in your package.json scripts in a way that works cross-platform.

  1. disable nyc's instrumentation and source-maps, e.g. in package.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.

nyc --extension .jsx --extension .mjs npm test
{
  "nyc": {
    "extension": [
      ".jsx",
      ".mjs"
    ]
  }
}

Checking coverage

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

To check thresholds on a per-file basis run:

nyc check-coverage --lines 95 --per-file

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: clover, cobertura, html, json-summary, json, lcov, lcovonly, none, teamcity, text-lcov, text-summary, text.

nyc report --reporter=lcov

You can find examples of the output for various reporters here.

You also have the choice of using a custom reporter. Install custom reporters as a development dependency and you can use the --reporter flag to load and view them:

nyc report --reporter=<custom-reporter-name>

Selecting files for coverage

By default, nyc only collects coverage for source files that are visited during a test. It does this by watching for files that are require()'d during the test. Only source files that are visited during a test will appear in the coverage report and contribute to coverage statistics.

nyc will instrument all files if the --all flag is set. In this case all files will appear in the coverage report and contribute to coverage statistics.

nyc will only collect coverage for files that are located under cwd, and then only *.js files or files with extensions listed in in the extension array.

You can reduce the set of covered files by adding include and exclude filter arrays to your config. These allow you to shape the set of covered files by specifying glob patterns that can filter files from the covered set. The exclude array may also use exclude negated glob patterns, these are specified with a ! prefix, and can restore sub-paths of excluded paths.

Globs are matched using minimatch.

We use the following process to remove files from consideration:

  1. Limit the set of covered files to those files in paths listed in the include array.
  2. Remove any files that are found in the exclude array.
  3. Restore any exclude negated files that have been excluded in the second step.

Using include and exclude arrays

If there are paths specified in the include array, then the set of covered files will be limited to eligible files found in those paths. If the include array is left undefined all eligible files will be included, equivalent to setting include: ['**']. Include options can be specified on the command line with the -n switch.

If there are paths specified in the exclude array, then the set of covered files will not feature eligible files found in those paths. You can also specify negated paths in the exclude array, by prefixing them with a !. Negated paths can restore paths that have been already been excluded in the exclude array. Exclude options can be specified on the command line with the -x switch.

The exclude option has the following defaults settings:

[
  'coverage/**',
  'packages/*/test/**',
  'test/**',
  'test{,-*}.js',
  '**/*{.,-}test.js',
  '**/__tests__/**',
  '**/node_modules/**',
  '**/babel.config.js'
]

These settings exclude test and __tests__ directories as well as test.js, *.test.js, and test-*.js files. Specifying your own exclude property completely replaces these defaults.

Note: The exclude list always implicitly contains **/node_modules/**, even if not explicitly specified in an overriding exclude array. To reverse this you must add the negated exclude rule !**/node_modules/.

For example, the following config will collect coverage for every file in the src directory regardless of whether it is require()'d in a test. It will also exclude any files with the extension .spec.js.

{
  "nyc": {
    "all": true,
    "include": [
      "src/**/*.js"
    ],
    "exclude": [
      "**/*.spec.js"
    ]
  }
}

Note: Be wary of automatic OS glob expansion when specifying include/exclude globs with the CLI. To prevent this, wrap each glob in single quotes.

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

nyc's default behavior is to cache instrumented files to disk to prevent instrumenting source files multiple times, and speed nyc execution times. You can disable this behavior by running nyc with the --cache false flag. You can also change the default cache directory from ./node_modules/.cache/nyc by setting the --cache-dir flag.

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 (or .nycrc.json) file:

package.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"
    ],
    "ignore-class-method": "methodToIgnore",
    "reporter": [
      "lcov",
      "text-summary"
    ],
    "require": [
      "./test/helpers/some-helper.js"
    ],
    "extension": [
      ".jsx"
    ],
    "cache": true,
    "all": true,
    "temp-dir": "./alternative-tmp",
    "report-dir": "./alternative"
  }
}

Configuration can also be provided by nyc.config.js if programmed logic is required:

'use strict';
const {defaultExclude} = require('test-exclude');
const isWindows = require('is-windows');

let platformExclude = [
  isWindows() ? 'lib/posix.js' : 'lib/win32.js'
];

module.exports = {
  exclude: platformExclude.concat(defaultExclude)
};

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:

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

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

Ignoring Methods

There may be some methods that you want to universally ignore out of your classes rather than having to ignore every instance of that method:

{
  "nyc": {
    "ignore-class-method": "render"
  }
}

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-dev
  1. update the scripts in your package.json to include these bins:
{
   "scripts": {
     "test": "nyc mocha",
     "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?.

Integrating with codecov

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
  1. update the scripts in your package.json to include these bins:
{
   "scripts": {
     "test": "nyc tap ./test/*.js",
     "coverage": "nyc report --reporter=text-lcov > coverage.lcov && codecov"
   }
}

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

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

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