Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
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.
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"
}
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 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 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 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.
Istanbul's state of the art command line interface, with support for:
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 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
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.
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
.
babel-plugin-istanbul
for ES2015+ Supportbabel-plugin-istanbul
can be used to enable first-class ES2015+ support.
babel-plugin-istanbul
plugin: {
"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
package to set these environment variables
in your package.json
scripts in a way that works cross-platform.
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:
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"
]
}
}
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%.
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
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.
For example, the following config will exclude any files with the extension .spec.js
,
and anything in the build
directory:
{
"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 excludetest
/__tests__
directories as well astest.js
,*.test.js
, andtest-*.js
files. Specifying your own exclude property overrides these defaults.
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:
{
"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.
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
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.
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:
{
"description": "These are just examples for demonstration, nothing prescriptive",
"nyc": {
"check-coverage": 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"
}
}
Several of the coverage reporters supported by nyc display special information for high and low watermarks:
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]
}
}
}
Take a look at http://istanbul.js.org/docs/advanced/ and please feel free to contribute documentation.
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:
npm install coveralls nyc --save-dev
{
"script": {
"test": "nyc mocha",
"coverage": "nyc report --reporter=text-lcov | coveralls"
}
}
For private repos, add the environment variable COVERALLS_REPO_TOKEN
to travis.
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?
.
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:
npm install codecov nyc --save-dev
{
"script": {
"test": "nyc tap ./test/*.js",
"coverage": "nyc report --reporter=text-lcov > coverage.lcov && codecov"
}
}
For private repos, add the environment variable CODECOV_TOKEN
to travis.
add the following to your .travis.yml
:
after_success: npm run coverage
That's all there is to it!
You can find more tutorials at http://istanbul.js.org/docs/tutorials
FAQs
the Istanbul command line interface
The npm package nyc receives a total of 3,186,234 weekly downloads. As such, nyc popularity was classified as popular.
We found that nyc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.