astannotate
astannotate is a node.js package that supports querying a JavaScript AST annotated with comments. It is useful for testing libraries that perform JavaScript source introspection because it lets you define test expectations inline in source code instead of having to put them in separate test files.
For example, suppose we want to test a function findDecl
that determines the
definition location of any JavaScript identifier in source code. You can use
astannotate.js to help you test this function by first writing JavaScript code
interspersed with comments as follows:
var /*DECL*/a = 8/*DECL:a*/;var x = a/*REF:a*/ + 8;
And then define AST annotation visitors:
var astannotate = ;var decls = {};var declVisitor = astannotate;var refVisitor = astannotate;
Then we can run this simple test case as follows, and it will throw an error if the output of findDecl doesn't match the expectations we've defined in the source code annotations.
astannotate 'var /*DECL*/a = 8/*DECL:a*/;' + 'var x = a/*REF:a*/ + 8;';
Documentation: astannotate.js on Sourcegraph
Usage
Install the library by running npm install astannotate
or by adding it to
your package.json file.
var astannotate = ;
The two main functions are astannotate.nodeVisitor
and
astannotate.rangeVisitor
, which visit annotated AST nodes and ranges,
respectively. Both functions let you define a comment directive and specify a
test (constraint) function on the matched AST nodes.
Example
var astannotate = ; // Simple directive.astannotate'var a/*#:A*/;';// outputs:// Found node VariableDeclaration with data: A // Use a different directive and a node test ('Identifier') to constrain the matched nodes.astannotate'var a, b/*VAR:foo*/, c/*VAR:bar*/;';// outputs:// Found node Identifier b with data: foo// Found node Identifier c with data: bar // Visit annotated ranges.astannotate'var /*DECL*/a = 7/*DECL:foo*/;';// outputs:// Found node VariableDeclarator with data: foo
These examples are contained in example.js. See the test file for more examples.
Known issues
- When using
rangeVisitor
, the range between the start/end comments must exactly contain a node in order for it to be defined on the callback range'snode
property. If there is extra whitespace or nested comments, such as/*##*/foo/*hello*//*##:*/
, then the node will not be detected.
Running tests
Run npm test
.
Contributors
- Quinn Slack sqs@sourcegraph.com
Inspired by the tests in marijnh/tern.