Getting Started

Last update : September 25 2001

About
  • What is Cactus ?
  • Features/Status
  • Goals
  • News/Changes
  • Roadmap/Todo
  • Contributors
  • Contributing
  • License
  • Feedback


  • Downloads
  • Downloads


  • Documentation
  • How it works ?
  • Getting Started
  • Mock vs Container
  • API Reference


  • Howto Guides
  • Config Howto
  • TestCase Howto
  • Ant Howto
  • HttpUnit Howto
  • Sample Howto
  • EJB Howto
  • IDE Howto


  • Support
  • Bug database
  • Mailing list
  • FAQ


  • Misc.
  • Why the name ?
  • Resources


  • Developers
  • CVS
  • Coding Conventions


  • 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. Thus, installing Cactus simply means to understand what jars need to be put where and what are the configuration files you need to have and edit. This is discussed below.

    There are 2 kinds of environments in which you may want to use Cactus, mainly :

    • within your IDE,
    • from the command line, using Ant

    Note Usually, these 2 environments are complementary. A good strategy is to use an IDE to increase day to day productivity, run quickly the Cactus tests in the IDE and use Ant to perform the (continuous) builds (including running the Cactus tests).


    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 Engine A Servlet 2.x compliant servlet engine (where x >= 2.2) for running your Cactus tests must be present.
    • Ant (optional) Ant is only needed if you are working from the command line or if you wish to automate the execution of tests. If you wish to use Ant, make sure that you read the Ant Howto after you finish reading this introductory guide.

    The Cactus files

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

    The Cactus jars 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.

    The Cactus configuration files are described in the Configuration Howto tutorial.


    The Classpath

    You must understand that your Cactus tests are started by a JUnit Test Runner (in the client JVM) and that the Cactus TestCase that you have extended will connect to the Cactus Redirector (in the server JVM), where your testXXX() methods will be executed. See How it works to understand the mechanism.

    Note It is very important that you understand what files you need to put in the client and server classpaths, as 99% of Cactus errors come from an incorrect classpath !

    Classpaths

    Client side classpath

    The Cactus tests are started by running a JUnit Test Runner (For explanations on how JUnit works see the JUnit web site). As pictured in figure 1, you need to have the following jars and classes in your client side classpath :

    • junit.jar : obviously this is needed for the JUnit Test Runner and because the Cactus XXXTestCase classes extend the JUnit org.junit.framework.TestCase class.
    • cactus.jar : well, this is the Cactus jar containing all Cactus classes,
    • your test classes : these are your test classes that extend the Cactus XXXTestCase classes,
    • servlet.jar : these are the Servlet API interfaces (for the Servlet API you are using). This is needed because your test case extend one or several of XXXTestCase which use class variables that are servlet objects (HttpSevletRequest, PageContext, ...). You can get this jar either from your servlet engine or from the Servlet download page of the Sun web site. It is also included in the j2ee.jar, available either from your servlet engine or from the J2EE download page of the Sun web site (but it contains a lot of other API that you probably don't need).
    • log4j.jar (optional) : only needed when you want Cactus to output debugging information on the client side.
    • httpunit.jar, Tidy.jar and xerces.jar (optional) : only needed if you wish to use HttpUnit in your endXXX() methods (see the HttpUnit Howto tutorial). The 3 jars mentioned above are part of the HttpUnit distribution.

    Note If you have the habit of declaring class variables for the classes to test (as opposed to declaring them within the testXXX() method), you'll also need to put your classes under test in the client side classpath.

    In addition to the above mentionned jars and classes, you will also need to put the cactus.properties configuration file in your classpath (because it is a java properties file). This file is described in the Config Howto tutorial).

    Note In theory you would also need to put the log_client.properties properties file in your classpath. However a default one is provided in cactus.jar (and thus is on the classpath as cactus.jar is itself in the classpath !).


    Server side classpath

    The server side part is a webapp. It can be packaged as a .war file or as expanded war. It should have the following structure, which will ensure that the classpath is correct :

    • WEB-INF/lib/cactus.jar : the Cactus main jar,
    • WEB-INF/lib/junit.jar : this is needed because the Cactus XXXTestCase extends the JUnit org.junit.framework.TestCase class.
    • WEB-INF/classes/<your test classes> : obviously as their testXXX() methods will get executed in the container.
    • WEB-INF/classes/<your classes under test> : will be called by your test classes.
    • WEB-INF/lib/log4j.jar (optional) : only needed when you want Cactus to output debugging information on the server side.

    Note In theory you would also need to put the log_server.properties configuration file in your classpath. However a default one is provided in cactus.jar (and thus is on the classpath as cactus.jar is itself in the classpath !).



    What's next ?

    You should now read the Configuration Howto tutorial. Then, read the TestCase Howto, which explains how to write a Cactus Test Case. Then, you could try to install the Cactus Sample by following the Samples Howto tutorial.




    Copyright © 2000-2001 The Apache Software Foundation. All Rights Reserved.