z2-Environment

h1. How to use z2Unit

The z2Unit feature of "z2-base.base":http://redmine.z2-environment.net/projects/z2-base/repository/base?rev=master allows 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.

In-system tests are ordinary unit tests that run within the server environment. Running tests within the running environment is also called integration testing. 

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. 

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.

The foundation of the z2Unit feature is a JUnit Test Runner implementation that delegates the actual test execution to a Z2 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).

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).

h2. To see how this works in Eclipse

# 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.

# Create a Z2 Java project my_tests in your Eclipse workspace. Make sure it is armed.

# Add a test reference to *com.zfabrik.dev.z2unit* to your Java component, say *my_tests/java*. 

# Create a test class in src.test of your Java component like the following:

<pre><code class="java">

package mytest;

import org.junit.Test;

import org.junit.runner.RunWith;

import com.zfabrik.z2unit.Z2UnitTestRunner;

import com.zfabrik.z2unit.annotations.Z2UnitTest;

@RunWith(Z2UnitTestRunner.class)

@Z2UnitTest(componentName="my_tests/java")

public class AZ2UnitTest {

    @Test

    public void someTestMethod() {  

        System.out.println("Hello z2Unit");

    }

}

</code></pre>

# Resolve using the Eclipsoid plugin (see above)

# Right-click and choose Run-As / JUnit Test

h2. To cut things short

There is a ready-to-use test project, the most simple project with a test class like the one above really. To try that:

# Have z2-base.core and Eclipse set up

# Clone "http://git.z2-environment.net/z2-samples.z2unit":http://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]]!)

# Import the project *com.zfabrik.samples.z2unit.hello*

# Resolve using the Eclipsoid plugin (see above)

# 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

# Right-click and choose Run-As / JUnit Test

You should see this:

!z2unit_screen.png!

h2. More notes

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.

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.

h2. More configuration details

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.

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).

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.