Using via JavaScript

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');