istanbul-lib-instrument

1.0.0-alpha.2

Exports

Static members

.createInstrumenter(opts)

returns an instrumenter instance with the specified options

createInstrumenter(opts)

returns an instrumenter instance with the specified options

Parameters

Returns

Instrumenter

Instrumenter(options)

mechanism to instrument code for coverage. It uses the esprima and escodegen libraries for JS parsing and code generation respectively.

Works on node as well as the browser.

Usage on nodejs

 var instrumenter = new require('istanbul').Instrumenter(),
     changed = instrumenter.instrumentSync('function meaningOfLife() { return 42; }', 'filename.js');

Usage in a browser

Load esprima.js, escodegen.js and instrumenter.js (this file) using script tags or other means.

Create an instrumenter object as:

 var instrumenter = new Instrumenter(),
     changed = instrumenter.instrumentSync('function meaningOfLife() { return 42; }', 'filename.js');

Aside from demonstration purposes, it is unclear why you would want to instrument code in a browser.

Parameters

  • Object options :

    Optional. Configuration options.
    • [String] options.coverageVariable

      the global variable name to use for tracking coverage. Defaults to __coverage__

    • [Boolean] options.preserveComments

      whether comments should be preserved in the output. Defaults to false

    • [Boolean] options.noCompact

      emit readable code when set. Defaults to false

    • [Boolean] options.esModules

      whether the code to instrument contains uses es imports or exports.

    • [Boolean] options.noAutoWrap

      do not automatically wrap the source in an anonymous function before covering it. By default, code is wrapped in an anonymous function before it is parsed. This is done because some nodejs libraries have return statements outside of a function which is technically invalid Javascript and causes the parser to fail. This construct, however, works correctly in node since module loading is done in the context of an anonymous function. Note that the semantics of the code returned by the instrumenter does not change in any way. The function wrapper is "unwrapped" before the instrumented code is generated.

    • [Object] options.codeGenerationOptions

      an object that is directly passed to the escodegen library as configuration for code generation. The noCompact setting is not honored when this option is specified

    • [Function] options.sourceMapUrlCallback

      a callback function that is called with a source map URL found in the original source.

    • [Boolean] options.debug

      assist in debugging. Currently, the only effect of setting this option is a pretty-print of the coverage variable. Defaults to false

    • [Boolean] options.walkDebug

      assist in debugging of the AST walker used by this class.

Instance members

#instrument(code, filename, callback)

Callback based instrumentation. Note that this still executes synchronously in the same process tick and calls back immediately. It only provides the options for callback style error handling as opposed to a try-catch style and nothing more. Implemented as a wrapper over instrumentSync

instrument(code, filename, callback)

Callback based instrumentation. Note that this still executes synchronously in the same process tick and calls back immediately. It only provides the options for callback style error handling as opposed to a try-catch style and nothing more. Implemented as a wrapper over instrumentSync

Parameters

  • String code :

    the code to be instrumented as a String
  • String filename :

    Optional. The name of the file from which the code was read. A temporary filename is generated when not specified. Not specifying a filename is only useful for unit tests and demonstrations of this library.
  • callback :
#instrumentASTSync(program, filename)

synchronous instrumentation method that instruments an AST instead.

instrumentASTSync(program, filename)

synchronous instrumentation method that instruments an AST instead.

Parameters

  • String program :

    the AST to be instrumented
  • String filename :

    Optional. The name of the file from which the code was read. A temporary filename is generated when not specified. Not specifying a filename is only useful for unit tests and demonstrations of this library.
#instrumentSync(code, filename)

synchronous instrumentation method. Throws when illegal code is passed to it

instrumentSync(code, filename)

synchronous instrumentation method. Throws when illegal code is passed to it

Parameters

  • String code :

    the code to be instrumented as a String
  • String filename :

    Optional. The name of the file from which the code was read. A temporary filename is generated when not specified. Not specifying a filename is only useful for unit tests and demonstrations of this library.
#lastFileCoverage

returns the file coverage object for the code that was instrumented just before calling this method. Note that this represents a "zero-coverage" object which is not even representative of the code being loaded in node or a browser (which would increase the statement counts for mainline code).

lastFileCoverage

returns the file coverage object for the code that was instrumented just before calling this method. Note that this represents a "zero-coverage" object which is not even representative of the code being loaded in node or a browser (which would increase the statement counts for mainline code).

Returns

Object :

a "zero-coverage" file coverage object for the code last instrumented by this instrumenter
#lastSourceMap

returns the source map object for the code that was instrumented just before calling this method.

lastSourceMap

returns the source map object for the code that was instrumented just before calling this method.

Returns

Object :

a source map object for the code last instrumented by this instrumenter

SourceCoverage(pathOrObj)

Extends FileCoverage

SourceCoverage provides mutation methods to manipulate the structure of a file coverage object. Used by the instrumenter to create a full coverage object for a file incrementally.

Parameters

  • pathOrObj :

    {String|Object} - see the argument for FileCoverage