Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Power Assert feature instrumentor based on the Mozilla JavaScript AST
JavaScript

refactor(espower): s/ensure/verify/g

since `ensure` is the word for the post conditions
latest commit 9d3e7d554a
@twada authored
Failed to load latest commit information.
build chore(espower): rebuild web bundle
coverage
lib refactor(espower): s/ensure/verify/g
test chore(espower): improve error message
.gitignore chore(espower): self-build SourceMap web bundle for Browser/AMD testing
.jshintrc chore(gulpfile): integrate jshint into gulp
.travis.yml chore(travis): drop Node 0.11 and add io.js build
CHANGELOG.md docs(CHANGELOG): generate CHANGELOG for 0.10.0
MIT-LICENSE.txt chore(espower): update copyright year
README.md docs(README): coverall svg badge
bower.json chore(package): update devDependencies
esp.js chore(espower): update example script
gulpfile.js chore(package): apply dereserve on build
index.js docs(espower): update interface documentation
package.json

README.md

espower

Build Status NPM package Bower package Dependency Status Coverage Status Code Climate License Built with Gulp

Power Assert feature instrumentor based on the Mozilla JavaScript AST.

DESCRIPTION

espower is a core module of power-assert family.

espower detects and manipulates assertion expression (JavaScript Code) in original AST represented as Mozilla JavaScript AST, to instrument power-assert feature into returned new AST object. Mozilla JavaScript AST in, Mozilla JavaScript AST out.

Please note that espower is a beta version product. Pull-requests, issue reports and patches are always welcomed. See power-assert project for more documentation.

CHANGELOG

See CHANGELOG

API

var modifiedAst = espower(originalAst, [options])

return type
object

espower function manipulates originalAst then returns modifiedAst that is also an AST node object defined in Mozilla JavaScript AST 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 Error when

  • originalAst is already instrumented
  • originalAst does not contain location information
  • options argument is not valid

originalAst

type default value
object N/A

originalAst should be an AST node object defined in Mozilla JavaScript AST spec.

options

type default value
object (return value of espower.defaultOptions())

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

options.destructive

type default value
boolean false

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.

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])'
]

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.

(optional) options.path

type default value
string N/A

Filepath of originalAst. If passed, espower stores filepath information for reporting. 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.

var options = espower.defaultOptions();

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])'
    ]
}

EXAMPLE

For given test file example_test.js below,

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

Apply espower then generate modified code to console,

var espower = require('espower'),
    esprima = require('esprima'),
    escodegen = require('escodegen'),
    fs = require('fs'),
    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'), truthy = 'true', 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

via npm

Install

$ npm install --save-dev espower

via bower

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>

AUTHOR

LICENSE

Licensed under the MIT license.

Something went wrong with that request. Please try again.