This test kit is designed to test the Jini(TM) technology-enabled components and services supplied in the Jini Technology Starter Kit (starter kit). All of these tests run in the Jini Test Harness V3 (harness). This kit contains the Java source code for all of the tests and support code that make up this test suite. The jar files generated from this source is included in the lib directory and are identical to the files used in production testing by the Jini Technology Group. This document assumes familiarity with the documentation supplied with the test harness kit.

Installation Directory

This kit may be installed in a user selected directory. Installation parameters are provided in a deployment properties file which is named on the command line used to run the harness. The directory containing the test kit is identified in this file by the property org.apache.river.test.home. In property files and in this document this directory will be referred to symbolically as ${org.apache.river.test.home}.

Deployment Properties File

When the harness is invoked from the command line, the name of a user-supplied deployment properties file must be provided. The example prototype for this file is located in ${org.apache.river.test.home}/src/org/apache/river/test/resources/qaHarness.prop.. That file is derived from the basicDeployment.prop file that is included in the harness source kit, and provides additional definitions specific to this test suite, including the installation directory property described above.

Test Logging

The tests in this test suite extend the harness test class org.apache.river.qa.harness.QATest. As a result, test output is generated by calls to the Java logging API to the logger supplied by that class, having the name org.apache.river.qa.harness.

Running a Test

To run the harness, at least two JAR files must be included in the classpath: 
        ${org.apache.river.qa.home}/lib/jiniharness.jar
is the JAR file containing the harness code and resources, and 
        ${org.apache.river.jsk.home}/lib/jsk-platform.jar
is the starter kit platform that is typically included in the classpath of Jini clients and services.

The user must specify the name of a deployment properties file on the command line as described above. The user must also specify the name of the primary test suite JAR file via the command-line option -testJar ${org.apache.river.test.home}/lib/jinitests.jar. In the following examples, assume that the test source kit is installed in /files/jiniqa2_1_tests_source, the starter kit has been installed in /files/jini2_1, and the harness binary kit has been installed in /files/jiniqa2_1_harness. Also assume that /tmp/myharness.prop is an edited version of /files/jiniqa2_1_tests_source/src/org/apache/river/test/resources/qaHarness.prop, modified to reflect the correct installation environment.

To specify a set of test categories to run, use the -categories option, for example: 

  java -cp /files/jiniqa2_1_harness/lib/jiniharness.jar:/files/jini2_1/lib/jsk-platform.jar \
       org.apache.river.qa.harness.QARunner \
       /tmp/myharness.prop \
       -testJar /files/jiniqa2_1_tests_source/lib/jinitests.jar \
       -categories joinmanager,javaspace
This would limit test execution to those tests whose test descriptions included either joinmanager or javaspace in their definitions of testCategories. The configuration used would be none unless the value of org.apache.river.harness.configs had been modified in /tmp/myharness.prop.

To specify an explicit list of tests to execute, list them after the -tests option. For example, 

  java -cp /files/jiniqa2_1_harness0/lib/jiniharness.jar:/files/jini2_1/lib/jsk-platform.jar \
       org.apache.river.qa.harness.QARunner \
       /tmp/myHarness.prop \
       -testJar /files/jiniqa2_1_tests_source/lib/jinitests.jar \
       -tests org/apache/river/test/spec/joinmanager/EqualsTest
This would execute only the joinmanger EqualsTest test. The following command line would run this test using the jeri ConfigurationFileSet: 
  java -cp /files/jiniqa2_1_harness0/lib/jiniharness.jar:/files/jini2_1/lib/jsk-platform.jar \
       org.apache.river.qa.harness.QARunner \
       /tmp/myHarness.prop \
       -testJar /files/jiniqa2_1_tests_source/lib/jinitests.jar \
       -tests org/apache/river/test/spec/joinmanager/EqualsTest \
       -org.apache.river.qa.harness.configs jeri
The -tests argument is optional, and if present must be followed by a comma-separated list of test description file names specified relative to the root of the primary test suite JAR file. This identifies the set of tests to place in the run list, which may be additionally filtered by category. If omitted, all tests are placed in the run list.

The -categories argument is optional, and if present must be followed by a comma-separated list of test categories. When the run list is processed, tests which do not belong to one of the specified categories are discarded from the list. If omitted no category filtering is done.

One or both of these options must be specified.

Supporting Kerberos Configurations

The harness includes configuration files that support testing with kerberos as the underlying security infrastructure. However, in order to run with kerberos some additional setup is required.

1. In order to run the Kerberos harness configuration, you need a Kerberos KDC (Key Distribution Center) available in your network.

2. You also need to create principals for reggie, mahalo, outrigger, mercury, norm, phoenix, an executing test (this is a single principal used for all tests), fiddler, an activation group (again a single principal used for all activation groups), a server principal, and a client principal. Refer to your KDC documentation for instructions on how to create principals for that particular KDC.

3. Once the principals needed by the harness have been created, generate an aggregate password file containing the passwords for all the principals created in step 2 and store this password file in a location that is accessible to the harness. Refer to your KDC documentation for instructions on how to create password files for your KDC.

4. Edit the following section in the deployment properties file derived from ${org.apache.river.test.home}/src/org/apache/river/test/resources/qaHarness.prop: 

#
# The following properties are used to specify the kerberos
# environment for tests that need to access a kdc and kerberos principals
#
org.apache.river.qa.harness.kerberos.realm=[add the realm that your KDC is serving]
org.apache.river.qa.harness.kerberos.kdc=[add the name of your KDC host]
org.apache.river.qa.harness.kerberos.clientPasswordFile=[add the location for the password file created in step 3]
org.apache.river.qa.harness.kerberos.serverPasswordFile=[add the location for the password file created in step 3]
org.apache.river.qa.harness.kerberos.aggregatePasswordFile=[add the location for the password file created in step 3]
org.apache.river.qa.harness.kerberos.clientPrincipal=[add the name of the client principal created in step 2]
org.apache.river.qa.harness.kerberos.serverPrincipal=[add the name of the client principal created in step 2]
org.apache.river.qa.harness.kerberos.reggiePrincipal=[add the name of the reggie principal created in step 2]
org.apache.river.qa.harness.kerberos.mahaloPrincipal=[add the name of the mahalo principal created in step 2]
org.apache.river.qa.harness.kerberos.outriggerPrincipal=[add the name of the outrigger principal created in step 2]
org.apache.river.qa.harness.kerberos.mercuryPrincipal=[add the name of the mercury principal created in step 2]
org.apache.river.qa.harness.kerberos.normPrincipal=[add the name of the norm principal created in step 2]
org.apache.river.qa.harness.kerberos.phoenixPrincipal=[add the name of the phoenix principal created in step 2]
org.apache.river.qa.harness.kerberos.testPrincipal=[add the name of the test principal created in step 2]
org.apache.river.qa.harness.kerberos.fiddlerPrincipal=[add the name of the fiddler principal created in step 2]
org.apache.river.qa.harness.kerberos.groupPrincipal=[add the name of the group principal created in step 2]

5. If you wish to run the End2End Security Test, you must also edit ${org.apache.river.test.home}/src/org/apache/river/test/impl/e2etest/End2EndTestKerberos.td and provide a value for the org.apache.river.test.impl.end2end.kinit property. The value for this property should be the command that generates forwardable tickets stored in the local ticket cache for your KDC. Because the default search path used by the harness does not include this directory, the search path must be augmented to include the src directory. This can be done on the command line by adding the following option:

-searchPath '${searchPath},${org.apache.river.test.home}/src'

or in the deployment properties file by adding:

searchPath=${searchPath},${org.apache.river.test.home}/src

Note that adding src to the search path will introduce a noticable delay to the initialization phase of the harness, but has little impact during test execution.