429 lines
12 KiB
Markdown
429 lines
12 KiB
Markdown
# nyc
|
|
|
|
[](https://travis-ci.org/istanbuljs/nyc)
|
|
[](https://coveralls.io/r/bcoe/nyc?branch=master)
|
|
[](https://www.npmjs.com/package/nyc)
|
|
[](https://ci.appveyor.com/project/bcoe/nyc-ilw23)
|
|
[](https://conventionalcommits.org)
|
|
[](http://devtoolscommunity.herokuapp.com)
|
|
|
|
_Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com)_.
|
|
|
|
Istanbul's state of the art command line interface, with support for:
|
|
|
|
* applications that spawn subprocesses.
|
|
* ES2015 transforms, via [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul), or source-maps.
|
|
|
|
## Instrumenting your code
|
|
|
|
You can install nyc as a development dependency and add it to the test stanza
|
|
in your package.json.
|
|
|
|
```shell
|
|
npm i nyc --save-dev
|
|
```
|
|
|
|
```json
|
|
{
|
|
"script": {
|
|
"test": "nyc mocha"
|
|
}
|
|
}
|
|
```
|
|
|
|
Alternatively, you can install nyc globally and use it to execute `npm test`:
|
|
|
|
```shell
|
|
npm i nyc -g
|
|
```
|
|
|
|
```shell
|
|
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.
|
|
|
|
```shell
|
|
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](https://github.com/evanw/node-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`](http://babeljs.io/docs/usage/require/). nyc can
|
|
load the hooks for you, [using the `--require`
|
|
flag](#require-additional-modules).
|
|
|
|
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`](http://babeljs.io/docs/usage/require/))
|
|
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`](https://github.com/istanbuljs/babel-plugin-istanbul) if your
|
|
project uses the babel tool chain:
|
|
|
|
1. enable the `babel-plugin-istanbul` plugin:
|
|
|
|
```json
|
|
{
|
|
"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`](https://npmjs.com/package/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, e.g. in `package.json`:
|
|
|
|
```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:
|
|
|
|
<img width="500" src="screen2.png">
|
|
|
|
## 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`.
|
|
|
|
```shell
|
|
nyc --extension .jsx --extension .mjs npm test
|
|
```
|
|
|
|
```json
|
|
{
|
|
"nyc": {
|
|
"extension": [
|
|
".jsx",
|
|
".mjs"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Checking coverage
|
|
|
|
nyc can fail tests if coverage falls below a threshold.
|
|
After running your tests with nyc, simply run:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
nyc --check-coverage --lines 95 --per-file
|
|
```
|
|
|
|
## Running reports
|
|
|
|
Once you've run your tests with nyc, simply run:
|
|
|
|
```bash
|
|
nyc report
|
|
```
|
|
|
|
To view your coverage report:
|
|
|
|
<img width="500" src="screen.png">
|
|
|
|
You can use [any reporters that are supported by `istanbul`](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib): `clover`, `cobertura`, `html`, `json-summary`, `json`, `lcov`, `lcovonly`, `none`, `teamcity`, `text-lcov`, `text-summary`, `text`.
|
|
|
|
```bash
|
|
nyc report --reporter=lcov
|
|
```
|
|
|
|
You can find examples of the output for various reporters [here](https://istanbul.js.org/docs/advanced/alternative-reporters).
|
|
|
|
## 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](https://www.npmjs.com/package/micromatch).
|
|
|
|
For example, the following config will exclude any files with the extension `.spec.js`,
|
|
and anything in the `build` directory:
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
## Including files
|
|
|
|
As an alternative to providing a list of files to `exclude`, you can provide
|
|
an `include` key with a list of globs to specify specific files that should be covered:
|
|
|
|
```json
|
|
{
|
|
"nyc": {
|
|
"include": ["**/build/umd/moment.js"]
|
|
}
|
|
}
|
|
```
|
|
|
|
> Note: include defaults to `['**']`
|
|
|
|
> ### Use the `--all` flag to include files that have not been required in your tests.
|
|
|
|
## 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
|
|
|
|
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.
|
|
|
|
## 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` file:
|
|
|
|
**package.json:**
|
|
|
|
```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"
|
|
],
|
|
"reporter": [
|
|
"lcov",
|
|
"text-summary"
|
|
],
|
|
"require": [
|
|
"./test/helpers/some-helper.js"
|
|
],
|
|
"extension": [
|
|
".jsx"
|
|
],
|
|
"cache": true,
|
|
"all": true,
|
|
"report-dir": "./alternative"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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](https://www.npmjs.com/package/@istanbuljs/nyc-config-babel):
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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).
|
|
|
|
## Integrating with coveralls
|
|
|
|
[coveralls.io](https://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:
|
|
|
|
```shell
|
|
npm install coveralls nyc --save-dev
|
|
```
|
|
|
|
2. update the scripts in your package.json to include these bins:
|
|
|
|
```json
|
|
{
|
|
"script": {
|
|
"test": "nyc mocha",
|
|
"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`:
|
|
|
|
```yaml
|
|
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](https://codecov.io/) 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:
|
|
|
|
```shell
|
|
npm install codecov nyc --save-dev
|
|
```
|
|
|
|
2. update the scripts in your package.json to include these bins:
|
|
|
|
```json
|
|
{
|
|
"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`:
|
|
|
|
```yaml
|
|
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](https://en.wikipedia.org/wiki/Test_Anything_Protocol) output. [tap-nyc](https://github.com/MegaArman/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](https://github.com/istanbuljs/istanbuljs.github.io/tree/development/content).
|