espower
v2.1.2
Published
Power Assert feature instrumentor based on the ECMAScript AST
Downloads
128,033
Maintainers
Readme
espower
Power Assert feature instrumentor based on the ECMAScript AST.
DESCRIPTION
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.
CHANGELOG
See CHANGELOG
API
var modifiedAst = espower(ast, [options])
| return type |
|:------------|
| object
|
espower
function manipulates ast
then returns modifiedAst
that is also an AST node object defined in The ESTree Spec. ast
will be manipulated directly and returned modifiedAst
will be the same instance of ast
.
espower
function throws EspowerError
when
ast
is already instrumentedast
does not contain location informationoptions
argument is not valid
var visitor = espower.createVisitor(ast, [options])
| return type |
|:------------|
| object
|
espower.createVisitor
generates visitor object to be used with estraverse.replace
. Arguments are the same as espower
function.
ast
| type | default value |
|:---------|:--------------|
| object
| N/A |
ast
should be an AST node object defined in The ESTree Spec.
options
| type | default value |
|:---------|:--------------|
| object
| (return value of espower.defaultOptions()
) |
Configuration options. If not passed, default options will be used.
options.patterns
| type | default value |
|:--------------------|:--------------------|
| Array
of string
| objects 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.
options.ecmaVersion
| type | default value |
|:---------|:--------------|
| number
| 2018
|
The ECMAScript version to parse and analyze. Must be either 3, 5, 6 (2015), 2016, 2017, or 2018.
options.sourceType
| type | default value |
|:---------|:--------------|
| string
| 'module'
|
The source type of the code. Must be either "script"
or "module"
.
(optional) options.path
| type | default value |
|:---------|:--------------|
| string
| N/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.
(optional) options.sourceRoot
| type | default value |
|:---------|:--------------|
| string
| N/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.
(optional) options.sourceMap
| type | default value |
|:--------------------|:--------------|
| object
or string
| N/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.
(optional) options.visitorKeys
| type | default value |
|:---------|:--------------|
| object
| N/A |
VisitorKeys for AST traversal. See estraverse.VisitorKeys and babel.types.VISITOR_KEYS.
var options = espower.defaultOptions();
Returns default options object for espower
function. In other words, returns
{
ecmaVersion: 2018,
sourceType: 'module',
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])'
]
}
EXAMPLE
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, sourceRoot: __dirname});
console.log(escodegen.generate(modifiedAst));
Output:
var _PowerAssertRecorder1 = function () {
function PowerAssertRecorder() {
this.captured = [];
}
PowerAssertRecorder.prototype._capt = function _capt(value, espath) {
this.captured.push({
value: value,
espath: espath
});
return value;
};
PowerAssertRecorder.prototype._expr = function _expr(value, source) {
var capturedValues = this.captured;
this.captured = [];
return {
powerAssertContext: {
value: value,
events: capturedValues
},
source: source
};
};
return PowerAssertRecorder;
}();
var _rec1 = new _PowerAssertRecorder1();
var _rec2 = new _PowerAssertRecorder1();
var _rec3 = new _PowerAssertRecorder1();
var assert = require('power-assert');
var truthy = 'true';
var falsy = 'false';
assert(_rec1._expr(_rec1._capt(falsy, 'arguments/0'), {
content: 'assert(falsy)',
filepath: 'example_test.js',
line: 4
}));
assert.equal(_rec2._expr(_rec2._capt(truthy, 'arguments/0'), {
content: 'assert.equal(truthy, falsy)',
filepath: 'example_test.js',
line: 5
}), _rec3._expr(_rec3._capt(falsy, 'arguments/1'), {
content: 'assert.equal(truthy, falsy)',
filepath: 'example_test.js',
line: 5
}));
INSTALL
via npm
Install
$ npm install --save-dev espower
OUR SUPPORT POLICY
We support Node under maintenance. In other words, we stop supporting old Node version when their maintenance ends.
This means that any other environment is not supported.
NOTE: If espower works in any of the unsupported environments, it is purely coincidental and has no bearing on future compatibility. Use at your own risk.
AUTHOR
CONTRIBUTORS
LICENSE
Licensed under the MIT license.