espower

Power Assert feature instrumentor based on the ECMAScript AST

espower

Power Assert feature instrumentor based on the ECMAScript AST.

espower is a core module of power-assert family.

espower detects and manipulates assertion expression (JavaScript Code) in the form of ECMAScript AST defined in The ESTree Spec (formerly known as Mozilla SpiderMonkey Parser API), to instrument power-assert feature into returned new AST object. AST in, AST out. Since 0.11.0, espower can transform ES6 AST as well.

Pull-requests, issue reports and patches are always welcomed. See power-assert project for more documentation.

See CHANGELOG

return type
object

espower function manipulates originalAst then returns modifiedAst that is also an AST node object defined in The ESTree Spec. If destructive option is falsy, originalAst will be unchanged. If destructive option is truthy, originalAst will be manipulated directly and returned modifiedAst will be the same instance of originalAst.

espower function throws EspowerError when

  • originalAst is already instrumented
  • originalAst does not contain location information
  • options argument is not valid
typedefault value
objectN/A

originalAst should be an AST node object defined in The ESTree Spec.

typedefault value
object(return value of espower.defaultOptions())

Configuration options. If not passed, default options will be used.

typedefault value
booleanfalse

Modify originalAst destructively or not.

If false, espower clones originalAst deeply, so originalAst will be unchanged. If true, originalAst will be manipulated directly and returned modifiedAst will be the same instance of originalAst.

typedefault value
Array of stringobjects shown below
[
    'assert(value, [message])',
    'assert.ok(value, [message])',
    'assert.equal(actual, expected, [message])',
    'assert.notEqual(actual, expected, [message])',
    'assert.strictEqual(actual, expected, [message])',
    'assert.notStrictEqual(actual, expected, [message])',
    'assert.deepEqual(actual, expected, [message])',
    'assert.notDeepEqual(actual, expected, [message])',
    'assert.deepStrictEqual(actual, expected, [message])',
    'assert.notDeepStrictEqual(actual, expected, [message])'
]

Target patterns for power assert feature instrumentation.

If callee name (for example, assert.equal) matches exactly and number of arguments is satisfied, then the assertion will be modified. Detection is done by escallmatch. Any arguments enclosed in bracket (for example, [message]) means optional parameters. Without bracket means mandatory parameters.

typedefault value
stringN/A

Filepath of originalAst. If passed, espower stores filepath information for reporting. If options.path is absolute and it conflicts with options.sourceRoot or sourceRoot in options.sourceMap, then filepath in power-assert output will be fall back on basename of options.path. This property is optional.

typedefault value
stringN/A

Root filepath for target test files. Only works with options.path or options.sourceMap. If set, filepath in power-assert output will be relative from options.sourceRoot. When both options.sourceRoot and sourceMap's sourceRoot are given and both are absolute filepath, options.sourceRoot has precedence over sourceMap's sourceRoot. This property is optional.

typedefault value
object or stringN/A

A raw (either as a string which can be JSON.parse'd, or an object) SourceMap associated with originalAst. This property is optional. If given, espower uses options.sourceMap to adjust information in the power-assert output.

typedefault value
objectN/A

VisitorKeys for AST traversal. See estraverse.VisitorKeys and babel.types.VISITOR_KEYS.

Returns default options object for espower function. In other words, returns

{
    destructive: false,
    patterns: [
        'assert(value, [message])',
        'assert.ok(value, [message])',
        'assert.equal(actual, expected, [message])',
        'assert.notEqual(actual, expected, [message])',
        'assert.strictEqual(actual, expected, [message])',
        'assert.notStrictEqual(actual, expected, [message])',
        'assert.deepEqual(actual, expected, [message])',
        'assert.notDeepEqual(actual, expected, [message])',
        'assert.deepStrictEqual(actual, expected, [message])',
        'assert.notDeepStrictEqual(actual, expected, [message])'
    ]
}

For given test file example_test.js below,

var assert = require('power-assert');
var truthy = 'true';
var falsy = 'false';
assert(falsy);
assert.equal(truthy, falsy);

Apply espower then generate modified code to console,

var espower = require('espower');
var esprima = require('esprima');
var escodegen = require('escodegen');
var fs = require('fs');
var path = require('path');
 
var filepath = path.join(__dirname, 'example_test.js');
var jsAst = esprima.parse(fs.readFileSync(filepath), {tolerant: true, loc: true, tokens: true});
var modifiedAst = espower(jsAst, {path: filepath});
 
console.log(escodegen.generate(modifiedAst));

Output:

var assert = require('power-assert');
var truthy = 'true';
var falsy = 'false';
assert(assert._expr(assert._capt(falsy, 'arguments/0'), {
    content: 'assert(falsy)',
    filepath: '/path/to/example_test.js',
    line: 4
}));
assert.equal(assert._expr(assert._capt(truthy, 'arguments/0'), {
    content: 'assert.equal(truthy, falsy)',
    filepath: '/path/to/example_test.js',
    line: 5
}), assert._expr(assert._capt(falsy, 'arguments/1'), {
    content: 'assert.equal(truthy, falsy)',
    filepath: '/path/to/example_test.js',
    line: 5
}));

Install

$ npm install --save-dev espower

espower function is exported

<script type="text/javascript" src="./path/to/node_modules/espower/build/espower.js"></script>

Install

$ bower install --save-dev espower

Then load (espower function is exported)

<script type="text/javascript" src="./path/to/bower_components/espower/build/espower.js"></script>

Licensed under the MIT license.