Metaprogramming

(TBD)

(TBD)

Once the ExpandoMetaClass is accessed by calling the metaClass property, methods can added by using either the left shift << or the = operator.

The operators are applied on a non-existent property of metaClass passing an instance of a Closure code block.

The example above shows how a new method can be added to a class by accessing the metaClass property and using the << or = operator to assign a Closure code block. The Closure parameters are interpreted as method parameters. Parameterless methods can be added by using the {→ …​} syntax.

ExpandoMetaClass supports two mechanisms for adding or overriding properties.

Firstly, it has support for declaring a mutable property by simply assigning a value to a property of metaClass:

Another way is to add getter and/or setter methods by using the standard mechanisms for adding instance methods.

In the source code example above the property is dictated by the closure and is a read-only property. It is feasible to add an equivalent setter method but then the property value needs to be stored for later usage. This could be done as shown in the following example.

This is not the only technique however. For example in a servlet container one way might be to store the values in the currently executing request as request attributes (as is done in some cases in Grails).

Constructors can be added by using a special constructor property. Either the << or = operator can be used to assign a Closure code block. The Closure arguments will become the constructor arguments when the code is executed at runtime.

Static methods can be added using the same technique as instance methods with the addition of the static qualifier before the method name.

With ExpandoMetaClass it is possible to use Groovy’s method pointer syntax to borrow methods from other classes.

Since Groovy allows you to use Strings as property names this in turns allows you to dynamically create method and property names at runtime. To create a method with a dynamic name simply use the language feature of reference property names as strings.

The same concept can be applied to static methods and properties.

One application of dynamic method names can be found in the Grails web application framework. The concept of "dynamic codecs" is implemented by using dynamic method names.

The example above shows a codec implementation. Grails comes with various codec implementations each defined in a single class. At runtime there will be multiple codec classes in the application classpath. At application startup the framework adds a encodeXXX and a decodeXXX method to certain meta-classes where XXX is the first part of the codec class name (e.g. encodeHTML). This mechanism is in the following shown in some Groovy pseudo-code:

At runtime it is often useful to know what other methods or properties exist at the time the method is executed. ExpandoMetaClass provides the following methods as of this writing:

Why can’t you just use reflection? Well because Groovy is different, it has the methods that are "real" methods and methods that are available only at runtime. These are sometimes (but not always) represented as MetaMethods. The MetaMethods tell you what methods are available at runtime, thus your code can adapt.

This is of particular use when overriding invokeMethod, getProperty and/or setProperty.

Another feature of ExpandoMetaClass is that it allows to override the methods invokeMethod, getProperty and setProperty, all of them can be found in the groovy.lang.GroovyObject class.

The following example shows how to override invokeMethod:

The first step in the Closure code is to lookup the MetaMethod for the given name and arguments. If the method can be found everything is fine and it is delegated to. If not, a dummy value is returned.

The same logic can be used to override setProperty or getProperty.

The important thing to note here is that instead of a MetaMethod a MetaProperty instance is looked up. If that exists the getProperty method of the MetaProperty is called, passing the delegate.

ExpandoMetaClass even allows for overriding static method with a special invokeMethod syntax.

The logic that is used for overriding the static method is the same as we’ve seen before for overriding instance methods. The only difference is the access to the metaClass.static property and the call to getStaticMethodName for retrieving the static MetaMethod instance.

It is possible to add methods onto interfaces with ExpandoMetaClass. To do this however, it must be enabled globally using the ExpandoMetaClass.enableGlobally() method before application start-up.

The @ToString AST transformation generates a human readable toString representation of the class. For example, annotating the Person class like below will automatically generate the toString method for you:

With this definition, then the following assertion passes, meaning that a toString method taking the field values from the class and printing them out has been generated:

The @ToString annotation accepts several parameters which are summarized in the following table:

The @EqualsAndHashCode AST transformation aims at generating equals and hashCode methods for you. The generated hashcode follows the best practices as described in Effective Java by Josh Bloch:

There are several options available to tweak the behavior of @EqualsAndHashCode:

The @TupleConstructor annotation aims at eliminating boilerplate code by generating constructors for you. A tuple constructor is created for each property, with default values (using the Java default values). For example, the following code will generate 3 constructors:

