Installing Cactus

Last update : June 18 2001

Home
  • Jakarta Commons


  • About
  • News
  • Features
  • Goals
  • Changes
  • Todo
  • Contributors
  • Contributing
  • License


  • Downloads
  • Downloads


  • Design
  • Architecture
  • Mock vs Container


  • User Guides
  • Installation
  • Installing Ant
  • Installing Sample
  • Configuration
  • Writing Test Case
  • Servlet Sample
  • Ant integration
  • Servlet Engines
  • API Reference


  • Support
  • CVS
  • Bug database
  • Mailing lists
  • FAQ


  • Misc.
  • Resources


  • Forewords

    You have 2 options for installing Cactus :

    • Integrate Cactus in your existing developement environment and build process. This is what I call the "manual" installation because you'll have to understand how Cactus works,
    • Use the Cactus Sample as a starting point. The Cactus Sample application is more than just an example of how to use Cactus. It is a methodology for using Cactus. This methodology is described in the Ant integration and in the Servlet engine integration tutorials. The Cactus Sample is the implementation of this methodology.

    The steps below will explain how to "manually" install Cactus in your developement environment. For explanations on how to install the Cactus Sample, go here.


    System Requirements

    In order to use Cactus for unit-testing 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. Sample Ant scripts are even provided for the most common ones (see the features list).
    • Ant (optional) Ant is needed only if you wish to either run the Cactus Sample application or if you wish to use Ant as your build system for running and automating your unit tests. See the Ant installation tutorial.

    Note Even if you already have Ant installed, make sure you read the Ant installation section because there are some setup actions that you still need to perform.


    Installing Cactus

    The steps below show how to set up an environment for executing servlet unit tests. However, look at the Cactus Sample sources for an already set up environment that uses Ant to automate the running of unit tests.

    Step 1 : Installation of Cactus in your application to test

    Cactus works by calling a Redirector (either Servlet Redirector or JSP Redirector, both part of Cactus) that you need to put where both the server-side code that you need to test and your test code are located. In other words, you need to do the following :

    1. Put the commons-cactus.jar file in the WEB-INF/lib directory of the webapp that you are testing (If your servlet engine does not support web applications, just make sure that it is in the CLASSPATH of your servlet engine).
    2. Modify your web.xml file to include a mapping for the Redirector Servlet (If your servlet engine does not support web applications, you won't have any web.xml file. You'll need to edit your servlet engine configuration file and find out how to map a URL to a Servlet). This mapping contains :
      • the name of the Redirector Servlet class,
      • the URI that will be used to call the Redirector Servlet. This needs to match the URL specified in the cactus.properties configuration file (see configuration),
      • configuration data that can be retrieved using the config implicit object.
    3. Modify your web.xml file to include a mapping for the Redirector JSP. This mapping contains :
      • the name of the Redirector JSP page,
      • the URI that will be used to call the Redirector JSP. This needs to match the URL specified in the cactus.properties configuration file (see configuration).
      • configuration data that can be retrieved using the config implicit object.
    4. Copy the Cactus Redirector JSP file called redirector.jsp in the document root of your test webapp.

    Note The steps 3 and 4 above are only necessary if you wish to use the Redirector JSP for your tests and thus have access to the pageContext and out implicit objects (for testing custom tag libraries for example).

    For example, if you have the following configuration :

    • Your webapp is called "mywebapp"
    • The URLs specified in your cactus.properties are "http://localhost:8080/mywebapp/ServletRedirector" for the cactus.servletRedirectorURL property and "http://localhost:8080/mywebapp/JspRedirector" for the cactus.jspRedirectorURL property
    • The Cactus Redirector JSP file redirector.jsp is put in a subdirectory named test/ in your webapp document root.

    then your web.xml file should look like :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    
    <!DOCTYPE web-app
        PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
        "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">
    
    <web-app>
    
        <servlet>
            <servlet-name>ServletRedirector</servlet-name>
            <servlet-class>org.apache.commons.cactus.server.ServletTestRedirector</servlet-class>
            <init-param>
              <param-name>param1</param-name>
              <param-value>value1 used for testing</param-value>
            </init-param>
        </servlet>
    
        <servlet>
            <servlet-name>JspRedirector</servlet-name>
            <jsp-file>/test/redirector.jsp</jsp-file>
            <init-param>
              <param-name>param1</param-name>
              <param-value>value1 used for testing</param-value>
            </init-param>
        </servlet>
    
        <servlet-mapping>
            <servlet-name>ServletRedirector</servlet-name>
            <url-pattern>/ServletRedirector</url-pattern>
        </servlet-mapping>
    
        <servlet-mapping>
            <servlet-name>JspRedirector</servlet-name>
            <url-pattern>/JspRedirector</url-pattern>
        </servlet-mapping>
    
    </web-app>
    

    Step 2 : Installation of your test code

    You also need to put the test classes that you have written (see the using section) on the server side, along with the code to test. Put these classes in your WEB-INF/classes or WEB-INF/lib (If your servlet engine does not support web applications, just make sure that it is in the CLASSPATH of your servlet engine).


    Step 3 : The server side CLASSPATH

    Here is the list of files that need to be in your server CLASSPATH :

    • the classes under test. These would normally be put under your webapp WEB-INF/classes directory,
    • the test classes. These would normally be put under your webapp WEB-INF/classes directory,
    • the cactus jar (commons-cactus.jar). It should normally be put under your webapp WEB-INF/lib directory. However if you use Cactus to test several webapps you might want to factor it out by putting it in the server's global CLASSPATH,
    • the JUnit jar (junit.jar). It should normally be put under your webapp WEB-INF/lib directory. However if you use it for several other webapps you might want to factor it out by putting it in the server's global CLASSPATH,

    Step 4 : Client-side installation with JUnit

    A Cactus suite of tests is started using JUnit test runners (see the using section). You need to put the following files in your client-side CLASSPATH :

    • The JUnit jar file,
    • The Cactus jar : commons-cactus.jar,
    • The Cactus configuration file cactus.properties (see the configuration page
    • Your test classes. This is needed because the beginXXX() and endXXX() methods are executed on the client side (see the using section for explanations on how to write tests using Cactus and see the architecture section for an explanation on how Cactus works)

    Step 5 : Configure Cactus

    You need to configure Cactus before using it the first time.





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