This section assumes you are already familiar with building Xalan-J and with Ant.

Set JAVA_HOME, and have your classes.zip or tools.jar in the CLASSPATH.

Here are some sample commands to build and run tests:

cd /builds
checkout xml-xalan/java Get the Xalan-J code (or simply get a nightly build or distro)
cd xml-xalan/java
build jar Build Xalan-J as usual
build smoketest Run the build Smoketest (optional; simply calls the smoketest target below)

cd /builds
checkout xml-xalan/test
cd xml-xalan/test
build jar Build the test framework/harness and most API/conf/etc. tests into java/build/testxsl.jar
build smoketest Run the build Smoketest (includes a selection of API tests and the conf tests); results in smoketest/
build conf Run the StylesheetTestletDriver over the conf dir; results in results-conf/
build conf -Dqetest.optionName=valueName -Dqetest.category=axes Run the StylesheetTestletDriver over the conf dir; passing options, and only on the axes subdirectory
build api -DtestClass=TransformerAPITest Run a single API test; results in results-api/
build harness Run the full set of individual API tests; results in results-api/

build extensions.classes Compile the tests/extensions tests
build extensions Run the tests/extensions tests
build bugzilla.classes Compile the tests/bugzilla bug regression tests
build bugzilla Run the tests/bugzilla bug regression tests
build clean Clean up the built automation (does not clean any results you've generated)
build -h Get help on build.bat/build.sh options and Ant targets

Changing options:

Since we use the Ant test/build.xml script to kick off tests, test options get passed slightly differently. The actual options the tests see and use remain the same as before, however when you invoke Ant you need to specify the options with a -D and a prefix that Ant uses and then strips off in XSLTestAntTask.

Default options (inputDir, loggingLevel, etc.) are now all stored in test.properties. Overall defaults are prefixed with qetest., which are used if no other type of test is specified. Each type of test (api, conf, perf, contrib, etc.) has it's own set of some prefixed options - namely api.inputDir, api.outputDir, api.goldDir and api.logFile, etc..

Users may override the defaults in one of two ways:

  • Create a my.test.properties file with any options you wish to use in the xml-xalan/test directory. This will override any options set in the test.properties or build.xml files. The format is the same as the test.properties file. A different name of this file may be specified using -Dlocal.properties=new.name.properties on the command line
  • Pass options on the command line. This is the same as passing options to java or your JDK, so you must use the -Dname=value format.

build conf -Dconf.category=axes -Dconf.flavor=trax.sax This runs the normal conf tests, but only on the axes subdir, and using the TraxSaxWrapper class.
build api -DtestClass=TransformStateTest -Dapi.loggingLevel=30 This runs the org.apache.qetest.xalanj2.TransformStateTest with a lower loggingLevel (so less is output). Note that testClass is one of the few properties that is not prefixed, since it is not passed on to the test itself, but is only used by the Ant script to load the test.

Since these tests are primarily to help developers test their changes to Xalan source code, we don't currently provide prebuilt builds of the test code. Most tests also require Xalan-J, even if you are testing a Xalan-C build.

To use the tests, you will need both a working build of Xalan-J as well as the sources for the tests themselves.

To download Xalan builds, see the: Xalan-J download page or the Xalan-C download page

To get the test sources, do the following:
Check out the xml-xalan\test repository directly from CVS (read-only access is available to all).

Since the test automation is written in Java, you must build it before running any tests. Like Xalan-J, we use Ant build.xml files as 'makefiles' to build the project. A copy of the Ant runtime files is provided in the xml-xalan/java/tools directory if you need them; you may also use your own copy of Ant if you have it installed. Unless specifically noted, all testing code should work either on Windows or UNIX systems; adjust .sh/.bat and path\separators/as needed. Note that paths in .properties files may always use forward / slashes since Ant's path handling will always do the proper thing.

This assumes you already have a version of Xalan-J in \builds\xml-xalan\java This may either be a distribution or a copy you pulled from CVS and built yourself.

Download the tests to \builds\xml-xalan\test.

cd \builds\xml-xalan\test
build jar This calls build.bat/.sh to find a copy of ant.jar and an xml parser (which Ant requires). It then calls Ant to run the 'jar' target in the default build.xml file. This will compile all the base test reporting libraries and framework, as well as the most common test drivers and API tests.

The default way to build and run the tests assumes you have both the xml-xalan/java and xml-xalan/test directories locally, as if you were a developer on xalan. See below for a simple alternate way to set your classpath using JARDIR. This allows QE/QA/test people to run the same set of tests quickly against different versions of the product.

Using JARDIR is no longer fully supported due to lack of interest. Those wishing to manage custom classpaths are welcome to submit patches to allow this in an automated fashion.

The default jar target builds all TestletDrivers and most of the tests. A few kinds of tests require separate targets to compile since they have extra dependencies. In particular, any XSLTC-specific API tests or TransformWrapper subclasses are compiled in a separate set of targets.

Users of automated IDE's that automatically compile all *.java files in the source tree will either have to use the Ant build.xml script or may have to manually compile certain files with the extra dependencies. Note that JUnit is only required for the special qetesttest directory, which is only used to test the qetest framework itself and is not needed to test Xalan.

Note that there are a few precompiled .class files in the test/java/src/ area. By default these are simply copied into the testxsl.jar for you. These are files that require extra dependencies to compile, and change infrequently, so as a convenience they're checked in to the repository as precompiled .class files as well as source.

Building the Javadocs for the tests is done by build.bat javadocs , and is best done under JDK 1.2.2 or higher - they will build with JDK 1.1.8, but not all the links will work properly.

Building these top-level documents in the xdocs directory can be done with build.bat docs and must be done under JDK 1.2.2 or higher, since the Xalan-related stylebook code that we use requires that.