-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.adoc.jam
147 lines (104 loc) · 7.08 KB
/
README.adoc.jam
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
{%#define YamlSource($x)={%@java:class (format="`@$simpleName{%@if/$x/($x)/%}`") javax0.yamaledt.YamlSource%}%}\
{%#define Jamal={%@java:class (format="`@$simpleName`") javax0.yamaledt.Jamal%}%}\
{%#define DisplayName={%@java:class (format=`@$simpleName`)org.junit.jupiter.api.DisplayName%}%}\
{%#define Name($x)={%@java:class (format="`@$simpleName{%@if/$x/($x)/%}`")javax0.yamaledt.Name%}%}\
{%#define ParameterizedTest={%@java:class (format=`@$simpleName`) org.junit.jupiter.params.ParameterizedTest%}%}\
{%@options lenient%}\
{%@import version.jim%}\
== Patuyaja -- JUnit 5 Parameterized Tests Using Yaml and Jamal
=== Introduction and usage
{%#if/{%#replace(regex)|{%VERSION%}|\d+\.\d+\.\d+-SNAPSHOT|%}//
NOTE: This is the latest development documentation.
This is a SNAPSHOT version.
To see the documentation of a release you have to follow the link in the documentation link:{%@file RELEASES.adoc%}[`RELEASES.adoc`]
%}
You can create parameterized unit tests fetching the data from Yaml formatted resource file using Patuyaja.
To use the possibility add the dependency to your build configuration.
In case of Maven, for example, add the following lines to your `dependencies` configuration part:
[source,xml]
----
<dependency>
<groupId>com.javax0.yamaledt</groupId>
<artifactId>yamaledt</artifactId>
<version>{%VERSION%}</version>
<scope>test</scope>
</dependency>
----
The next step is to create a parameterized test, and the Yaml file that holds the data set for the tests.
{%@snip:collect from=./src/test/java/%}
[source,java]
----
{%@snip sampleTestWithSimpleParameters%}
----
The JUnit 5 annotation {%ParameterizedTest%} signals that this test is a parameterized test.
The annotation {%YamlSource%} specifies the test data source.
In this case all the settings are the default, there are no arguments.
The data will be read from the resource file {%@java:method (format=`$name.yaml`) javax0.yamaledt.TestYamalArgumentProvider#sampleTestWithSimpleParameters%}.
The name is calculated from the name of the test method, and the extension `.yaml` is appended to it.
The Yaml data source file contains the data in the format:
[source,yaml]
----
{%@include [verbatim] src/test/resources/javax0/yamaledt/sampleTestWithSimpleParameters.yaml%}
----
The Yaml file describes a Map structure.
The keys are the test names.
These are the strings that will get into the place of the strings, which are defined using the {%DisplayName%} annotation in non-parameterized tests.
The value for each test is also a Map specifying the values for the test parameters.
The mapping of values can be based on
* the type of the method arguments, or
* the value of the annotation {%Name/%}.
In the example above we have three parameters.
* One is named using {%Name/"DisplayName"%},
* one unnamed, and
* one named using {%Name/"k"%}.
In the Yaml file the main key, is used for the parameter named 'DisplayName'.
For the unnamed parameter the type is used, which is, in this case is `int`.
Finally, the last parameter gets the value from the map using the key `k`.
Running this test from an IDE will result a view something like this:
image::images/idea_sample_run.png[]
=== Annotation {%YamlSource%}
The annotation {%YamlSource%} is used to specify parameters for the test.
You have to use it together with the annotation {%ParameterizedTest%}.
You have to use this annotation on the test method.
The use of the annotation instructs JUnit 5 to execute the test as a parameterized test, and to use the {%@java:class (format=`$simpleName`)javax0.yamaledt.YamalArgumentsProvider%}, which implements the Yaml data source handling for parameterized tests.
The annotation can define parameters for the parameters, like the name of the Yaml file.
The annotation can also be applied to the enclosing class.
This is useful in case annotation parameters are shared by multiple test methods.
The annotation on the class can define these parameters, and the methods inherit the value from there.
For example, you can use the same single Yaml file for test parameter storage and provide an OGNL expression to point to the data of the individual tests.
In this case the name of the file can be provided on the class, shared, and the different OGNL expressions can be defined in the annotations on the methods.
The parameters of the annotation are:
* `value` may specify the file that holds the test data.
If it is not specified then the name of the name of the test method will be used with the extension `.yaml.jam` or `.yaml`.
The extension `.yaml.jam` is used by default.
The extension `.yaml` is used when the `@Jamal` annotation `enabled=false` disables the Jamal processing.
If there is a specified value, then the value is used as a resource name, and no extension is appended to the name.
That way you have to specify {%YamlSource/"testData.yaml"%}.
The name of the method is only considered a file name if the annotation does not define a value on the method and also not on any of the enclosing classes.
* `jamal` may specify a `@Jamal` annotation.
The use of this parameter is not recommended.
The same result can be achieved adding the `@Jamal` annotation directly on the test method or on the class containing the test method.
* `ognl` may specify an https://commons.apache.org/proper/commons-ognl/[OGNL expression].
If this value is defined then the test environment uses only the structure pointed by this expression as test data.
Using this along with putting a {%YamlSource%} annotation on the class you can use
=== Annotation {%Jamal%}
The annotation {%Jamal%} is used to specify parameters for the input Jamal processing.
Jamal is a general purpose text preprocessor that can go to extreme to eliminate input redundancy and copy-paste.
This way the data structures that appear repeatedly in the test data structure can be described programmatically.
Jamal supports Yaml data structure handling through an extension module, and the Jamal transformation process can be debugged via Web user interface.
The core Jamal modules as well as the debugger module, yaml and snippet handling modules are included in the project dependencies.
If you want to use any other module you need to add those to the project as a dependency.
For more information about Jamal read the documentation at https://github.com/verhas/jamal
The parameters of the annotation are
* `open` can specify the macro opening string.
This is {%@escape `` `{%` ``%} by default.
* `close` can specify the macro closing string
This is {%@escape `` `%}` ``%} by default.
* `enabled` can be used to disable Jamal processing on the input.
The default is to interpret the input as a macro text that results Yaml as output.
Use `@Jamal(enabled=false)` annotation on the method to disample Jamal processing.
When Jamal processing is disabled the default file name extension will be `.yaml` when the parameter resource name is calculated from the method name.
* `dump` can be used to specify a file name where the output of the Jamal processing in written.
This content does not need to be written into a file.
It is processed in memory usually.
This option is only provided in case you want to look at the generated, already pure Yaml formatted file.