Research
Security News
Malicious npm Packages Inject SSH Backdoors via Typosquatted Libraries
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Yet another JS code coverage tool that computes statement, line, function and branch coverage with module loader hooks to transparently add coverage when running tests. Supports all JS coverage use cases including unit tests, server side functional tests
Istanbul is a popular JavaScript code coverage tool that helps developers measure how much of their code is being tested. It provides detailed reports and integrates well with various testing frameworks.
Code Coverage
Istanbul can be used to generate code coverage reports in various formats such as HTML, lcov, and text. This helps developers understand which parts of their code are covered by tests.
const istanbul = require('istanbul');
const collector = new istanbul.Collector();
const reporter = new istanbul.Reporter();
reporter.addAll(['html', 'lcov', 'text']);
reporter.write(collector, true, () => {
console.log('Coverage report generated');
});
Instrumenting Code
Istanbul can instrument your code, which means it adds hooks to your code to track which parts are executed during a test run. This is essential for generating accurate coverage reports.
const istanbul = require('istanbul');
const instrumenter = new istanbul.Instrumenter();
const fs = require('fs');
const code = fs.readFileSync('path/to/your/file.js', 'utf8');
instrumenter.instrument(code, 'path/to/your/file.js', (err, instrumentedCode) => {
if (err) {
console.error(err);
} else {
fs.writeFileSync('path/to/your/instrumentedFile.js', instrumentedCode);
}
});
Integration with Testing Frameworks
Istanbul integrates well with various testing frameworks like Mocha, Jasmine, and Jest. This allows you to run your tests and generate coverage reports seamlessly.
const Mocha = require('mocha');
const istanbul = require('istanbul');
const mocha = new Mocha();
const collector = new istanbul.Collector();
const reporter = new istanbul.Reporter();
mocha.addFile('test/yourTestFile.js');
mocha.run(() => {
reporter.addAll(['html', 'lcov', 'text']);
reporter.write(collector, true, () => {
console.log('Coverage report generated');
});
});
NYC is a command-line interface for Istanbul. It provides a simpler way to use Istanbul's features and is often used in modern JavaScript projects. NYC is essentially a wrapper around Istanbul, making it easier to use with minimal configuration.
Jest is a JavaScript testing framework developed by Facebook. It comes with built-in code coverage support, which is powered by Istanbul under the hood. Jest provides an all-in-one solution for testing and code coverage, making it a popular choice for React and Node.js projects.
C8 is a code coverage tool that uses V8's built-in coverage feature. It is faster and more accurate than Istanbul for Node.js projects because it leverages the V8 JavaScript engine's native capabilities. C8 is a good alternative for projects that require high performance and accuracy.
esprima
parser and the equally awesome escodegen
code generatorSupports the following use cases and more
$ npm install -g istanbul
The best way to see it in action is to run node unit tests. Say you have a test
script test.js
that runs all tests for your node project without coverage.
Simply:
$ cd /path/to/your/source/root
$ istanbul cover test.js
and this should produce a coverage.json
, lcov.info
and lcov-report/*html
under ./coverage
Sample of code coverage reports produced by this tool (for this tool!):
Drop a .istanbul.yml
file at the top of the source tree to configure istanbul.
istanbul help config
tells you more about the config file format.
$ istanbul help
gives you detailed help on all commands.
Usage: istanbul help config | <command>
`config` provides help with istanbul configuration
Available commands are:
check-coverage
checks overall/per-file coverage against thresholds from coverage
JSON files. Exits 1 if thresholds are not met, 0 otherwise
cover transparently adds coverage information to a node command. Saves
coverage.json and reports at the end of execution
help shows help
instrument
instruments a file or a directory tree and writes the
instrumented code to the desired output location
report writes reports for coverage JSON objects produced in a previous
run
test cover a node command only when npm_config_coverage is set. Use in
an `npm test` script for conditional coverage
Command names can be abbreviated as long as the abbreviation is unambiguous
To get detailed help for a command and what command-line options it supports, run:
istanbul help <command>
(Most of the command line options are not covered in this document.)
cover
command$ istanbul cover my-test-script.js -- my test args
# note the -- between the command name and the arguments to be passed
The cover
command can be used to get a coverage object and reports for any arbitrary
node script. By default, coverage information is written under ./coverage
- this
can be changed using command-line options.
The cover
command can also be passed an optional --handle-sigint
flag to
enable writing reports when a user triggers a manual SIGINT of the process that is
being covered. This can be useful when you are generating coverage for a long lived process.
test
commandThe test
command has almost the same behavior as the cover
command, except that
it skips coverage unless the npm_config_coverage
environment variable is set.
This command is deprecated since the latest versions of npm do not seem to
set the npm_config_coverage
variable.
instrument
commandInstruments a single JS file or an entire directory tree and produces an output directory tree with instrumented code. This should not be required for running node unit tests but is useful for tests to be run on the browser.
report
commandWrites reports using coverage*.json
files as the source of coverage information.
Reports are available in multiple formats and can be individually configured
using the istanbul config file. See istanbul help report
for more details.
check-coverage
commandChecks the coverage of statements, functions, branches, and lines against the provided thresholds. Positive thresholds are taken to be the minimum percentage required and negative numbers are taken to be the number of uncovered entities allowed.
if
or else
path with /* istanbul ignore if */
or /* istanbul ignore else */
respectively./* istanbul ignore next */
See ignoring-code-for-coverage.md for the spec.
All the features of istanbul can be accessed as a library.
var istanbul = require('istanbul');
var instrumenter = new istanbul.Instrumenter();
var generatedCode = instrumenter.instrumentSync('function meaningOfLife() { return 42; }',
'filename.js');
var istanbul = require('istanbul'),
collector = new istanbul.Collector(),
reporter = new istanbul.Reporter(),
sync = false;
collector.add(obj1);
collector.add(obj2); //etc.
reporter.add('text');
reporter.addAll([ 'lcov', 'clover' ]);
reporter.write(collector, sync, function () {
console.log('All reports generated');
});
For the gory details consult the public API
Istanbul can be used in a multiple process environment by running each process with Istanbul, writing a unique coverage file for each process, and combining the results when generating reports. The method used to perform this will depend on the process forking API used. For example when using the cluster module you must setup the master to start child processes with Istanbul coverage, disable reporting, and output coverage files that include the PID in the filename. Before each run you may need to clear out the coverage data directory.
if(cluster.isMaster) {
// setup cluster if running with istanbul coverage
if(process.env.running_under_istanbul) {
// use coverage for forked process
// disabled reporting and output for child process
// enable pid in child process coverage filename
cluster.setupMaster({
exec: './node_modules/.bin/istanbul',
args: [
'cover', '--report', 'none', '--print', 'none', '--include-pid',
process.argv[1], '--'].concat(process.argv.slice(2))
});
}
// ...
// ... cluster.fork();
// ...
} else {
// ... worker code
}
For details on the format of the coverage.json object, see here.
istanbul is licensed under the BSD License.
The following third-party libraries are used by this module:
cover
commandlib/vendor/
cover
command, modeled after the run
command in that tool. The coverage methodology used by istanbul is quite different, howeverSince all the good ones are taken. Comes from the loose association of ideas across coverage, carpet-area coverage, the country that makes good carpets and so on...
FAQs
Yet another JS code coverage tool that computes statement, line, function and branch coverage with module loader hooks to transparently add coverage when running tests. Supports all JS coverage use cases including unit tests, server side functional tests
The npm package istanbul receives a total of 953,198 weekly downloads. As such, istanbul popularity was classified as popular.
We found that istanbul demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 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.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.