From b2db71a97ee7263aa45aa34f7c08bf44523ecf4a Mon Sep 17 00:00:00 2001
From: Terence Parr <parrt@cs.usfca.edu>
Date: Wed, 28 Oct 2015 17:06:40 -0700
Subject: [PATCH] got doc in on adding tests

---
 doc/adding-tests.md | 119 ++++++++++++++++++++++++++++++++++++++++++++
 doc/index.md        |   6 ++-
 2 files changed, 124 insertions(+), 1 deletion(-)
 create mode 100644 doc/adding-tests.md

diff --git a/doc/adding-tests.md b/doc/adding-tests.md
new file mode 100644
index 000000000..769383d31
--- /dev/null
+++ b/doc/adding-tests.md
@@ -0,0 +1,119 @@
+# 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](../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:
+
+```bash
+$ 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.
+
+
diff --git a/doc/index.md b/doc/index.md
index 649d30416..79d6ae654 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -55,6 +55,10 @@ This documentation is a reference and summarizes grammar syntax and the key sema
 
 * Integrating ANTLR into Development Systems
 
-* [Build ANTLR itself](building-antlr.md)
+# Building / releasing ANTLR itself
+
+* [Building ANTLR itself](building-antlr.md)
 
 * [Cutting an ANTLR Release](releasing-antlr.md)
+
+* [Adding ANTLR unit tests](adding-tests.md)