istanbul-api 1.0.0-alpha.4 | Documentation

### istanbul-api

`1.0.0-alpha.4`

## Exports

## Config

methods to load the configuration object.

## Usage

     var config = require('istanbul').config,
         configObj = config.loadFile();

     console.log(configObj.reporting.reports());

## add(fmt)

adds a report to be generated. Must be one of the entries returned by `Report.getReportList()`

#### Parameters

- `String` fmt :

  the format of the report to generate

## addAll(fmts)

adds an array of report formats to be generated

#### Parameters

- `Array` fmts :

  an array of report formats

## write(coverageMap, opts)

writes all reports added

#### Parameters

- coverageMap :
- opts :

## addMethods

returns a list of reports that should be generated at the end of a run. Used by the `cover` and `report` commands.

#### Returns

``Array`` :

an array of reports that should be produced

## addMethods

returns if comments should be preserved in the generated JS. Used by the `cover` and `instrument` commands.

#### Returns

``Boolean`` :

true if comments should be preserved in the generated JS

## addMethods

Sets the baseline coverage filename. Used by the `instrument` command.

#### Returns

``String`` :

the name of the baseline coverage file.

## addMethods

returns if comments the JS to instrument contains es6 Module syntax.

#### Returns

``Boolean`` :

true if code contains es6 import/export statements.

## addMethods

returns if the coverage filename should include the PID. Used by the `instrument` command.

#### Returns

``Boolean`` :

true to include pid in coverage filename.

## addMethods

returns if the output should be compact JS. Used by the `instrument` command.

#### Returns

``Boolean`` :

true if the output should be compact

## addMethods

returns if non-JS files should be copied during instrumentation. Used by the `instrument` command.

#### Returns

``Boolean`` :

true if non-JS files should be copied

## addMethods

returns the kind of information to be printed on the console. May be one of `summary`, `detail`, `both` or `none`. Used by the `cover` command.

#### Returns

``String`` :

the kind of information to print to the console at the end of the `cover` command execution.

## addMethods

returns if a zero-coverage baseline file should be written as part of instrumentation. This allows reporting to display numbers for files that have no tests. Used by the `instrument` command.

#### Returns

``Boolean`` :

true if a baseline coverage file should be written.

## addMethods

returns the directory under which reports should be generated. Used by the `cover` and `report` commands.

#### Returns

``String`` :

the directory under which reports should be generated.

## addMethods

returns an object that has keys that are report format names and values that are objects containing detailed configuration for each format. Running `istanbul help config` will give you all the keys per report format that can be overridden. Used by the `cover` and `report` commands.

#### Returns

``Object`` :

detailed report configuration per report format.

## addMethods

the coverage variable name to use. Used by the `instrument` command.

#### Returns

``String`` :

the coverage variable name to use

## addMethods

returns if default excludes should be turned on. Used by the `cover` command.

#### Returns

``Boolean`` :

true if default excludes should be turned on

## addMethods

returns if `vm.runInThisContext` needs to be hooked, in addition to the standard `require` hooks added by istanbul. This should be true for code that uses RequireJS for example. Used by the `cover` command.

#### Returns

``Boolean`` :

true if `vm.runInThisContext` needs to be hooked for coverage

## addMethods

returns a path to JS file or a dependent module that should be used for post-processing files after they have been required. See the `yui-istanbul` module for an example of a post-require hook. This particular hook modifies the yui loader when that file is required to add istanbul interceptors. Use by the `cover` command

#### Returns

``String`` :

a path to a JS file or the name of a node module that needs to be used as a `require` post-processor

## addMethods

returns if istanbul needs to add a SIGINT (control-c, usually) handler to save coverage information. Useful for getting code coverage out of processes that run forever and need a SIGINT to terminate.

#### Returns

``Boolean`` :

true if SIGINT needs to be hooked to write coverage information

## config(config)

Object that returns hook options. Note that istanbul does not provide an option to hook `require`. This is always done by the `cover` command.

#### Parameters

- config :

  the hooks part of the config object

## config(config)

Object that returns instrumentation options

#### Parameters

- config :

  the instrumentation part of the config object

## config(obj, overrides)

represents the istanbul configuration and provides sub-objects that can return instrumentation, reporting and hook options respectively.

## Usage

     var configObj = require('istanbul').config.loadFile();

     console.log(configObj.reporting.reports());

#### Parameters

- `Object` obj :

  the base object to use as the configuration

- `Object` overrides :

  optional - override attributes that are merged into the base config

## config(config)

Object that returns reporting options

#### Parameters

- config :

  the reporting part of the config object

## defaultConfig

returns the default configuration object. Note that this is a plain object and not a `Configuration` instance.

#### Returns

``Object`` :

an object that represents the default config

## loadFile(file, overrides)

loads the specified configuration file with optional overrides. Throws when a file is specified and it is not found.

#### Parameters

- `String` file :

  the file to load. If falsy, the default config file, if present, is loaded. If not a default config is used.

- `Object` overrides :

  an object with override keys that are merged into the config object loaded

#### Returns

``Configuration`` :

the config object with overrides applied

## loadObject(obj, overrides)

loads the specified configuration object with optional overrides.

#### Parameters

- `Object` obj :

  the object to use as the base configuration.

- `Object` overrides :

  an object with override keys that are merged into the config object

#### Returns

``Configuration`` :

the config object with overrides applied

## excludes(excludeTests)

returns an array of fileset patterns that should be excluded for instrumentation. Used by the `instrument` and `cover` commands.

#### Parameters

- excludeTests :

#### Returns

``Array`` :

an array of fileset patterns that should be excluded for instrumentation.

## root

returns the root directory used by istanbul which is typically the root of the source tree. Used by the `cover` and `report` commands.

#### Returns

``String`` :

the root directory used by istanbul.

## loadFile(file, overrides)

hook options

#### Parameters

- file :
- overrides :

## loadFile(file, overrides)

true if verbose logging is required

#### Parameters

- file :
- overrides :

## loadFile(file, overrides)

instrumentation options

#### Parameters

- file :
- overrides :

## loadFile(file, overrides)

reporting options

#### Parameters

- file :
- overrides :

## matcherFor(options)

asynchronously returns a function that can match filesystem paths. The function returned in the callback may be passed directly as a `matcher` to the functions in the `hook` module.

When no options are passed, the match function is one that matches all JS files under the current working directory except ones under `node_modules`

Match patterns are `ant`-style patterns processed using the `fileset` library. Examples not provided due to limitations in putting asterisks inside jsdoc comments. Please refer to tests under `test/other/test-matcher.js` for examples.

#### Parameters

- `Object` options :

  Optional. Lookup options.

- `[`String`]` options.root

  the root of the filesystem tree under which to match files. Defaults to `process.cwd()`

- `[`Array`]` options.includes

  an array of include patterns to match. Defaults to all JS files under the root.

- `[`Array`]` options.excludes

  and array of exclude patterns. File paths matching these patterns will be excluded by the returned matcher. Defaults to files under `node_modules` found anywhere under root.

## watermarks

returns the low and high watermarks to be used to designate whether coverage is `low`, `medium` or `high`. Statements, functions, branches and lines can have independent watermarks. These are respected by all reports that color for low, medium and high coverage. See the default configuration for exact syntax using `istanbul help config`. Used by the `cover` and `report` commands.

#### Returns

``Object`` :

an object containing low and high watermarks for statements, branches, functions and lines.