Adding a unit test

Because ANTLR supports multiple target languages, the unit tests are broken into two groups: the unit tests that test the tool itself (in antlr4/tool/test) and the unit tests that test the parser runtimes. To avoid a lot of cut-and-paste, we generate all runtime tests from a set of templates and a Generator.

As each target is in its own repository for organizational purposes, you will have to make sure that you have cloned those repositories as shown in Making tool and runtime jars. Here are the directories that list all of the generated unit tests:

antlr4/tool/test/org/antlr/v4/test/rt/java
antlr4-python2/tool/test/org/antlr/v4/test/rt/py2
antlr4-python3/tool/test/org/antlr/v4/test/rt/py3
antlr4-csharp/tool/test/org/antlr/v4/test/rt/csharp
antlr4-javascript/tool/test/org/antlr/v4/test/rt/js/chrome
antlr4-javascript/tool/test/org/antlr/v4/test/rt/js/explorer
antlr4-javascript/tool/test/org/antlr/v4/test/rt/js/firefox
antlr4-javascript/tool/test/org/antlr/v4/test/rt/js/node
antlr4-javascript/tool/test/org/antlr/v4/test/rt/js/safari

Generating parse-time tests

antlr4/tool/test/org/antlr/v4/test/rt/gen/grammars

Adding an ANTLR tool unit test

Just go into the appropriate Java test class in dir antlr4/tool/test/org/antlr/v4/test/tool an add your unit test.

Adding a Java runtime unit test

Adding unit test for the runtime requires the following steps:

1. Add a StringTemplate template for your test to the appropriate subdirectories of antlr4/tool/test/org/antlr/v4/test/rt/gen/grammars such as file antlr4/tool/test/org/antlr/v4/test/rt/gen/grammars/ParserErrors/SingleSetInsertionConsumption.st:

grammar <grammarName>;
myset: ('b'|'c') ;
a: 'a' myset 'd' {<writeln("$myset.stop"))>} ;

1. Now, notify the generator of this test. Alter file tool/test/org/antlr/v4/test/rt/gen/Generator.java to add a statement to the appropriate buildXXX methods. For example, see the changes to Generator.java in commit antlr/antlr4/353235c. If you add it to directory ParserErrors, make sure to add the appropriate statement with input and output pairs etc... to buildParserErrors().
2. Regenerate all of the unit tests for ALL targets, including the new one.

cd /tmp/antlr4 # jump to root dir of antlr
./bild.py regen_tests

For example, regeneration will add a new test method to TestParserErrors.java for the unit test example discussed in the section.

Cross-language actions embedded within grammars

System.out.println($set.stop);

<writeln("$set.stop")>

antlr4/tool/test/org/antlr/v4/test/rt/java/Java.test.stg and an analogous locations for the other targets.

writeln(s) ::= <<System.out.println(<s>);>>