2011/08/05 - Jakarta Cactus has been retired.

For more information, please explore the Attic.

Cactus Task

The task cactus is an extension of the junit task that is included in Ant as an optional task. cactus extends junit to enable in-container tests. It features built-in support for a variety of containers, but also allows testing in custom containers.

Here are the different steps peformed automatically by the cactus task:

  1. Deploy the cactified WAR/EAR into the target container,
  2. If the container is not already started, start it. Otherwise, leave it running,
  3. Run the Cactus tests,
  4. If the container was started by the cactus task the stop it. Otherwise, leave it running.
Currently the following containers are supported out of the box: In addition if your favorite container is not in the above list, you can use the Generic container.

Parameters

As this task is an extension of the junit task, it also supports all attributes that the junit task supports. In addition, the following parameters are supported:
Name Description Required
warfile The web application archive that should be tested. The archive must already contain everything needed for running Cactus tests (it must be cactified). Yes, unless the earfile attribute is specified
earfile The enterprise application archive that should be tested. The archive must contain a web module that already contains everything needed for running Cactus tests (it must be cactified). Yes, unless the warfile attribute is specified

Nested Elements

As this task is an extension of the junit task, it also supports all the nested elements supported by the junit task. In addition, the following nested elements are supported:

cactusproperty

The cactusproperty element lets you specify the name of a property file. All the properties specified in this file will be read and set as System properties.

Parameters

The cactusproperty element supports the following parameters:
Name Description Required
server Specifies whether the properties should be added in the Cactus server side JVM ("true") or the Cactus client side JVM ("false"). Yes
Example (used for enabling Cactus logging):
<!-- Configure the cactus task for logging -->
<cactusproperty server="false"
    propertiesFile="${target.dir}/logging_client.properties"/>
<cactusproperty server="true"
    propertiesFile="${target.dir}/logging_server.properties"/>

containerset

The containerset element lets you specify which containers the tests should run against. Every element nested inside this element corresponds to a container. See below for a list of container elements supported in this element.

Parameters

The containerset element supports the following parameters:
Name Description Required
timeout Specifies the timeout in milliseconds after which starting up a container should be given up. If the timeout is reached before the container starts responding with a successful HTTP status code, the build will fail. No, default is 3 minutes
proxyport By specifying this attribute it is possible to insert some application that acts as a local TCP/IP proxy between the test runner and the actual containers. Most importantly, that includes applications that record and display the HTTP transactions, which can be helpful in tracking down tricky problems. No

containerclasspath

The optional containerclasspath element lets you specify additional jars that will be added to the container classpaths that are used to start/stop the containers. This is in addition to the container jars which are automatically added by the <cactus> task. The containerclasspath element behaves exactly the same as the Ant classpath element. In most cases you will not need to use this element.

Supported Containers

All elements nested in the containerset element represent specific containers. Specific container elements provide attributes and nested elements as appropriate.

Common Parameters

Here is a list of parameters that are common to all containers.
Name Description Required
protocol Protocol to use for communication, one of http or https. Note that https will only work, if a.) JSSE is installed b.) the proper certificates are installed. No, default is http
server Host name or ip of the machine running the server. Note, that the built in deployment support will not work for remote hosts. No, default is localhost
port The TCP port that the container should listen to No, default is 8080

generic

The generic container supports custom containers by allowing you to specify targets to be called, or tasks to executed, in order to start up and shut down the container. Note that the attributes of the <cactus> and <containerset> elements are currently not used by the <generic> element.

Parameters

Name Description Required
name A name for the container that is displayed when the tests are run. No
port The TCP port that the container should listen to No, default is 8080
startuptarget The name of a target that should be called to perform the starting up of the container. Yes, unless there's a nested startup element
shutdowntarget The name of a target that should be called to perform the shutting down of the container. Yes, unless there's a nested shutdown element
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No

Nested Elements

The generic container supports the following nested elements:

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

startup

A single startup element can be nested inside a generic element. Using this element, you can implement the startup of the container, either by specifying a target name in the target attribute, or by directly embedding the required Ant tasks inside the startup element.

shutdown

