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

For more information, please explore the Attic.

Version 1.8

The cactus task is being significantly changed in version 1.8 of Cactus, and now Cactus uses Cargo project for all server-related manipulation. If you use Cactus version gt to 1.8 than you should follow this documentation.

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 also relies on the Cargo tasks to start/stop the server and to deploy the webapplication. Currently Cactus works with the latest release of Cargo - 0.9

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

  1. Invoke cargo task to deploy the cactified WAR/EAR into the target container,
  2. Invoke cargo task and if the container is not already started, start it. Otherwise, leave it running,
  3. Run the Cactus tests,
  4. Invoke the cargo tasks and check if the container was started by the cargo task the stop it. Otherwise, leave it running.
For a list of supported containers, you can check the corresponding version of cargo

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
cargo A list of cargo tasks that are supposed to manipulate the container. For a reference of the parameters that these cargo tasks can get, you can reference the Cargo site. Yes

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.

Examples

The following example demonstrates how to run a suite of Cactus tests against two containers (Tomcat 4 and Tomcat5). The cargo task in this case is configured with the zipurlinstaller, so the containers will be downloaded from the specified URL and then the execution will proceed. More on configuring the cargo task, you can look on the Cargo site.


<cactus warfile="${cactified.servlet.archive.name}"
printsummary="yes">
    <classpath>
        <path refid="cactus.classpath"/>
        <pathelement location="${build.dir}"/>
        <pathelement location="${ivy.lib.dir}/htmlunit-1.10.jar"/>
    </classpath>
    <containerset>
        <cargo containerId="tomcat5x" output="${logs.dir}/output.log" log="${logs.dir}/cargo.log">
            <zipUrlInstaller
              installUrl="${tomca5x.url}"
              installDir="${target.dir}/${tomcat.container.id}"/>
            <configuration>
                <property name="cargo.servlet.port" value="${cargo.servlet.port}"/>
                <property name="cargo.logging" value="${cargo.logging}"/>
                <deployable type="${cactus.sample.archive.type}" 
                  file="${cactified.servlet.archive.name}"/>
            </configuration>
        </cargo>
    
        <cargo containerId="tomcat4x" output="${logs.dir}/output.log" log="${logs.dir}/cargo.log">
            <zipUrlInstaller
              installUrl="$"{tomcat4x.url}
              installDir="${target.dir}/${tomcat.container.id}"/>
            <configuration>
                <property name="cargo.servlet.port" value="${cargo.servlet.port}"/>
                <property name="cargo.logging" value="${cargo.logging}"/>
                <deployable type="${cactus.sample.archive.type}" 
                  file="${cactified.servlet.archive.name}"/>
            </configuration>
        </cargo>
    </containerset>
    
    <sysproperty key="prop1" value="value1"/>
    <sysproperty key="prop2" value="value2"/>
    
    <formatter type="${cactus.formatter.type}"/>
    
    <batchtest todir="${reports.dir}">
      <fileset dir="${cactus.src.dir}">
        <include name="**/Test*.java"/>
      </fileset>
    </batchtest>
</cactus>