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

For more information, please explore the Attic.


If you want to quickly get a feeling of Cactus, there is a 20 minutes tutorial that take you through running your first Cactus test using Tomcat. It doesn't explain how Cactus works or any other details but let's you have something running quickly.

We suggest you take this quicky tutorial and then come back here and continue reading below. You would have had a first glimpse of Cactus in action and will be ready to understand the concepts behind it and its full power.

Installing Cactus

There is not really an installation of Cactus per see, as Cactus is not an application but a framework. However you do need to understand how it integrates in your working environment. In order to simplify this integration Cactus offers several integration modules. Thus, installing Cactus simply means picking an integration module and learning how to configure and use it.

System Requirements

In order to run Cactus tests you need to have the following software already installed on your system:

  • Java Virtual Machine A Java 1.2 or greater compatible virtual machine must be present. Note that all servlet engines require a JVM to run so if you are already using servlets you already have one installed.
  • Servlet/J2EE Engine A Servlet 2.x/J2EE 1.x compliant servlet engine for running your Cactus tests must be present.
You also need to have installed the development tools that you are integrating Cactus with. For example, if you plan to use the Ant integration, you must have Ant installed. If you plan to execute Cactus tests from an IDE, this IDE software has to be already installed, etc.

The Cactus files

At this point, you should have downloaded a Cactus distribution (for the J2EE API you intend to use) and unzipped it in a [cactus root] directory.

You'll find the following directories under [cactus root]:

  • doc/: contains Cactus web site and API javadocs.
  • lib/: contains Cactus jars and related external libraries.
  • samples/: contains sample applications showing how to write Cactus tests and how to automate their execution.
  • samples/ejb: contains a sample application showing how to test EJBs with Cactus.
  • samples/jetty: contains a sample application showing how to test Servlet with Cactus and Jetty (using the JettyTestSetup extension).
  • samples/servlet: contains a sample application showing how to test Servlet/JSPs/Taglibs with Cactus.
  • web/: contains the JSP redirector file which is only required if you're using the manual integration.
The jars making up Cactus are:
  • cactus.jar: the main jar, contains the framework classes. You can find this jar in [cactus root]/lib.
  • cactus-ant.jar: a jar which contains some custom Ant tasks to help integrate easily with Ant. This is only needed if you wish to use Ant for automating the execution of Cactus tests. For more information on how to integrate Cactus with Ant, see the Ant Howto tutorial. You also find this jar in [cactus root]/lib.
  • httpclient.jar: Cactus is relying on the Jakarta Commons HttpClient framework for Cookie handling.
  • junit.jar: Cactus extends JUnit and thus needs the JUnit jar.
  • aspectjrt.jar: Cactus uses AspectJ for performing several tasks (logging entries and exit of methods, checking configuration, etc).
  • commons-logging.jar: Cactus uses the Jakarta Commons Logging facade framework to provide seamless Cactus logging using any existing Logging framework (Log4j, LogKit, JDK 1.4 Logging, etc). It is also needed for Commons HttpClient.
  • servletapi.jar: Required for compiling the Servlet sample. Ideally we should be bundling the J2EE jar (which is required for compiling the EJB sample). However the Sun license does not allow us to redistribute it so you'll need to download it by yourself (see the Sample howto page.
  • httpunit.jar: Cactus uses the HttpUnit framework to perform complex assertions of returned responses. Cactus also bundles a default web response object but the HttpUnit one should be preffered for complex assertions.
  • nekohtml.jar: Required by HttpUnit.

What's next?

At this point you should understand what Cactus is and how it works. Pick the Cactus integration module that you wish to use in your development environment. Read up on how it works and how to use it. Then, you should read the TestCase Howto to understand how to write Cactus Test Cases. The last step is probably to put in practice what you've learned so far by running the Cactus Samples. Enjoy !