API Docs for: 0.3.0
Show:

Instrumenter Class

Defined in: lib/instrumenter.js:285
Module: main

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.

Constructor

Instrumenter

(
  • options
)

Defined in lib/instrumenter.js:285

Parameters:

  • options Object

    Optional. Configuration options.

    • [coverageVariable] String optional

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

    • [embedSource] Boolean optional

      whether to embed the source code of every file as an array in the file coverage object for that file. Defaults to false

    • [preserveComments] Boolean optional

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

    • [noCompact] Boolean optional

      emit readable code when set. Defaults to false

    • [noAutoWrap] Boolean optional

      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.

    • [codeGenerationOptions] Object optional

      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

    • [debug] Boolean optional

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

    • [walkDebug] Boolean optional

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

Methods

instrument

(
  • code
  • filename
  • callback
)

Defined in lib/instrumenter.js:522

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:

  • code String

    the code to be instrumented as a String

  • filename String

    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 Function(err, instrumentedCode)
    • the callback function

instrumentASTSync

(
  • program
  • filename
  • originalCode
)

Defined in lib/instrumenter.js:456

synchronous instrumentation method that instruments an AST instead.

Parameters:

  • program String

    the AST to be instrumented

  • filename String

    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.

  • originalCode String

    the original code corresponding to the AST, used for embedding the source into the coverage object

instrumentSync

(
  • code
  • filename
)

Defined in lib/instrumenter.js:380

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

Parameters:

  • code String

    the code to be instrumented as a String

  • filename String

    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

() Object

Defined in lib/instrumenter.js:547

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

() Object

Defined in lib/instrumenter.js:560

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