|
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
 |
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.
 |
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 !
|

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.
 |
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).
 |
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.
 |
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.
|
|
|