The first constructor is a no-arg constructor which allows the traditional map-style construction. It is worth noting that if the first property (or field) has type LinkedHashMap or if there is a single Map, AbstractMap or HashMap property (or field), then the map-style mapping is not available.

The other constructors are generated by taking the properties in the order they are defined. Groovy will generate as many constructors as they are properties (or fields, depending on the options).

The @TupleConstructor AST transformation accepts several configuration options:

The @Canonical AST transformation combines the effects of the @ToString, @EqualsAndHashCode and @TupleConstructor annotations:

A similar immutable class can be generated using the @Immutable AST transformation instead. The @Canonical AST transformation supports several configuration options:

The @InheritConstructor AST transformation aims at generating constructors matching super constructors for you. This is in particular useful when overriding exception classes:

The @InheritConstructor AST transformation supports the following configuration options:

The @Category AST transformation simplifies the creation of Groovy categories. Historically, a Groovy category was written like this:

The @Category transformation lets you write the same using an instance-style class, rather than a static class style. This removes the need for having the first argument of each method being the receiver. The category can be written like this:

Note that the mixed in class can be referenced using this instead. It’s also worth noting that using instance fields in a category class is inherently unsafe: categories are not stateful (like traits).

The @IndexedProperty annotation aims at generating indexed getters/setters for properties of list/array types. This is in particular useful if you want to use a Groovy class from Java. While Groovy supports GPath to access properties, this is not available from Java. The @IndexedProperty annotation will generate indexed properties of the following form:

The @Lazy AST transformation implements lazy initialization of fields. For example, the following code:

will produce the following code:

The default value which is used to initialize the field is the default constructor of the declaration type. It is possible to define a default value by using a closure on the right hand side of the property assignment, as in the following example:

In that case, the generated code looks like the following:

If the field is declared volatile then initialization will be synchronized using the double-checked locking pattern.

Using the soft=true parameter, the helper field will use a SoftReference instead, providing a simple way to implement caching. In that case, if the garbage collector decides to collect the reference, initialization will occur the next time the field is accessed.

The @Newify AST transformation is used to bring alternative syntaxes to construct objects:

The Ruby version can be disabled by setting the auto flag to false.

The @Sortable AST transformation is used to help write classes that are Comparable and easily sorted by numerous properties. It is easy to use as shown in the following example where we annotate the Person class:

The generated class has the following properties:

The generated compareTo method will look like this:

As an example of the generated comparators, the comparatorByFirst comparator will have a compare method that looks like this:

The Person class can be used wherever a Comparable is expected and the generated comparators wherever a Comparator is expected as shown by these examples:

Normally, all properties are used in the generated compareTo method in the priority order in which they are defined. You can include or exclude certain properties from the generated compareTo method by giving a list of property names in the includes or excludes annotation attributes. If using includes, the order of the property names given will determine the priority of properties when comparing. To illustrate, consider the following Person class definition:

It will have two comparator methods comparatorByFirst and comparatorByBorn and the generated compareTo method will look like this:

This Person class can be used as follows:

The @Builder AST transformation is used to help write classes that can be created using fluent api calls. The transform supports multiple building strategies to cover a range of cases and there are a number of configuration options to customize the building process. If you’re an AST hacker, you can also define your own strategy class. The following table lists the available strategies that are bundled with Groovy and the configuration options each strategy supports.

To use the SimpleStrategy, annotate your Groovy class using the @Builder annotation, and specify the strategy as shown in this example:

Then, just call the setters in a chained fashion as shown here:

For each property, a generated setter will be created which looks like this:

You can specify a prefix as shown in this example:

And calling the chained setters would look like this:

You can use the SimpleStrategy in conjunction with @Canonical. If your @Builder annotation doesn’t have explicit includes or excludes annotation attributes but your @Canonical annotation does, the ones from @Canonical will be re-used for @Builder.

The annotation attributes builderClassName, buildMethodName, builderMethodName and forClass are not supported for this strategy.

To use the ExternalStrategy, create and annotate a Groovy builder class using the @Builder annotation, specify the class the builder is for using forClass and indicate use of the ExternalStrategy. Suppose you have the following class you would like a builder for:

you explicitly create and use your builder class as follows:

Note that the (normally empty) builder class you provide will be filled in with appropriate setters and a build method. The generated build method will look something like:

The class you are creating the builder for can be any Java or Groovy class following the normal JavaBean conventions, e.g. a no-arg constructor and setters for the properties. Here is an example using a Java class:

