call-matcher

ECMAScript CallExpression matcher made from function/method signature

EXAMPLE

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

Then match against path/to/some_test.js.

1var CallMatcher = require('call-matcher');
2var esprima = require('esprima');
3var estraverse = require('estraverse');
4var fs = require('fs');
5
6var ast = esprima.parse('assert.equal(actual, expected, [message])');
7var expression = ast.body[0].expression;
8var matcher = new CallMatcher(expression);
9
10estraverse.traverse(esprima.parse(fs.readFileSync('path/to/some_test.js')), {
11    enter: function (currentNode, parentNode) {
12        if (matcher.test(currentNode)) {
13            // currentNode is a CallExpression that matches to the signature
14        }
15        var argMatched = matcher.matchArgument(currentNode, parentNode);
16        if (argMatched) {
17            if (argMatched.kind === 'mandatory') {
18                // mandatory arg (in this case, `actual` or `expected`)
19            } else if (argMatched.kind === 'optional') {
20                // optional arg (in this case, `message`)
21            }
22        }
23    }
24});

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

1var assert = require('assert');
2var anotherAssert = assert;
3var equal = assert.equal.bind(assert);
4var foo = '2';
5var bar = 2;
6
7assert.equal(foo, bar);  // matches
8assert.equal(bar, foo);  // matches
9assert.equal(foo, bar, 'foo shoule be equal to bar');  // matches (with optional arg)
10
11assert.equal();  // does not match (less args)
12assert.equal(foo);  // does not match (less args)
13assert.equal(foo, bar, 'hoge', 'fuga');  // does not match (too much args)
14
15assert.notEqual(foo, bar);  // does not match (callee method name differs)
16anotherAssert.equal(foo, bar);  // does not match (callee object name differs)
17equal(foo, bar);  // does not match (callee does not match)

call-matcher is a spin-off product of power-assert project.

Pull-requests, issue reports and patches are always welcomed.

API

var matcher = new CallMatcher(signatureAst, [options])

Create matcher object for a given expression.

1var ast = esprima.parse('assert.equal(actual, expected, [message])');
2var expression = ast.body[0].expression;
3var matcher = new CallMatcher(expression);

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

Returns matcher object having four methods, test, matchArgument, calleeAst, and argumentSignatures.

options

an object for configuration options. If not passed, default options will be used.

options.visitorKeys

type	default value
object	(return value of estraverse.VisitorKeys)

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

options.astWhiteList

type	default value
object	N/A

Type and property whitelist on creating AST clone. astWhiteList is an object containing NodeType as keys and properties as values.

1{
2    ArrayExpression: ['type', 'elements'],
3    ArrayPattern: ['type', 'elements'],
4    ArrowFunctionExpression: ['type', 'id', 'params', 'body', 'generator', 'expression'],
5    AssignmentExpression: ['type', 'operator', 'left', 'right'],
6    ...

var isMatched = matcher.test(node)

Tests whether node matches the signature or not.

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

node should be an AST node object defined in The ESTree Spec (formerly known as Mozilla SpiderMonkey Parser API).

var argMatched = matcher.matchArgument(node, parentNode)

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

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

node and parentNode should be AST node objects defined in The ESTree Spec (formerly known as Mozilla SpiderMonkey Parser API).

var calleeAst = matcher.calleeAst()

Returns clone of callee AST object based on signature passed to CallMatcher function. Returned tree is one of AST node objects defined in The ESTree Spec (formerly known as Mozilla SpiderMonkey Parser API) (in most cases, Identifier or MemberExpression).

var argSigs = matcher.argumentSignatures()

Returns array of argument signature objects based on signature passed to CallMatcher function. Returns array of objects like [{index: 0, name: 'actual', kind: 'mandatory'}], whose index is an index of matched argument, name is an argument name in the signature and kind is 'mandatory' or 'optional'.

INSTALL

via npm

Install

$ npm install --save call-matcher

CHANGELOG

See CHANGELOG

AUTHOR

• Takuto Wada

CONTRIBUTORS

• Renée Kooi

LICENSE

Licensed under the MIT license.