Project

General

Profile

How to Unit Test in Z2 » History » Version 10

Henning Blohm, 18.08.2021 09:22

1 1 Henning Blohm
h1. How to Unit Test in Z2
2
3 8 Henning Blohm
(Applies to z2 Version 2.9 and later)
4
5 9 Henning Blohm
The *Z2 Jupiter* feature of "z2-base.base":http://redmine.z2-environment.net/projects/z2-base/repository/base?rev=master allow to run in-system tests on z2, from anywhere where you can run JUnit tests. To learn more about the JUnit testing framework, please visit http://www.junit.org .
6 1 Henning Blohm
7 9 Henning Blohm
In-system tests are ordinary unit tests that run within the server environment. Running tests within the running environment is also called integration testing.
8 1 Henning Blohm
9 9 Henning Blohm
Standard JUnit tests run in an environment that often has little to do with the tested code's "native" environment, other than seeing the same types. Anything else, database connectivity, domain test data, component and naming abstractions (e.g. JNDI) need to be firstly abstracted out from the tested code and secondly _mocked_<notextile></notextile>, that is, simulated one way or the other, into the test assembly of things.
10 1 Henning Blohm
11
While that has the advantage of a defined, clean-room test bed, for higher-level components this can become unreasonable and assuring the correctness of the mocked up environment becomes a testing issue on its own.
12
13 9 Henning Blohm
The z2 Jupiter feature is built on the "JUnit 5":https://junit.org/junit5/ API that succeeded the "JUnit 4":https://junit.org/junit4/ API that is the underlying foundation of the previously promoted z2Unit feature (see [[How_to_z2Unit|How to z2Unit]]). It is recommended that you use the z2 Jupiter implementation today starting with z2 Version 2.9.
14 1 Henning Blohm
15 9 Henning Blohm
At the heart of Z2 Jupiter lies the Z2 Jupiter Test Engine implementation that delegate test discovery and test execution to a running z2 server runtime. That is, although JUnit believes to run a locally defined test class, the actual test execution is performed in another process, running the test methods and reporting results back to the client.
16 1 Henning Blohm
17
h2. Using z2 Jupiter
18
19 9 Henning Blohm
Using z2 Jupiter is as easy as referencing the module *com.zfabrik.dev.z2jupiter* from the test module and adding one more annotation to your test class: "Z2JupiterTestable":http://www.z2-environment.net/javadoc/com.zfabrik.dev.z2jupiter!2Fjava/api/com/zfabrik/dev/z2jupiter/Z2JupiterTestable.html<notextile></notextile>.
20 1 Henning Blohm
21 9 Henning Blohm
Z2 Jupiter uses itself for testing. You can see a simple "Hello World" test at z2-base:source:base|com.zfabrik.dev.z2jupiter/java/src.test/com/zfabrik/dev/z2jupiter/test/HelloZ2JupiterTest.java :
22 1 Henning Blohm
23 9 Henning Blohm
<pre><code>
24 2 Henning Blohm
package com.zfabrik.dev.z2jupiter.test;
25 1 Henning Blohm
26 2 Henning Blohm
import org.junit.jupiter.api.Test;
27 1 Henning Blohm
28 2 Henning Blohm
import com.zfabrik.dev.z2jupiter.Z2JupiterTestable;
29
import com.zfabrik.dev.z2jupiter.impl.Z2JupiterImpl;
30 1 Henning Blohm
31 2 Henning Blohm
@Z2JupiterTestable(componentName = Z2JupiterImpl.MODULE_NAME)
32
public class HelloZ2JupiterTest {
33 9 Henning Blohm
34
    @Test
35
    public void helloZ2Jupiter() {
36
        System.err.println("Hello Z2 Jupiter");
37
    }
38 2 Henning Blohm
}
39 1 Henning Blohm
</code></pre>
40 2 Henning Blohm
41 1 Henning Blohm
Check out more test examples in z2-base:source:base|com.zfabrik.dev.z2jupiter/java/src.test/com/zfabrik/dev/z2jupiter/test .
42 5 Henning Blohm
43 9 Henning Blohm
If you want to use Z2 Jupiter in your projects for tests implemented under *java/src.test*<notextile></notextile>, make sure to have the framework referenced in *java/z.properties* like this:
44 2 Henning Blohm
45 9 Henning Blohm
<pre><code>
46 2 Henning Blohm
java.testReferences=\
47 9 Henning Blohm
    com.zfabrik.dev.z2jupiter,\
