Skip to content
Snippets Groups Projects
Commit d866407d authored by René Schöne's avatar René Schöne
Browse files

Begin with guide for contributing, covering creation of test cases.

parent 0b47751a
Branches
Tags
1 merge request!8Resolve "Create guides for contributing"
# 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.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment