This is the JacORB Regression Test Suite.

Building and running the tests
------------------------------

NB: The name server must be running before running these tests!

The JacORB test suite consists of a set of JUnit tests and an Ant XML
file for building and running them.  Depending on the Ant target that
is invoked, it is possible to run all tests in a package hierarchy or
to run only the tests within a specific package.  Furthermore, it is
possible to log all test results in a single file or to log the result
of each test in a separate file.

All ant targets must be invoked from the root of the test repository
where the Ant XML file is located.  To see which Ant targets are
available, type 'ant -projecthelp'.  Only the main targets (targets
with descriptions) can be invoked.

Log files generated by the tests are written to the 'output' directory
with the name 'TEST-<classname>' where <classname> is the full class
name of the tests being run.

In order to run the JacORB tests the following must be in the
classpath:
  - JUnit 3.8.1 (junit.jar), available at http://www.junit.org/
  - optionally: jacorb.jar, if jacorb classes should be taken from
    there. By default, classes from the classes/ dir are used.

The tests are being developed using JUnit 3.8.1 and Ant 1.5.1. Please make
sure your Ant installation has the "optional.jar" file in its lib/ directory.

Adding new tests
----------------

The following steps are necessary to add a new set of JUnit tests to
the JacORB test suite.


   Source Code
   -----------

1. Write the tests using the JUnit framework.  Tests should be packaged using
   the same packaging as the source that is being tested, but replacing
   'org.jacorb' with 'org.jacorb.test'.  Any helper classes that can be used
   by tests in different packages should be put in the package
   'org.jacorb.test.common'.  All source code in the test hierarchy can be
   found under the 'src' directory.

   For example, the DynAny source is in the package 'org.jacorb.orb.dynany'.
   Therefore, the JUnit tests that test the DynAny source are in the package
   'org.jacorb.test.orb.dynany'.  Many tests in the orb package and elsewhere
   use a special client/server setup; this can be found under
   org.jacorb.test.common.


2. Create a Java source file named 'PackageTest.java' that will run all JUnit
   tests within the package.  An example of this file can be found in the
   directory containing the DynAny tests.  This file can be copied and modified
   to create a new PackageTest file.  If adding tests to a package that
   already contains this file then be sure to modify it to include the newly
   added tests.


3. Create a Java source file named 'AllTest.java' that will run all JUnit
   tests within the package and each of its subpackages.  An example of this
   file can be found in each package in the test hierarchy.  The AllTest
   file at the root of the test hierarchy (in the package 'org.jacorb.test')
   will run all the tests in the repository.  It does this by calling on to
   the AllTest test suite in each of its subpackages, which in turn call on to
   the AllTest test suites in each of their subpackages, until all tests are
   executed.  If adding tests to a package that already contains this file then
   no modifications to the existing file are required.


4. Modify the AllTest file in the package immediately above the package where
   the tests are being added.  This file needs to include the test suite of
   the AllTest file in the newly added package of tests.  If adding tests to
   a package that already contains an AllTest file then this modification is
   not required.


   IDL
   ---

1. Add any IDL files to the 'idl' directory in the test repository.  The
   'pragma prefix' directive should be set to 'jacorb.org'.


   Ant XML
   -------

1. The following modifications are needed for each new IDL file added to the
   test repository:

   Copy and modify the target named 'idl-tests'.  This target compiles the
   Tests.idl file.  To change this target to compile a different IDL file,
   set the values of the three properties in the target as follows:
      prop.idl = the name of the IDL file excluding the .idl extension
      pkg.idl  = the package containing the source code and any subpackages
                 generated from the IDL
      file.idl = the name of the IDL file including the .idl extension
   Rename this target to 'idl-<name>' where <name> refers to the name of the
   IDL file (excluding the .idl extension and beginning with a lower case
   character).

   Modify the target named 'compile-idl' to call on the newly added target.
   This modification involves adding an 'antcall' task whose 'target'
   attribute is set to the name of the target added in the above step.


2. The following modifications are needed for each new package of tests that
   are added to the test repository:

   Add a target to run the new set of tests as a package using the
   PackageTest test suite.  This target should have the name
   'run-package-<package>' where <package> refers to the name of the package
   containing the tests.  The target 'run-package-dynany' can be copied and
   modified to create the new target.

   Add a target to run the new set of tests as a package hierarchy using the
   AllTest test suite.  This target runs all tests in the package and any
   subpackages and should have the name 'run-all-<package>' where <package>
   refers to the name of the package containing the tests.  The target
   'run-all-dynany' can be copied and modified to create the new target.

   Add a target to run the new set of tests as a package using the
   individual test suites.  This target should have the name
   'run-package-<package>-separate' where <package> refers to the name of the
   package containing the tests.  The target 'run-package-dynany-separate' can
   be copied and modified to create the new target.  Each individual test in
   the package must be called from this target.

   Add a target to run the new set of tests as a package hierarchy using the
   individual test suites.  This target runs all tests in the package and any
   subpackages and should have the name 'run-all-<package>-separate' where
   <package> refers to the name of the package containing the tests.  The
   target 'run-all-dynany-separate' can be copied and modified to create the
   new target.  The 'run-package-<package>-separate' target and the
   'run-all-<subpackage>-separate' target in each subpackage must be called
   from this target.

   NOTE:  If new tests are being added to a package that already exists, then
          all that should be required is to modify the appropriate
          'run-package-<package>-separate' target so that each of the newly
          added tests is called.
