Code Instrumentation

JavaScript code instrumentation engine that parses source files and adds coverage tracking statements.

Capabilities

Instrument Method

Main instrumentation method for adding coverage tracking to JavaScript code.

/**
 * Instrument JavaScript code for coverage tracking (alias for instrumentSync)
 * @param config - Instrumentation configuration
 * @param config.inputFile - Source code string to instrument
 * @param config.inputFileName - Filename for the source code (used in reports)
 * @param next - Optional callback function receiving instrumented code
 * @returns Instrumented code string (when used synchronously without callback)
 */
function instrument(config, next);

Instrument Sync Method

Synchronous code instrumentation with optional caching support.

/**
 * Synchronously instrument JavaScript code for coverage tracking
 * @param config - Instrumentation configuration
 * @param config.inputFile - Source code string to instrument  
 * @param config.inputFileName - Filename for the source code
 * @param next - Optional callback function receiving instrumented code
 * @returns Instrumented code string (when used synchronously without callback)
 */
function instrumentSync(config, next);

Usage Examples:

// Synchronous instrumentation
const sourceCode = 'function add(a, b) { return a + b; }';
const instrumented = blanket.instrumentSync({
  inputFile: sourceCode,
  inputFileName: 'math.js'
});

// Asynchronous instrumentation with callback
blanket.instrument({
  inputFile: sourceCode,
  inputFileName: 'math.js'
}, function(instrumentedCode) {
  console.log('Instrumented:', instrumentedCode);
});

Instrumentation Process

Code Parsing

Blanket.js uses Esprima parser and node-falafel to:

1. Parse JavaScript into an Abstract Syntax Tree (AST)
2. Traverse the AST to identify trackable statements
3. Insert coverage tracking code at strategic points
4. Generate instrumented source code

Tracked Statement Types

The following JavaScript statement types are instrumented for coverage:

• ExpressionStatement - Expression statements
• BreakStatement - Break statements in loops/switches
• ContinueStatement - Continue statements in loops
• VariableDeclaration - Variable declarations
• ReturnStatement - Function return statements
• ThrowStatement - Exception throwing
• TryStatement - Try-catch blocks
• FunctionDeclaration - Function declarations
• IfStatement - Conditional statements
• WhileStatement - While loops
• DoWhileStatement - Do-while loops
• ForStatement - For loops
• ForInStatement - For-in loops
• SwitchStatement - Switch statements
• WithStatement - With statements

Branch Tracking

When branchTracking option is enabled, Blanket.js also tracks:

• Conditional branches - Both true and false paths of if statements
• Ternary operators - Both consequent and alternate expressions
• Logical operators - Short-circuit evaluation paths

Instrumentation Output

Instrumented code includes:

1. Coverage variable setup - Initializes coverage tracking object
2. Source line mapping - Maps original source lines to coverage array
3. Tracking statements - Increments counters when code executes
4. Branch tracking (optional) - Records which branches were taken

Example of instrumented code:

// Original code
function add(a, b) {
  return a + b;
}

// Instrumented code (simplified)
if (typeof _$jscoverage === 'undefined') _$jscoverage = {};
if (typeof _$jscoverage['math.js'] === 'undefined') {
  _$jscoverage['math.js'] = [];
  _$jscoverage['math.js'].source = ['function add(a, b) {', '  return a + b;', '}'];
  _$jscoverage['math.js'][1] = 0;
  _$jscoverage['math.js'][2] = 0;
}
function add(a, b) {
  _$jscoverage['math.js'][1]++;
  _$jscoverage['math.js'][2]++;
  return a + b;
}

Caching

Instrument Cache

When instrumentCache option is enabled (browser only), instrumented code is cached in sessionStorage.

Cache behavior:

• Cache key: "blanket_instrument_store-" + filename
• Automatic cache lookup before instrumentation
• Reduces instrumentation overhead for repeated file loads
• Cache persists for browser session

Cache Methods

The caching is handled automatically by instrumentSync, but the process:

1. Check if file exists in cache
2. If cached, return cached instrumented code
3. If not cached, instrument code and store in cache
4. Return instrumented code

Error Handling

Instrumentation Errors

When instrumentation fails:

• Default behavior: Throws error and stops execution
• With ignoreScriptError: true: Logs error and continues with original code
• Debug mode: Outputs detailed error information

Common errors:

• Syntax errors in source code
• Unsupported ECMAScript features (adjust ecmaVersion option)
• Parse errors from malformed JavaScript

Source URL Comments

When sourceURL option is enabled, adds source URL comments to instrumented code:

// Instrumented code...
//@ sourceURL=math.js

This helps debuggers map instrumented code back to original files.

Advanced Features

Custom ECMAScript Version

Control JavaScript parsing with ecmaVersion option:

blanket.options("ecmaVersion", 6); // Parse ES6 features

Strict Mode Detection

Blanket.js automatically detects and preserves strict mode directives:

// Original
'use strict';
function myFunc() { }

// Instrumented (preserves strict mode)
'use strict';
// coverage setup...
function myFunc() { 
  // tracking code...
}

Shebang Handling

Automatically removes shebang lines before parsing:

// Original
#!/usr/bin/env node
console.log('Hello');

// Processed (shebang removed for parsing)
console.log('Hello');