README.md

compareAst

Determine if two strings of JavaScript have equivalent abstract syntax trees. This can be useful to test tools that perform source code transformations.

API

This module exports a function with the following signature:

compareAst(expectedJsSource, actualJsSource [, options])

Built-in Relaxing Options

compareAst supports configuration of the following relaxing options:

• varPattern - a regular expression describing identifier names that, when encountered in the "expected" AST, will be "bound" to the corresponding identifier in the "actual" AST. All further occurences of that identifier must match the original bound value.
• stringPattern - a regular expression describing string values that, when encountered in the "expected" AST, will be "bound" to the corresponding string value in the "actual" AST. All further occurences of that string value must match the original bound value.

See the "Examples" section below for more information on defining these relaxing options.

Custom Comparators

The options object may specify an array of comparators. These functions can be used to further relax the criteria for equivalency. Each will be invoked for every node under comparison. These nodes are generated by esprima; see the esprima documentation for a description of their structure.

compareAst recognizes the following comparator return types:

• Instance of compareAst.Errors - the two nodes are not equivalent
• true - the two nodes are equivalent
• undefined - equivalency cannot be determined by this comparator

Examples

// Identical sources will not trigger an error:
compareAst("var a = 3; a++;", "  var a =3; a++;");

// Because whitespace is insignificant in JavaScript, two sources which
// only differ in their spacing will not trigger an error:
compareAst("var a = 3; a++;", "  var a \t=3;\na++;");

// Code that differs structurally will throw an error
compareAst("var a = 3; a++;", "var a = 3; a--;");

// Allow for "fuzzy" variable names by specifying the `varPattern` option
// as a regular expression:
compareAst(
  "var a = 3, b = 2; a += b;",
  "var __x1__ = 3, __x2__ = 2; __x1__ += __x2__;",
  { varPattern: /__x\d+__/ }
);

// Allow for "fuzzy" string values by specifying the `stringPattern` option
// as a regular expression:
compareAst(
  "var a = 'one', b = 'two', c = 'three';"
  "var a = '__s1__', b = '__s2__', c = '__s3__';",
  { stringPattern: /__s\d+__/ }
);

Tests

Run via:

$ npm test

License

Copyright (c) 2014 Mike Pennisi
Licensed under the MIT license.