A single shutdown element can be nested inside a generic element. Using this element, you can implement the shutdown of the container, either by specifying a target name in the target attribute, or by directly embedding the required Ant tasks inside the shutdown element.

jboss3x

The nested element jboss3x allows running the tests against the JBoss 3.x application server.

Parameters

Name Description Required
dir The installation directory of the JBoss 3.x server Yes
config The name of the JBoss server configuration to use. The files in this server configuration will be copied to the tmp directory used to start the container. No, the default is default
port The TCP port that will be used to poll the server to verify if it is running. Note that this port value is not used to tell JBoss on what port it should listen to, as is the case for the other containers (this may be implemented in the future). No, default is 8080
jndiport The JNDI server port on which the JBoss server has been started. This attribute is only used for shutting down JBoss and should only be used if you are running JBoss on a custom JNDI port. No, default is 1099
tmpdir The directory to which the container will be installed for the tests. No (by default the [JBOSS_HOME]/server/cactus temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The jboss3x container supports the following nested elements:

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

orion1x

The nested element orion1x allows running the tests against the Orion Application Server 1.x.

Parameters

Name Description Required
dir The installation directory of the Orion 1.x server Yes
port The TCP port that the container should listen to No, default is 8080
tmpdir The directory to which the container will be installed for the tests. No (by default the system temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The orion1x container supports the following nested elements:

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

orion2x

The nested element orion1x allows running the tests against the Orion Application Server 2.x.

Parameters

Name Description Required
dir The installation directory of the Orion 2.x server Yes
port The TCP port that the container should listen to No, default is 8080
tmpdir The directory to which the container will be installed for the tests. No (by default the system temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The orion2x container supports the following nested elements:

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

resin2x

The nested element resin2x allows running the tests against the Resin Server 2.x.

Parameters

Name Description Required
dir The installation directory of the Resin 2.x server Yes
resinconf The configuration file to use instead of the default one No
port The TCP port that the container should listen to No, default is 8080
tmpdir The directory to which the container will be installed for the tests. No (by default the system temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The resin2x container supports the following nested elements:

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

resin3x

The nested element resin3x allows running the tests against the Resin Server 3.x.

Parameters

Name Description Required
dir The installation directory of the Resin 3.x server Yes
resinconf The configuration file to use instead of the default one No
port The TCP port that the container should listen to No, default is 8080
tmpdir The directory to which the container will be installed for the tests. No (by default the system temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The resin3x container supports the following nested elements:

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

tomcat3x

The nested element tomcat3x allows running the tests against the Apache Tomcat 3.x servlet container.

Parameters

Name Description Required
dir The installation directory of the Tomcat 3.x server Yes
serverxml The server configuration file to use instead of the default one No
port The TCP port that the container should listen to No, default is 8080
tmpdir The directory to which the container will be installed for the tests. No (by default the system temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The tomcat3x container supports the following nested elements:

conf

An Ant Fileset that can be used to specify the set of files that should be placed into the conf directory of the installation directory. This fileset should not include the server.xml file (it will be excluded if you add it) as you must use the serverxml attribute to specify a custom version of it.

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

tomcat4x

The nested element tomcat4x allows running the tests against the Apache Tomcat 4.x servlet container.

Parameters

Name Description Required
dir The installation directory of the Tomcat 4.x server Yes
serverxml The server configuration file to use instead of the default one No
contextxml An optional context xml file to use. Any file specified here will be copied into the webapps/ directory. No
port The TCP port that the container should listen to No, default is 8080
tmpdir The directory to which the container will be installed for the tests. No (by default the system temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The tomcat4x container supports the following nested elements:

conf

An Ant Fileset that can be used to specify the set of files that should be placed into the conf directory of the installation directory. This fileset should not include the server.xml file (it will be excluded if you add it) as you must use the serverxml attribute to specify a custom version of it.

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

tomcat5x

The nested element tomcat5x allows running the tests against the Apache Tomcat 5.x servlet container.

Note: For Tomcat 5.x, there is no contextxml attribute as it is not required. Tomcat 5.x requires the context file to be put under the conf/ directory (see the context documentation page). Thus you'll simply need to use the nested <conf> element. Alternatively you should be able to also put your context file in META-INF/context.xml.

Parameters

Name Description Required
dir The installation directory of the Tomcat 5.x server Yes
serverxml The server configuration file to use instead of the default one No
port The TCP port that the container should listen to No, default is 8080
tmpdir The directory to which the container will be installed for the tests. No (by default the system temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The tomcat5x container supports the following nested elements:

conf

An Ant Fileset that can be used to specify the set of files that should be placed into the conf directory of the installation directory. This fileset should not include the server.xml file (it will be excluded if you add it) as you must use the serverxml attribute to specify a custom version of it.

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

weblogic7x

The nested element weblogic7x allows running the tests against the WebLogic 7.x J2EE container.

Parameters

Name Description Required
dir The installation directory of WebLogic 7.x. Note that this should not be the the bea home directory. For example: c:\bea\weblogic700. Yes
beahome The bea home directory. By default Cactus tries to guess the bea home directory by taking the parent directory of the dir directory (i.e. where WebLogic 7.x is installed). You only need to use the beahome if you have put your bea home directory somewhere else. No, defaults to the parent directory of dir
configXml The Weblogic config.xml configuration file to use instead of the default one. No
port The TCP port that the container should listen to No, default is 8080
tmpdir The directory to which the container will be installed for the tests. No (by default the system temporary directory is used)
output Name of a file to write the output of the container to. If not specified, the standard output will be used No
append Whether output should be appended to or overwrite an existing file. No, default is false
if Tests will only be run in the container if a property of the given name exists in the current project No
unless Tests will only be run in the container if a property of the given name doesn't exist in the current project No
jvmArgs Arguments to be passed to the JVM running the container (for instance, -Xms256m -Xmx800m) No

Nested Elements

The tomcat4x container supports the following nested elements:

conf

A fileset that can be used to specify the set of files that should be placed into the conf directory of the installation directory. This fileset should not include the serverxml file.

exclude

Multiple exclude elements can be used as in standard Ant PatternSets or FileSets to exclude specific tests from running in the container.

Examples

The following example demonstrates how to run a suite of Cactus tests against three contains with builtin support (JBoss 3, Resin 2 and Tomcat 4).

<cactus warfile="${test.dir}/test.war"
    printsummary="yes" failureproperty="tests.failed">
  <classpath>
    <path refid="cactus.classpath"/>
    <pathelement location="${build.classes.dir}"/>
    <pathelement location="${test.classes.dir}"/>
  </classpath>
  <containerset>
    <jboss2x dir="${jboss3x.home}" config="default"
        todir="${test.reports.dir}/jboss3x"/>
    <resin2x dir="${resin2x.home}" port="8080"
        todir="${test.reports.dir}/resin2x"/>
    <tomcat4x dir="${tomcat4x.home}" port="8080"
        todir="${test.reports.dir}/tomcat4x"/>
  </containerset>
  <formatter type="xml"/>
  <batchtest>
    <fileset dir="${src.test.dir}">
      <include name="**/Test*.java"/>
      <exclude name="**/TestAll.java"/>
    </fileset>
  </batchtest>
</cactus>

The next example shows the use of the generic container element for starting/stopping a custom container. You need to define the two targets mycontainer.start and mycontainer.stop, so that the container is started up (on port 8080) before the tests are run, and shut down after the tests completed. How these targets are implemented is highly dependant on the container. Most likely you'll need to copy some files and use the <java> task to invoke a container-provided Java class that can start/stop the container.

<cactus warfile="${test.dir}/test.war"
    printsummary="yes" failureproperty="tests.failed">
  <classpath>
    <path refid="cactus.runtime.classpath"/>
    <pathelement location="${build.classes.dir}"/>
    <pathelement location="${test.classes.dir}"/>
  </classpath>
  <containerset>
    <generic name="My Container" port="8080">
      <startup target="mycontainer.start"/>
      <shutdown target="mycontainer.stop"/>
    </generic>
  </containerset>
  <formatter type="xml"/>
  <batchtest>
    <fileset dir="${src.test.dir}">
      <include name="**/Test*.java"/>
      <exclude name="**/TestAll.java"/>
    </fileset>
  </batchtest>
</cactus>