Skip to content
Power Assert feature instrumentor based on the ECMAScript AST.
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib feat: embed transpiler name and its version into output Jul 11, 2019
templates
test
.codeclimate.yml chore(codeclimate): analyze product code only May 3, 2019
.gitignore refactor: replace blanket with nyc Jan 11, 2019
.travis.yml chore(travis): drop Node11 Jul 11, 2019
CHANGELOG.md
MIT-LICENSE.txt
README.md
esp.js feat: remove runtime parser dependency by removing escallmatch Feb 15, 2019
gen.js chore: copy new ArgumentRecorder from babel-plugin-espower Feb 16, 2019
index.js feat: prefer Error over custom EspowerError Feb 14, 2019
package-lock.json chore: bump to major pre version Jul 11, 2019
package.json chore: bump to major pre version Jul 11, 2019

README.md

espower

Build Status NPM package Coverage Status Code Climate Code Style License

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

const 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 Error when

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

const 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. 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.

(optional) options.parse

type default value
function N/A

A function to parse pattern string specified by options.patterns. This property is optional and only required to parse a bit complicated custom pattern string like "browser.assert.element(selection, [message])".

const 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,

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

Apply espower then generate modified code to console,

const espower = require('espower');
const esprima = require('esprima');
const escodegen = require('escodegen');
const fs = require('fs');
const { join } = require('path');

const filepath = join(__dirname, 'example_test.js');
const jsAst = esprima.parse(fs.readFileSync(filepath), {tolerant: true, loc: true, tokens: true});
const modifiedAst = espower(jsAst, {path: filepath, sourceRoot: __dirname});

console.log(escodegen.generate(modifiedAst));

Output:

TBD

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.

You can’t perform that action at this time.