The generated builder can be customised using the prefix, includes, excludes and buildMethodName annotation attributes. Here is an example illustrating various customisations:

The builderMethodName and builderClassName annotation attributes for @Builder aren’t applicable for this strategy.

You can use the ExternalStrategy in conjunction with @Canonical. If your @Builder annotation doesn’t have explicit includes or excludes annotation attributes but the @Canonical annotation of the class you are creating the builder for does, the ones from @Canonical will be re-used for @Builder.

To use the DefaultStrategy, annotate your Groovy class using the @Builder annotation as shown in this example:

If you want, you can customize various aspects of the building process using the builderClassName, buildMethodName, builderMethodName, prefix, includes and excludes annotation attributes, some of which are used in the example here:

This strategy also supports annotating static methods and constructors. In this case, the static method or constructor parameters become the properties to use for building purposes and in the case of static methods, the return type of the method becomes the target class being built. If you have more than one @Builder annotation used within a class (at either the class, method or constructor positions) then it is up to you to ensure that the generated helper classes and factory methods have unique names (i.e. no more than one can use the default name values). Here is an example highlighting method and constructor usage (and also illustrating the renaming required for unique names).

The forClass annotation attribute is not supported for this strategy.

To use the InitializerStrategy, annotate your Groovy class using the @Builder annotation, and specify the strategy as shown in this example:

Your class will be locked down to have a single public constructor taking a "fully set" initializer. It will also have a factory method to create the initializer. These are used as follows:

Any attempt to use the initializer which doesn’t involve setting all the properties (though order is not important) will result in a compilation error. If you don’t need this level of strictness, you don’t need to use @CompileStatic.

You can use the InitializerStrategy in conjunction with @Canonical and @Immutable. If your @Builder annotation doesn’t have explicit includes or excludes annotation attributes but your @Canonical annotation does, the ones from @Canonical will be re-used for @Builder. Here is an example using @Builder with @Immutable:

This strategy also supports annotating static methods and constructors. In this case, the static method or constructor parameters become the properties to use for building purposes and in the case of static methods, the return type of the method becomes the target class being built. If you have more than one @Builder annotation used within a class (at either the class, method or constructor positions) then it is up to you to ensure that the generated helper classes and factory methods have unique names (i.e. no more than one can use the default name values). For an example of method and constructor usage but using the DefaultStrategy strategy, consult that strategy’s documentation.

The annotation attribute forClass is not supported for this strategy.

The @Delegate AST transformation aims at implementing the delegation design pattern. In the following class:

The when field is annotated with @Delegate, meaning that the Event class will delegate calls to Date methods to the when field. In this case, the generated code looks like this:

Then you can call the before method, for example, directly on the Event class:

The behavior of the @Delegate AST transformation can be changed using the following parameters:

The @Immutable AST transformation simplifies the creation of immutable classes, that is to say classes for which members are deemed immutable. For that, all you have to do is annotating the class like in the following example:

Immutable classes generated with @Immutable are automatically made final. For a class to be immutable, you have to make sure that properties are of an immutable type (primitive or boxed types), of a known-immutable type or another class annotated with @Immutable. The effect of applying @Immutable to a class are pretty similar to those of applying the @Canonical AST transformation, but with an immutable class: automatic generation of toString, equals and hashCode methods for example, but trying to modify a property would throw a ReadOnlyPropertyException in that case.

