How to z2Unit » History » Version 14
Henning Blohm, 16.08.2021 09:21
1 | 1 | Henning Blohm | h1. How to use z2Unit |
---|---|---|---|
2 | |||
3 | 13 | Henning Blohm | The *z2 Jupiter* and the *z2 Unit 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. |
4 | 2 | Henning Blohm | |
5 | 5 | 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. |
6 | 2 | Henning Blohm | |
7 | 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_, that is, simulated one way or the other, into the test assembly of things. |
||
8 | |||
9 | 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. |
||
10 | |||
11 | 13 | 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 z2Unit feature. It is recommended that you use the z2 Jupiter implementation today. |
12 | 1 | Henning Blohm | |
13 | 13 | Henning Blohm | The foundation of both implementations is that they come with a "client" side implementation, an Engine implementation in the JUnit 5 case and a Test Runner implementation in the JUnit 4 case, that delegate test discovery and test execution to a z2 server runtime.That is, although JUnit believes to run a locally defined test class, the actual test runs in another process, running the methods and reporting results corresponding to the structure of the local test implementation (which matches its server-side equivalent). |
14 | 1 | Henning Blohm | |
15 | 13 | Henning Blohm | h2. Using z2 Jupiter |
16 | |||
17 | 14 | Henning Blohm | Using z2 Jupiter is as easy as 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. |
18 | 1 | Henning Blohm | |
19 | |||
20 | 14 | Henning Blohm | |
21 | |||
22 | |||
23 | 13 | Henning Blohm | |
24 | h2. Using z2 Unit |
||
25 | |||
26 | *Note* that z2 Unit has now become an outdated implementation. It will be kept for compatibility with existing test code but is not recommended for new test implementations. |
||
27 | |||
28 | Z2Unit comes with one annotation ("Z2UnitTest":http://www.z2-environment.net/javadoc/com.zfabrik.dev.z2unit!2Fjava/api/com/zfabrik/z2unit/annotations/Z2UnitTest.html) and one Unit Test Runner ("Z2UnitTestRunner":http://www.z2-environment.net/javadoc/com.zfabrik.dev.z2unit!2Fjava/api/com/zfabrik/z2unit/Z2UnitTestRunner.html). |
||
29 | 2 | Henning Blohm | |
30 | 9 | Henning Blohm | h2. To see how this works in Eclipse |
31 | 2 | Henning Blohm | |
32 | 6 | Henning Blohm | # 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. |
33 | 4 | Henning Blohm | # Create a Z2 Java project my_tests in your Eclipse workspace. Make sure it is armed. |
34 | 2 | Henning Blohm | # Add a test reference to *com.zfabrik.dev.z2unit* to your Java component, say *my_tests/java*. |
35 | # Create a test class in src.test of your Java component like the following: |
||
36 | <pre><code class="java"> |
||
37 | 6 | Henning Blohm | package mytest; |
38 | 2 | Henning Blohm | |
39 | import org.junit.Test; |
||
40 | import org.junit.runner.RunWith; |
||
41 | import com.zfabrik.z2unit.Z2UnitTestRunner; |
||
42 | import com.zfabrik.z2unit.annotations.Z2UnitTest; |
||
43 | |||
44 | @RunWith(Z2UnitTestRunner.class) |
||
45 | @Z2UnitTest(componentName="my_tests/java") |
||
46 | public class AZ2UnitTest { |
||
47 | |||
48 | @Test |
||
49 | 6 | Henning Blohm | public void someTestMethod() { |
50 | System.out.println("Hello z2Unit"); |
||
51 | 2 | Henning Blohm | } |
52 | 1 | Henning Blohm | } |
53 | </code></pre> |
||
54 | # Resolve using the Eclipsoid plugin (see above) |
||
55 | # Right-click and choose Run-As / JUnit Test |
||
56 | 6 | Henning Blohm | |
57 | 9 | Henning Blohm | h2. To cut things short |
58 | 7 | Henning Blohm | |
59 | 9 | Henning Blohm | There is a ready-to-use test project, the most simple project with a test class like the one above really. To try that: |
60 | 6 | Henning Blohm | |
61 | 9 | Henning Blohm | |
62 | 7 | Henning Blohm | # Have z2-base.core and Eclipse set up |
63 | 12 | Henning Blohm | # Clone "https://www.z2-environment.net/git/z2-samples.z2unit":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-z2unit next to your workspace (Folders matter. No idea why? Follow [[Step_2_-_Install_and_run_in_5_minutes]]!) |
64 | 7 | Henning Blohm | # Import the project *com.zfabrik.samples.z2unit.hello* |
65 | # Resolve using the Eclipsoid plugin (see above) |
||
66 | 8 | Henning Blohm | # Open the class "com.zfabrik.samples.z2unit.test.AZ2UnitTest":https://redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-z2unit/revisions/master/entry/com.zfabrik.samples.z2unit.hello/java/src.test/com/zfabrik/samples/z2unit/test/AZ2UnitTest.java |
67 | 7 | Henning Blohm | # Right-click and choose Run-As / JUnit Test |
68 | |||
69 | You should see this: |
||
70 | |||
71 | 1 | Henning Blohm | !z2unit_screen.png! |
72 | 7 | Henning Blohm | |
73 | 11 | Henning Blohm | h2. Using and Configuring z2Unit outside of the IDE |
74 | 2 | Henning Blohm | |
75 | 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. |
||
76 | |||
77 | 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 z2Unit tests just as any unit tests also from an ANT script for example. A typical application is to run z2Unit integration tests as part of your test automation effort. |
||
78 | 3 | Henning Blohm | |
79 | 11 | Henning Blohm | The execution of a z2Unit test requires the test client, which is the local JUnit runtime invoked by ANT (or your IDE as above) invoking the @Z2UnitTestRunner@, 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. |
80 | 1 | Henning Blohm | |
81 | 11 | Henning Blohm | For example, you could define a different @z2unitUrl@ when configuring the @Z2UnitTest@ annotation. |
82 | |||
83 | That is not practical when running test automatically however, as you would not want to change application code for that purpose. |
||
84 | |||
85 | Instead you can specify essentially the same configuration that the @Z2UnitTest@ annotation holds by setting any of the system properties shown belown during test execution. For example in your ANT script. |
||
86 | |||
87 | Alternatively you can specify these configuration settings by putting a file called, by default, @z2unit.properties@ on the classpath of the Unit Test Runner (i.e. the ANT test execution classpath for example). The name of the configuration file can be overwritten in a test specific way by setting in on the @Z2UnitTest@ annotation on the test class, in case you need many different configurations. |
||
88 | |||
89 | Properties that control the behavior of the @Z2UnitTestRunner@, and that may be specified as system properties or via the configuration file are shown in the following table: |
||
90 | |||
91 | |_. Property Name |_. Property Meaning | |
||
92 | | z2unit.className | Name of the test class. As a result, z2Unit will report test execution events on that class which may not match the structure of the client side class. | |
||
93 | | z2unit.componentName | Name of the java component that contains the test class. A short form may be used for java components "/java". | |
||
94 | | z2unit.z2unitUrl | URL to send the test request to. Defaults to @http://localhost:8080/z2unit/run@. | |
||
95 | |||
96 | |||
97 | h2. Using other Unit Test Runners |
||
98 | |||
99 | 3 | Henning Blohm | Using the Z2UnitTest annotation, a test can be configured to run with a non-standard unit test runner. That is useful for example, if your test is actually a test suite or something special like a Spock test. See [[Sample-groovy-in-Z2]] for an example of the latter. |
100 | 1 | Henning Blohm | |
101 | Furthermore, a unit test can be configured to have some runtime dependencies in Z2, i.e. components that should be prepared prior to the test execution. That is extremely useful, if the test depends on a configured Spring application context for example. In the latter case, the test could even use Spring configuration annotations (which is what we typically do). |
||
102 | 11 | Henning Blohm | |
103 | h2. References |
||
104 | 3 | Henning Blohm | |
105 | Read on in the "Javadocs":http://www.z2-environment.net/javadoc/com.zfabrik.dev.z2unit!2Fjava/api/com/zfabrik/z2unit/annotations/Z2UnitTest.html for more details. |