From d866407d3214cfac86f83b83fc64b72e7314bf0e Mon Sep 17 00:00:00 2001
From: rschoene <rene.schoene@tu-dresden.de>
Date: Fri, 10 Jan 2020 19:11:35 +0100
Subject: [PATCH] Begin with guide for contributing, covering creation of test
cases.
---
CONTRIBUTING.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
create mode 100644 CONTRIBUTING.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..1400748
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,69 @@
+# Creating normal test cases
+
+A test usually defines a grammar, optionally some attributes and a Test class.
+It then normally runs RelAST followed by JastAdd.
+To create a new test, the following four ingredients are needed:
+
+## Specification
+
+Here, the grammar and attributes to be compiled are contained.
+Use `src/test/jastadd/$YourTestName` as directory to put your files into.
+All generated `*.ast`, `*.jrag` and `ResolverStubs.jrag` are already ignored by the main `.gitignore`.
+
+## Generated files
+
+Usually, all files are generated into a separate directory in `src/test/java-gen/`.
+This location can be [configured](#build-configuration).
+
+## Build configuration
+
+Currently, test setup is configured within the `build.gradle` using a specialized Gradle task `RelastTest`.
+An example configuration might look like:
+
+```groovy
+task compileMultipleTest(type: RelastTest) {
+ relastFiles 'src/test/jastadd/multiple/Part1.relast',
+ 'src/test/jastadd/multiple/Part2.relast',
+ 'src/test/jastadd/multiple/Part3.relast'
+ grammarName = 'src/test/jastadd/multiple/Multiple'
+ useJastAddNames = true
+ packageName = 'multiple.ast'
+ moreInputFiles 'src/test/jastadd/Utils.jadd'
+}
+```
+
+The following options are supported:
+
+| Name | Description | Required | Default |
+|------|-------------|----------|---------|
+| `relastFiles` | Input grammar(s). Either one or multiple files separated by comma. | Yes | _none_ |
+| `grammarName` | Directory and file prefix for the generated grammar and jrag created by RelAST. | Yes | _none_ |
+| `useJastAddNames` | Set to `true` to use accessor names for relations matching JastAdd naming convention. | No | `false` |
+| `packageName` | Name of the package for the Java files generated by JastAdd. | Yes (not enforced) | The empty package |
+| `moreInputFiles` | Additional files as input for JastAdd. | No | No additional files |
+| `resolverHelper` | Set to `true` to generate means for lazy resolving. | No | `false` |
+| `jastAddList` | Alternative name for `List` nodes. Will be passed to both RelAST and JastAdd. | No | `List` |
+| `serializer` | Name of supported serializer. One of {`jackson`, `jackson-json-pointer`, `jackson-manual-references`}. | No | No serializer |
+
+## Test files
+
+The actual test source, usually located in `src/test/java/` in the package `org.jastadd.relast.tests`.
+Pay attention to import the correct nonterminal classes by using the same package as [configured](#build-configuration).
+This project uses JUnit 5 as test framework.
+
+# Creating special tests
+
+Aside from the [normal tests](#creating-normal-test-cases), there are some special tests.
+
+## Negative parser tests
+
+To check, errors are found and contain the correct messages, one test [`Errors`](/../blob/master/src/test/java/org/jastadd/relast/tests/Errors.java) is used.
+Here, the RelAST compiler is invoked manually, and the actual error messages are compared to expected ones for each grammar in `src/test/jastadd/errors`.
+The expected messages can contain the special word `$FILENAME` to refer to the filename of the grammar, if there is only one, or `$FILENAME1`, `$FILENAME2` etc., if there are many.
+Furthermore, empty lines, lines starting with `//` and the order of the error messages are ignored.
+
+## Output diff
+
+Currently, there is one test to test whether the output of RelAST is a valid input for RelAST and produces the same output again.
+To achieve this, there two Gradle tasks. The first produces the usual `.ast` and `.jadd` files, whereas the second task takes the `.ast` as input.
+The test then ensures, that both output grammars are identical.
--
GitLab