Package com.zfabrik.dev.z2jupiter

Annotation Interface Z2JupiterTestable

@Retention(RUNTIME) @Target(TYPE) public @interface Z2JupiterTestable
Annotation marking a test class as executable via the Z2 Jupiter Test Engine. The Z2 Jupiter Test Engine performs test execution in the actual server-side application runtime environment rather than in the runtime environment of the client requesting the test.

To do so, requests for test discovery and execution are sent from the client, where the test is initiated (e.g. your IDE), to the Web application com.zfabrik.dev.z2jupiter/web listening on the context path /z2jupiter and running as part of environment/webWorkerUp by default.

Technically, the Z2 Jupiter Test Engine masks test execution of annotated classes for non-execution locally and for normal execution remotely and reports test events as if executed locally, so that, from a local client perspective the execution is as if it happened locally, while the execution on the remote end works ignoring Z2 Jupiter and so in principle, supports any other test engine or configuration model.

You may combine this annotation with other test engine annotations.

Using this annotation as well as through system properties and environment settings various aspects of the execution may be configured.

One particular aspect of execution is the remote location to test one that may be set using the url() attribute. This setting may be overwritten, in order of preference by

  • The system property com.zfabrik.dev.z2jupiter.url
  • The environment variable Z2_JUPITER_URL

Remote access to test discovery and execution is protected by authentication. User name and password may be specified by setting the user() and password() attribute respectively. Authentication is verified against the default "realm" that is configured in environment/webUsers (and may be changed by adapting the built-in Jetty Web server configuration). Alternatively, username and password may be specified by system properties and environment properties, where system properties take preference.

For username:

  • The system property com.zfabrik.dev.z2jupiter.user
  • The environment variable Z2_JUPITER_USER

For password:
  • The system property com.zfabrik.dev.z2jupiter.password
  • The environment variable Z2_JUPITER_PASSWORD

Note: In order to make remote execution from non-localhost clients possible, you may need to change z2 configuration to allow such remote access or use a means tunneling, like SSH tunneling (see also How to Secure a Z2 Installation)

Configuration for a unit test class that is to run via the Z2 Jupiter Test Engine simply requires to specify this annotation: 


 @Z2UnitTestable(componentName="com.acme.modulex/java")
 public class SomeTests {
        @Test
        public void testThis() throws Exception {
                // some test code
        }
 }

Sometimes it can be handy to initialize other components before running a test (e.g. a Spring application context). Instead of using a super class to do static initialization, you can instead use the dependencies() attribute to specify Z2 components to be prepared before the test run. For example a test that requires a Spring application context to be initialized and makes use of Spring configuration could look like this: 


 @Z2UnitTestable(
   componentName="com.acme.modulex/java",
   dependencies={"com.acme.modulex/applicationContext"}
 )
 @Configurable
 public class BusinessTests {
 
   @Autowired
   private SomeService someService;
   
   @Test @Transactional
   public void testSomething() {
     // ...
   }
 
 }
The Z2 Jupiter Engine feature builds on the JUnit 5 API and succeeds the Z2 Unit feature (see Z2UnitTestRunner).

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    componentName
    Name of the java component that contains the test class.
    String[]
    dependencies
    Runtime dependencies specified as component names.
    String
    password
    Password name to send for authentication.
    String
    url
    URL to send the test request to.
    String
    user
    Username to send for authentication.

  • Element Details

    • componentName

      String componentName
      Name of the java component that contains the test class. A short form reduced to the module name may be used for java components ending with "/java".
      Returns:
      Default:
      ""

    • url

      String url
      URL to send the test request to. Defaults to http://localhost:8080/z2unit.jupiter/run. The URL may alternatively be defined by the system property com.zfabrik.dev.z2jupiter.url or the environment variable Z2_JUPITER_URL.
      Returns:
      Default:
      "http://localhost:8080/z2jupiter"

    • user

      String user
      Username to send for authentication. Defaults to "z*". The username may alternatively be defined by the system property com.zfabrik.dev.z2jupiter.user or the environment variable Z2_JUPITER_USER.
      Returns:
      Default:
      "z*"

    • password

      String password
      Password name to send for authentication. Defaults to "z". The password may alternatively be defined by the system property com.zfabrik.dev.z2jupiter.password or the environment variable Z2_JUPITER_PASSWORD.
      Default:
      "z"

    • dependencies

      String[] dependencies
      Runtime dependencies specified as component names. Before executing a test on the z2 side, these components will be looked up as IDependencyComponent and, if successful, be asked to IDependencyComponent.prepare().
      Default:
      {}