Skip to content

Using via JavaScript

Kitson Kelly edited this page Sep 28, 2015 · 2 revisions

This document covers how to use remap-istanbul directly via JavaScript.

The main part of remap-istanbul is broken down into three modules, which are covered in detail below. The modules provide access to read in coverage information, remap the coverage information and instruct Istanbul to write out reports including the raw remapped coverage information.

Package Main File

When remap-istanbul is installed via the NodeJS package manager, the package information resolves to the main module which provide a concise interface to remap-istanbul. In order to utilize it, you just need to require in the package.

The main CommonJS module provided combines the modules into a single API which basic usage can look like this:

var remapIstanbul = require('remap-istanbul');
remapIstanbul('coverage-final.json', {
	'json': 'coverage-final.json'
});

This would take the coverage file provided. The function accepts the following arguments:

Argument Type Description
sources Array, string Either an array of strings or a string the represent the JSON Istanbul files to be remapped
reports Object A hash of reports, where the keys are the Istanbul report types and the values are the destination for the report
returns Promise A promise that is resolved when all the reports are written

AMD

The main modules are provided in AMD for usage (although they utilize amdefine to allow transparent loading by a CommonJS loader such as NodeJS's require - see blow).

lib/loadCoverage

The lib/loadCoverage module would be used something like this:

require([ 'remap-istanbul/lib/loadCoverage' ], function (loadCoverage) {
	var coverage = loadCoverage('coverage-final.json');
	/* or if you have multiple files you want to merge */
	coverage = loadCoverage([ 'coverage-ie.json', 'coverage-chrome.json', 'coverage-firefox.json' ]);
});

The argument signature for loadCoverage is:

Argument Type Description
coverage Array/string Either an array of strings or a string representing the file path to the coverage file(s).
options Object? An object that allows providing alternative methods, mainly used for integration with other systems (e.g. Grunt)
returns Object A coverage object that is ready to be remapped

The options argument can take the following optional properties:

Property Type Default Description
readJSON Function JSON.parse(fs.readFileSync) A function that will synchronously read a file and return a POJO based on the JSON data in the file
warn Function console.warn A function that logs warning messages

lib/remap

Usage of the lib/remap module would look something like this:

require([
	'remap-istanbul/lib/loadCoverage',
	'remap-istanbul/lib/remap'
], function (loadCoverage, remap) {
	var coverage = loadCoverage('coverage-final.json');
	var collector = remap(coverage); /* collector now contains the remapped coverage */
});

If the source map no longer points properly at the source files, you can utilize the basePath option to override the path retrieved from the source map:

require([
	'remap-istanbul/lib/loadCoverage',
	'remap-istanbul/lib/remap'
], function (loadCoverage, remap) {
	var coverage = loadCoverage('coverage-final.json');
	var collector = remap(coverage, {
		basePath: 'some/other/path/to/sources'
	});
});

The argument signature for remap is:

Argument Type Description
coverage Array/Object Either an array of coverage objects or a single coverage object.
options Object? An object that allows providing alternative methods, mainly used for integration with other systems (e.g. Grunt)
returns istanbul/lib/collector An Istanbul coverage collector that is ready to be output

The argument of options can contain the following properties:

Property Type Default Description
basePath String Path found in source map A string to use as the base path for the source locations
readFile Function fs.readFileSync A function that will synchronously read a file
readJSON Function JSON.parse(fs.readFileSync) A function that will synchronously read a file and return a POJO based on the JSON data in the file
warn Function console.warn A function that logs warning messages

lib/writeReport

The lib/writeReport module would be used something like this:

require([
	'remap-istanbul/lib/loadCoverage',
	'remap-istanbul/lib/remap',
	'remap-istanbul/lib/writeReport'
], function (remap, writeReport) {
	var collector = remap(loadCoverage('coverage-final.json'));
	writeReport(collector, 'json', 'coverage-final.json').then(function () {
		/* do something else now */
	});
});

The writeReport function can take the following arguments:

Argument Type Description
collector istanbul/lib/collector This is an Istanbul coverage collector (usually returned from remap which is to be written out in a report)
reportType string The type of the report. Valid values are: clover, cobertura, html, json-summary, json, file, lcovonly, teamcity, text-lcov, text-summary or text
dest string, Function The destination file, directory or console logging function that is the destination of the report. Only text-lcov takes the logging function and will default to console.log if no value is passed.
returns Promise A promise that is resolved when the report is written.

CommonJS

If you are not using an AMD loader, that is not a problem for consuming the modules. They also can be loaded in a CommonJS environment:

var loadCoverage = require('remap-istanbul/lib/loadCoverage');
var remap = require('remap-istanbul/lib/remap');
var writeReport = require('remap-istanbul/lib/writeReport');

The APIs will match the usage information above.