antlr/doc/adding-tests.md

3.0 KiB

Adding unit tests

Generating Runtime Tests

Because ANTLR supports multiple target languages, the unit tests are broken into two groups: the unit tests that test the tool itself (in tool-testsuite) and the unit tests that test the parser runtimes (in antlr4/runtime-testsuite). To avoid a lot of cut-and-paste, we generate all runtime tests from a set of templates using runtime-testsuite/src/org/antlr/v4/testgen/TestGenerator.java. The mvn command is simple to use:

$ cd ~/antlr/code/antlr4/runtime-testsuite
$ mvn -Pgen generate-test-sources
...
rootDir = /Users/parrt/antlr/code/antlr4/runtime-testsuite
outputDir = /Users/parrt/antlr/code/antlr4/runtime-testsuite/test
templates = /Users/parrt/antlr/code/antlr4/runtime-testsuite/resources/org/antlr/v4/test/runtime/templates
target = ALL
browsers = false
viz = false

It basically runs the Java program:

$ java org.antlr.v4.testgen.TestGenerator \
	-root ~/antlr/code/antlr4/runtime-testsuite \
	-outdir ~/antlr/code/antlr4/runtime-testsuite/test \
	-templates ~/antlr/code/antlr4/runtime-testsuite/resources/org/antlr/v4/test/runtime/templates

Adding a runtime test

For each target, you will find an Index.stg file with a dictionary of all test groups. E.g., runtime-testsuite/resources/org/antlr/v4/test/runtime/templates/Index.stg looks like:

TestFolders ::= [
        "CompositeLexers": [],
        "CompositeParsers": [],
        "FullContextParsing": [],
        "LeftRecursion": [],
        "LexerErrors": [],
        "LexerExec": [],
        "Listeners": [],
        "ParserErrors": [],
        "ParserExec": [],
        "ParseTrees": [],
        "Performance": [],
        "SemPredEvalLexer": [],
        "SemPredEvalParser": [],
        "Sets": []
]

Then each group has a subdirectory with another index. E.g., Sets/Index.stg looks like:

TestTemplates ::= [
        "SeqDoesNotBecomeSet": [],
        "ParserSet": [],
        "ParserNotSet": [],
        "ParserNotToken": [],
        "ParserNotTokenWithLabel": [],
        "RuleAsSet": [],
        "NotChar": [],
        "OptionalSingleElement": [],
...

For every name mentioned, you will find a .stg file with the actual test. E.g., Sets/StarSet.stg:

TestType() ::= "Parser"

Options ::= [
	"Debug": false
]

Grammar ::= [
	"T": {<grammar("T")>}
]

Input() ::= "abaac"

Rule() ::= "a"

Output() ::= <<
abaac<\n>
>>

Errors() ::= ""

grammar(grammarName) ::= <<
grammar <grammarName>;
a : ('a'|'b')* 'c' {<InputText():writeln()>} ;
>>

Cross-language actions embedded within grammars

To get:

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

Use instead the language-neutral:

<writeln("$set.stop")>

File runtime-testsuite/resources/org/antlr/v4/test/runtime/java/Java.test.stg has templates like:

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

Adding an ANTLR tool unit test

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