Migration Guide for XTest 1.5

Abstract: This document describes a guide for migration from old monolithic version of XTest to a new modularized version of XTest (XTest 1.5). The scope of the document is focues on test developers who want to quickly migrate their test infrastructure to XTest 1.5 and higher.

Document History:

22 Feb 2004 : Martin Brehovsky, created

Contents:

1. Why to Migrate

2. Migrating build.xml Files

3. Migrating cfg-*.xml Files

4. Migrating build-*.xml Files

5. FAQ

1. Why to Migrate

2. Migrating build.xml Files

This section is focused on migrating the base test build file, which is usually stored in ${module_home}/test/build.xml file.  This file consists basically of two parts. In the first part, there are defined properties, which inform XTest about the module which is being tests, gives path to XTest, defines default test type and default attributes. The second part contains only targets used to compile/run/clean tests. 

To migrate the base build.xml file, you basically need to replace the second part of your file by the second part from this template (basically reaplace everything which starts by the comment "You should not change anything after this comment, unless you really know what you are doing").

3. Migrating cfg-*.xml Files

Now, when you have migrated the base test build file, you are ready to migrate the test configuration xml files, which described testbags and their related compilers/executors. This file hasn't changed much, just results processors cannot be longer configured by user, therefore all instances of <resultsprocessor> element and all 'resultsprocessor' attribute in <testbag> element should be deleted.

4. Migrating build-*.xml Files

The final task is to migrate the build files, which contain compilers and executors defined in the config files.

In the first step, delete all targets which server as result processors. They are no longer required.

In the second step. you should look at the way how classpath for test compilation and test execution is constructed. In the previous version of XTest you could use property 'xtest.source.location', which was used to determine whether the tests are running agains compiled sources, built jars or the whole IDE (the IDE mode was compulsory). This property was used to construct the classpath for compilation/execution by unfamous 'switch' and 'set_classpath' tasks, which led to unnecessary complexity of the build scripts. Because of that, XTest 1.5 completely abandon 'xtest.source.location' and you have to make sure your tests are compilable/executable against IDE, so you need to set classpath just once for compilation and once for execution (you can still use more complex solution if you want, but these solutions are just only for your conveninence and are not enforced by XTest in any way). In an ideal case, you just simply delete all obscure classpath settings and you set classpath directly in calls for compilation/execution (see details in the next parahraph).

In the third step, you need to rewrite the executors/compilers to use the new user tasks and call the appropriate plugins with compilers/executors. In he previous version, the compiler target looked something like this:

<target name="qa-functional-compiler" depends="set_classpath">
	<ant dir="." antfile="${xtest.module_harness.antfile}" target="buildtests">
            <property name="compile.srcdir" value="qa-functional/src"/>
	</ant>
</target>

In the above example you can see a simple 'qa-functional-compiler", which performed 'buildtests'' action. It depended on 'set_classpath' target, where the classpath for compilation was set. In XTest 1.5 you should rewrite this target to the following form:

<target name="unit-compiler">
     <buildTests srcDir="qa-functional/src" classpath="${my_classpath}"/>
</target>  

The buildTests tasks is supplied by XTest and you can specify many additional attributes and even subelements. For more details see the documentation for XTest user tasks.

Similary, the executor target looked something like this:

<target name="runidetest" depends="set_classpath">
   <ant dir="." antfile="${xtest.module_harness.antfile}" target="test">
       <property name="xtest.exectype" value="ide"/>
   </ant>
</target>

In this example you can see a simple executor, which runs the tests in NetBeans IDE. Similarly as with shown compiler, this target also depends on 'set_classpath' target, where the classpath for compilation is set. The rewrite for XTest 1.5 looks this way:

<target name="runidetest">        
   <executeTests  pluginName="ide" classpath="../mymodule.jar"/>
</target>

The executeTests task  is again supplied by XTest and you can specify many additional attributes/elements described in the documentation for XTest user tasks. The most notable attribute however is pluginName. By this attribute you basically specify which plugin runs the tests, therefore what product is used to run the tests. In the standard installation of XTest, there are two basic plugin available - jvm to run the tests in standard JVM and ide to run the tests in NetBeans IDE (including platform). To get more information about each plugin, please see plugins documentation.

One of the imporant step is also to rename/change properties which were originally supplied in compilers/executors to XTest to influence its behaviour. Because there were some issues with naming consistency in the previous version of XTest, we decided to rename/remove/change some of the properties, so now the naming is more consistent and comprihensible.

The following properties were changed:

xtest.jvm.args

xtest.ide.jvmargs

xtest.ide.reuse.userdir

tests.use.openide.classloader

xtest.ide.use.classloader

5. Frequently Asked Questions