Since @Immutable relies on a predefined list of known immutable classes (like java.net.URI or java.lang.String and fails if you use a type which is not in that list, you are allowed to instruct the transformation that some types are deemed immutable thanks to the following parameters:

The @Memoized AST transformations simplifies the implementation of caching by allowing the result of method calls to be cached just by annotating the method with @Memoized. Let’s imagine the following method:

This emulates a long computation, based on the actual parameters of the method. Without @Memoized, each method call would take several seconds plus it would return a random result:

Adding @Memoized changes the semantics of the method by adding caching, based on the parameters:

The size of the cache can be configured using two optional parameters:

By default, the size of the cache is unlimited and no cache result is protected from garbage collection. Setting a protectedCacheSize>0 would create an unlimited cache with some results protected. Setting maxCacheSize>0 would create a limited cache but without any protection from garbage protection. Setting both would create a limited, protected cache.

The @Singleton annotation can be used to implement the singleton design pattern on a class. The singleton instance is defined eagerly by default, using class initialization, or lazily, in which case the field is initialized using double checked locking.

By default, the singleton is created eagerly when the class is initialized and available through the instance property. It is possible to change the name of the singleton using the property parameter:

And it is also possible to make initialization lazy using the lazy parameter:

In this example, we also set the strict parameter to false, which allows us to define our own constructor.

Deprecated. Consider using traits instead.

The first logging AST transformation available is the @Log annotation which relies on the JDK logging framework. Writing:

is equivalent to writing:

Groovy supports the Apache Commons Logging framework using to the @Commons annotation. Writing:

is equivalent to writing:

Groovy supports the Apache Log4j 1.x framework using to the @Log4j annotation. Writing:

is equivalent to writing:

Groovy supports the Apache Log4j 2.x framework using to the @Log4j2 annotation. Writing:

is equivalent to writing:

Groovy supports the Simple Logging Facade for Java (SLF4J) framework using to the @Slf4j annotation. Writing:

is equivalent to writing:

The @Synchronized AST transformations works in a similar way to the synchronized keyword but locks on different objects for safer concurrency. It can be applied on any method or static method:

Writing this is equivalent to creating a lock object and wrapping the whole method into a synchronized block:

By default, @Synchronized creates a field named $lock (or $LOCK for a static method) but you can make it use any field you want by specifying the value attribute, like in the following example:

The @WithReadLock AST transformation works in conjunction with the @WithWriteLock transformation to provide read/write synchronization using the ReentrantReadWriteLock facility that the JDK provides. The annotation can be added to a method or a static method. It will transparently create a $reentrantLock final field (or $REENTRANTLOCK for a static method) and proper synchronization code will be added. For example, the following code:

is equivalent to this:

Both @WithReadLock and @WithWriteLock support specifying an alternative lock object. In that case, the referenced field must be declared by the user, like in the following alternative:

For details

The @AutoClone annotation is aimed at implementing the @java.lang.Cloneable interface using various strategies, thanks to the style parameter:

Each of those strategies have pros and cons which are discussed in the Javadoc for groovy.transform.AutoClone and groovy.transform.AutoCloneStyle .

For example, the following example:

is equivalent to this:

Note that the String properties aren’t explicitly handled because Strings are immutable and the clone() method from Object will copy the String references. The same would apply to primitive fields and most of the concrete subclasses of java.lang.Number.

In addition to cloning styles, @AutoClone supports multiple options:

The @AutoExternalize AST transformation will assist in the creation of java.io.Externalizable classes. It will automatically add the interface to the class and generate the writeExternal and readExternal methods. For example, this code:

will be converted into:

The @AutoExternalize annotation supports two parameters which will let you slightly customize its behavior:

One complicated situation in the JVM world is when a thread can’t be stopped. The Thread#stop method exists but is deprecated (and isn’t reliable) so your only chance relies in Thread#interrupt. Calling the latter will set the interrupt flag on the thread, but it will not stop the execution of the thread. This is problematic because it’s the responsibility of the code executing in the thread to check the interrupt flag and properly exit. This makes sense when you, as a developer, know that the code you are executing is meant to be run in an independent thread, but in general, you don’t know it. It’s even worse with user scripts, who might not even know what a thread is (think of DSLs).

@ThreadInterrupt simplifies this by adding thread interruption checks at critical places in the code:

Let’s imagine the following user script:

This is an obvious infinite loop. If this code executes in its own thread, interrupting wouldn’t help: if you join on the thread, then the calling code would be able to continue, but the thread would still be alive, running in background without any ability for you to stop it, slowly causing thread starvation.

One possibility to work around this is to set up your shell this way:

The shell is then configured to automatically apply the @ThreadInterrupt AST transformations on all scripts. This allows you to execute user scripts this way:

The transformation automatically modified user code like this:

The check which is introduced inside the loop guarantees that if the interrupt flag is set on the current thread, an exception will be thrown, interrupting the execution of the thread.

@ThreadInterrupt supports multiple options that will let you further customize the behavior of the transformation:

The @TimedInterrupt AST transformation tries to solve a slightly different problem from @groovy.transform.ThreadInterrupt: instead of checking the interrupt flag of the thread, it will automatically throw an exception if the thread has been running for too long.

Imagine the following user code:

The implementation of the famous Fibonacci number computation here is far from optimized. If it is called with a high n value, it can take minutes to answer. With @TimedInterrupt, you can choose how long a script is allowed to run. The following setup code will allow the user script to run for 1 second at max:

This code is equivalent to annotating a class with @TimedInterrupt like this:

@TimedInterrupt supports multiple options that will let you further customize the behavior of the transformation:

The last annotation for safer scripting is the base annotation when you want to interrupt a script using a custom strategy. In particular, this is the annotation of choice if you want to use resource management (limit the number of calls to an API, …​). In the following example, user code is using an infinite loop, but @ConditionalInterrupt will allow us to check a quota manager and interrupt automatically the script:

The quota checking is very basic here, but it can be any code:

We can make sure @ConditionalInterrupt works properly using this test code:

Of course, in practice, it is unlikely that @ConditionalInterrupt will be itself added by hand on user code. It can be injected in a similar manner as the example shown in the ThreadInterrupt section, using the org.codehaus.groovy.control.customizers.ASTTransformationCustomizer :

@ConditionalInterrupt supports multiple options that will let you further customize the behavior of the transformation:

The @Field annotation only makes sense in the context of a script and aims at solving a common scoping error with scripts. The following example will for example fail at runtime:

The error that is thrown may be difficult to interpret: groovy.lang.MissingPropertyException: No such property: x. The reason is that scripts are compiled to classes and the script body is itself compiled as a single run() method. Methods which are defined in the scripts are independent, so the code above is equivalent to this:

So def x is effectively interpreted as a local variable, outside of the scope of the line method. The @Field AST transformation aims at fixing this by changing the scope of the variable to a field of the enclosing script:

The resulting, equivalent, code is now:

By default, Groovy visibility rules imply that if you create a field without specifying a modifier, then the field is interpreted as a property:

Should you want to create a package private field instead of a property (private field+getter/setter), then annotate your field with @PackageScope:

The @PackageScope annotation can also be used for classes, methods and constructors. In addition, by specifying a list of PackageScopeTarget values as the annotation attribute at the class level, all members within that class that don’t have an explicit modifier and match the provided PackageScopeTarget will remain package protected. For example to apply to fields within a class use the following annotation:

The @PackageScope annotation is seldom used as part of normal Groovy conventions but is sometimes useful for factory methods that should be visible internally within a package or for methods or constructors provided for testing purposes, or when integrating with third-party libraries which require such visibility conventions.

@AnnotationCollector allows the creation of meta-annotation, which are described in a dedicated section.

@TypeChecked activates compile-time type checking on your Groovy code. See section on type checking for details.

@CompileStatic activates static compilation on your Groovy code. See section on type checking for details.

@CompileDynamic disables static compilation on parts of your Groovy code. See section on type checking for details.

@DelegatesTo is not, technically speaking, an AST transformation. It is aimed at documenting code and helping the compiler in case you are using type checking or static compilation. The annotation is described thoroughly in the DSL section of this guide.

@Bindable is an AST transformation that transforms a regular property into a bound property (according to the JavaBeans specification). The @Bindable annotation can be placed on a property or a class. To convert all properties of a class into bound properties, on can annotate the class like in this example:

This is equivalent to writing this:

@Bindable therefore removes a lot of boilerplate from your class, dramatically increasing readability. If the annotation is put on a single property, only that property is bound:

The @ListenerList AST transformation generates code for adding, removing and getting the list of listeners to a class, just by annotating a collection property:

The transform will generate the appropriate add/remove methods based on the generic type of the list. In addition, it will also create fireXXX methods based on the public methods declared on the class:

@Bindable supports multiple options that will let you further customize the behavior of the transformation:

The @Vetoable annotation works in a similar manner to @Bindable but generates constrained property according to the JavaBeans specification, instead of bound properties. The annotation can be placed on a class, meaning that all properties will be converted to constrained properties, or on a single property. For example, annotating this class with @Vetoable:

is equivalent to writing this:

If the annotation is put on a single property, only that property is made vetoable:

@NotYetImplemented is used to invert the result of a JUnit 3/4 test case. It is in particular useful if a feature is not yet implemented but the test is. In that case, it is expected that the test fails. Marking it with @NotYetImplemented will inverse the result of the test, like in this example:

Another advantage of using this technique is that you can write test cases for bugs before knowing how to fix them. If some time in the future, a modification in the code fixes a bug by side effect, you’ll be notified because a test which was expected to fail passed.

@ASTTest is a special AST transformation meant to help debugging other AST transformations or the Groovy compiler itself. It will let the developer "explore" the AST during compilation and perform assertions on the AST rather than on the result of compilation. This means that this AST transformations gives access to the AST before the bytecode is produced. @ASTTest can be placed on any annotable node and requires two parameters:

value is a closure expression which has access to a special variable node corresponding to the annotated node, and a helper lookup method which will be discussed here. For example, you can annotate a class node like this:

One interesting feature of @ASTTest is that if an assertion fails, then compilation will fail. Now imagine that we want to check the behavior of an AST transformation at compile time. We will take @PackageScope here, and we will want to verify that a property annotated with @PackageScope becomes a package private field. For this, we have to know at which phase the transform runs, which can be found in org.codehaus.groovy.transform.PackageScopeASTTransformation : semantic analysis. Then a test can be written like this:

The @ASTTest annotation can only be placed wherever the grammar allows it. Sometimes, you would like to test the contents of an AST node which is not annotable. In this case, @ASTTest provides a convenient lookup method which will search the AST for nodes which are labelled with a special token:

Imagine, for example, that you want to test the declared type of a for loop variable. Then you can do it like this:

@ASTTest also exposes those variables inside the test closure:

The latter is interesting if you don’t specify the phase attribute. In that case, the closure will be executed after each compile phase after (and including) SEMANTIC_ANALYSIS. The context of the transformation is kept after each phase, giving you a chance to check what changed between two phases.

As an example, here is how you could dump the list of AST transformations registered on a class node:

And here is how you can memorize variables for testing between two phases:

Grape is a dependency management engine embedded into Groovy, relying on several annotations which are described thoroughly in this section of the guide.

While you have seen that you can directly implement the ASTTransformation interface, in almost all cases you will not do this but extend the org.codehaus.groovy.transform.AbstractASTTransformation class. This class provides several utility methods that make AST transformations easier to write. Almost all AST transformations included in Groovy extend this class.

It is a common use case to be able to transform an expression into another. Groovy provides a class which makes it very easy to do this: org.codehaus.groovy.ast.ClassCodeExpressionTransformer

To illustrate this, let’s create a @Shout transformation that will transform all String constants in method call arguments into their uppercase version. For example:

should print:

Then the code for the transformation can use the ClassCodeExpressionTransformer to make this easier:

Classes of the Abstract Syntax Tree belong to the org.codehaus.groovy.ast package. It is recommended to the reader to use the Groovy Console, in particular the AST browser tool, to gain knowledge about those classes. However, a good resource for learning is the AST Builder test suite.

This section is about good practices with regards to testing AST transformations. Previous sections highlighted the fact that to be able to execute an AST transformation, it has to be precompiled. It might sound obvious but a lot of people get caught on this, trying to use an AST transformation in the same source tree as where it is defined.

The first tip for testing AST transformation is therefore to separate test sources from the sources of the transform. Again, this is nothing but best practices, but you must make sure that your build too does actually compile them separately. This is the case by default with both Apache Maven and Gradle.

It is very handy to be able to put a breakpoint in an AST transformation, so that you can debug your code in the IDE. However, you might be surprised to see that your IDE doesn’t stop on the breakpoint. The reason is actually simple: if your IDE uses the Groovy compiler to compile the unit tests for your AST transformation, then the compilation is triggered from the IDE, but the process which will compile the files doesn’t have debugging options. It’s only when the test case is executed that the debugging options are set on the virtual machine. In short: it is too late, the class has been compiled already, and your transformation is already applied.

A very easy workaround is to use the GroovyTestCase class which provides an assertScript method. This means that instead of writing this in a test case:

You should write:

The difference is that when you use assertScript, the code in the assertScript block is compiled when the unit test is executed. That is to say that this time, the Subject class will be compiled with debugging active, and the breakpoint is going to be hit.

Last but not least, testing an AST transformation is also about testing the state of the AST during compilation. Groovy provides a tool named @ASTTest for this: it is an annotation that will let you add assertions on an abstract syntax tree. Please check the documentation for ASTTest for more details.