48 2 Henning Blohm
</code></pre>
49
50 1 Henning Blohm
h2. To see how this works in Eclipse
51
52
# Follow the "Up in 5 minutes" trail [[Step_2_-_Install_and_run_in_5_minutes]] to make sure you understand how to setup z2 and Eclipse.
53
# Create a Z2 Java project my_tests in your Eclipse workspace. Make sure it is armed.
54 9 Henning Blohm
# Add a test reference to *com.zfabrik.dev.z2jupiter* to your Java component, say *my_tests/java*<notextile></notextile>.
55 1 Henning Blohm
# Create a test class in src.test of your Java component like the following:
56 9 Henning Blohm
57
<pre><code>
58 1 Henning Blohm
package mytest;
59
60
import org.junit.jupiter.api.Test;
61 3 Henning Blohm
62 1 Henning Blohm
import com.zfabrik.dev.z2jupiter.Z2JupiterTestable;
63 3 Henning Blohm
64 1 Henning Blohm
@Z2JupiterTestable(componentName="my_tests/java")
65
public class AZ2UnitTest {
66
67
    @Test
68
    public void someTestMethod() {  
69
        System.out.println("Hello World!");
70
    }
71
}
72
</code></pre>
73 9 Henning Blohm
74 1 Henning Blohm
# Resolve using the Eclipsoid plugin (see above)
75
# Right-click and choose Run-As / JUnit Test
76
77
h2. Using and Configuring z2Unit outside of the IDE
78
79
Note that resolving the dependencies and synchronizing the runtime is an important prerequisite to running a z2Unit Unit Test class. You need to have all dependencies of the test class resolved so that JUnit can resolve the test class locally (although all the action will happen elsewhere) and you need to have synchronized so that the matching definitions are found on the server side.
80
81 6 Henning Blohm
If you want to automate tests and cannot rely on the Eclipsoid to have a suitable class path, you should use the "com.zfabrik.dev.util/jarRetriever":http://www.z2-environment.eu/v21doc#Retrieving%20jars%20from%20Z2 tool to retrieve all required dependencies. In that case, you can run Z2 Jupiter tests just as any unit tests also from an ANT script for example. A typical application is to run Z2 Jupiter integration tests as part of your test automation effort.
82 1 Henning Blohm
83 9 Henning Blohm
See in particular [[How_to_download_jars_from_Z2|How to download jars from Z2]] on how to integrate jar retrieving with ANT.
84 1 Henning Blohm
85 9 Henning Blohm
The execution of a Z2 Jupiter test requires the test client, which is the local JUnit runtime invoked by ANT (or your IDE as above) invoking the *Z2 Jupiter Test Engine*<notextile></notextile>, to connect via HTTP to the Z2 application server. If you run tests on the same operating system instance the application runs on, this works by default by reaching out to localhost. If your application server is on a different machine though, you will want to configure that accordingly.
86 1 Henning Blohm
87 9 Henning Blohm
For example, you could define a different URL when configuring the @Z2JupiterTestable@ annotation.
88 6 Henning Blohm
89 1 Henning Blohm
That is not practical when running test automatically however, as you would not want to change application code for that purpose.
90
91 6 Henning Blohm
Instead you can specify essentially the same configuration that the @Z2JupiterTestable@ annotation holds by setting any of the system properties or environment variables shown belown before test execution. For example in your ANT script.
92 1 Henning Blohm
93 9 Henning Blohm
Properties that control the behavior of the @Z2JupiterTestable@ , and that may be specified as system properties or via the configuration file are shown in the following table:
94 1 Henning Blohm
95 6 Henning Blohm
|_. Property Name |_. Environment Variable |_. Property Meaning |
96 9 Henning Blohm
| com.zfabrik.dev.z2jupiter.url | Z2_JUPITER_URL | URL to send the test request to. Defaults to @http://localhost:8080/z2unit.jupiter/run@ . |
97 1 Henning Blohm
98 10 Henning Blohm
h2. Authentication and Remote Access
99
100
Note that connecting to Z2 for remote test execution requires authentication and is by default only accessible from localhost. The Z2 Jupiter test engine for JUnit 5 as well as the Z2UnitTestRunner for JUnit 4 use (by default) the user “z*” for test execution.
101
102
See also [[How to Secure a Z2 Installation]].
103
104 1 Henning Blohm
h2. References
105
106 9 Henning Blohm
Read on in the "Javadocs":http://www.z2-environment.net/javadoc/com.zfabrik.dev.z2jupiter!2Fjava/api/com/zfabrik/dev/z2jupiter/Z2JupiterTestable.html<notextile></notextile>. for more details.