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:
-
Deploy the cactified WAR/EAR into the target container,
-
If the container is not already started, start it. Otherwise, leave
it running,
-
Run the Cactus tests,
-
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>
|