escallmatch

ECMAScript CallExpression matcher made from simple API definition

EXAMPLE

Creating CallExpression matcher for API definition 'assert.equal(actual, expected, [message])'.

Then match against path/to/some_test.js.

var escallmatch = require('escallmatch'),
    esprima = require('esprima'),
    estraverse = require('estraverse'),
    fs = require('fs');

var matcher = escallmatch('assert.equal(actual, expected, [message])');

estraverse.traverse(esprima.parse(fs.readFileSync('path/to/some_test.js')), {
    enter: function (currentNode, parentNode) {
        if (matcher.test(currentNode)) {
            // currentNode is a CallExpression that matches to the API definition
        }
        var argMatched = matcher.matchArgument(currentNode, parentNode);
        if (argMatched) {
            if (argMatched.kind === 'mandatory') {
                // mandatory arg (in this case, `actual` or `expected`)
            } else if (argMatched.kind === 'optional') {
                // optional arg (in this case, `message`)
            }
        }
    }
});

where content of path/to/some_test.js is:

var assert = require('assert'),
    anotherAssert = assert,
    equal = assert.equal.bind(assert),
    foo = '2',
    bar = 2;

assert.equal(foo, bar);  // matches
assert.equal(bar, foo);  // matches
assert.equal(foo, bar, 'foo shoule be equal to bar');  // matches (with optional arg)

assert.equal();  // does not match (less args)
assert.equal(foo);  // does not match (less args)
assert.equal(foo, bar, 'hoge', 'fuga');  // does not match (too much args)

assert.notEqual(foo, bar);  // does not match (callee method name differs)
anotherAssert.equal(foo, bar);  // does not match (callee object name differs)
equal(foo, bar);  // does not match (callee does not match)

Please note that escallmatch is an alpha version product. Pull-requests, issue reports and patches are always welcomed. escallmatch is a spin-off product of power-assert project.

API

var matcher = escallmatch(definitionStr)

Create matcher object for a given function/method API definition string.

var matcher = escallmatch('assert.equal(actual, expected, [message])');

Any arguments enclosed in bracket (for example, [message]) means optional parameters. Without bracket means mandatory parameters.

Returns matcher object having two methods, test and matchArgument.

var isMatched = matcher.test(node)

Tests whether node matches the API definition or not.

• Returns true if matched.
• Returns false if not matched.

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

var argMatched = matcher.matchArgument(node, parentNode)

Returns match result object representing whether node (and its parentNode) matches some argument of the API definition or not.

• Returns null if not matched.
• If matched, returns object like {name: 'actual', kind: 'mandatory'}, whose name is an argument name in the API definition and kind is 'mandatory' or 'optional'.

node and parentNode should be AST node objects defined in Mozilla JavaScript AST spec.

INSTALL

via npm

Install

$ npm install --save escallmatch

via bower

Install

$ bower install --save escallmatch

Then load (escallmatch function is exported)

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

AUTHOR

• Takuto Wada

LICENSE

Licensed under the MIT license.