|
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
|
Tutorial for creating a Cactus Test Case |
This section explains how to write a test case, using Cactus.
Step 1 : Imports |
You need to include the following imports in your test class (this
is because Cactus uses JUnit as the client side application for
calling the tests) :
import org.apache.commons.cactus.*;
import org.apache.commons.cactus.util.*;
import junit.framework.*;
|
|
Step 2 : Extend ServletTestCase or JspTestCase |
Instead of extending TestCase as you would do if you were writing
a JUnit test class, you need to extend ServletTestCase
or JspTestCase . You would extend
ServletTestCase to unit test servlet methods and
JspTestCase to unit test simple custom JSP tags.
public class TestSampleServlet extends ServletTestCase
{
|
or
public class TestSampleTag extends JspTestCase
{
|
|
Step 3 : Standard JUnit methods |
Define the following standard JUnit methods :
-
A constructor with a single parameter (it is the test name),
-
A
main() method in which you start a JUnit test
runner if you want your test to be executable,
-
A
suite() method to list the tests that should
be executed by your test class
public TestSampleServlet(String theName)
{
super(theName);
}
public static void main(String[] theArgs)
{
junit.ui.TestRunner.main(new String[] {TestSampleServlet.class.getName()});
}
public static Test suite()
{
return new TestSuite(TestSampleServlet.class);
}
|
|
Step 4 : setUp() and tearDown() methods |
As in JUnit, you can define a setUp() and a
tearDown() methods. They are executed respectively before
and after each test case. However, whereas in JUnit they are executed
on the client side, in Cactus they are executed on the server side.
It means that you will be able to access the Cactus implicit object
(see step 6 below) within them. In other words, you'll be able to do
things such as putting a value in the HTTP Session prior to calling
the test cases, etc.
|
Step 5 : Signature of the test methods |
This is where it is a bit different from JUnit ! For each test
XXX that you want to implement you can define 3 methods
(2 being optionals) :
-
void beginXXX(ServletTestRequest) : This method
is optional and should be used to set up some HTTP-request related
parameters before your test case is executed. Whereas the setUp()
method is global for all test cases, this method is only executed
before the test case of the same name (i.e. testXXX() ).
This method is executed on the client side.
The ServletTestRequest object passed to the beginXXX()
method contains all the methods needed to set up the HTTP parameters.
See the javadoc for
ServletTestRequest
for detailed information on the API. Here is a short summary :
ServletTestRequest
|
addCookie(String, String)
|
Adds a cookie to the list of cookies that will be available
in testXXX() , setUp() and tearDown()
using the HttpServletRequest.getCookies() API
|
addHeader(String, String)
|
Adds a HTTP header to the list of headers that will be available
in testXXX() , setUp()
and tearDown() using the HttpServletRequest.getHeader()
API.
|
addParameter(String, String)
|
Adds a HTTP parameter to the list of parameters that will be
available in testXXX() , setUp() and
tearDown() using the HttpServletRequest.getParameter()
API.
|
setAutomaticSession(boolean)
|
If false , no HTTP session
wil be automatically created (i.e. the implicit session
object will be null . See section 6 below for implicit
objects). By default the value is true .
|
setURL(String, String, String, String, String)
|
If used, simulates a URL. From the point of view of your
test case, it is as if your servlet were called by this URL
instead of the Redirector servlet URL (see
configuration).
The parameters are : server name (+ port number), context path,
servlet path, path info, query string.
|
-
void testXXX() : This is the test method. In it,
you will instantiate the class to test, call the method method
and write the checking to verify that the test was successful
using JUnit asserts(..) , assertEquals(...) ,
fail(...) , etc methods.
-
void endXXX(HttpURLConnection) : This method is
optional and should be used to test HTTP-response related values
that might have been set by the tested method. For example, you
might want to verify that a cookie was sent back to the client,
that a HTTP header has been correctly set, the returned servlet
output stream, etc. This method is executed on the client side.
Cactus provides helper methods in the
org.apache.commons.cactus.util
package (download the
Cactus sample application
for example on how to use them) :
-
AssertUtils.getCookies() : retrieves all cookies sent
back from the server side,
-
AssertUtils.getResponseAsString() which returns the
server output stream as a string that you can assert.
-
AssertUtils.getResponseAsStringArray() which returns
the server output stream as an array of strings (each line
terminated by a line terminator is a string in the array) that
you can assert.
The HttpURLConnection object passed to this method
is the standard java.net.HttpURLConnection . Thus you
have access to all the standard API (getHeaderField(), ... )
|
Step 6 : Implicit objects |
Depending on whether your test class extended
ServletTestCase or JspTestCase you have
access to different server-side objects.
Implicit objects provided by ServletTestCase |
The following server-side objects are made available to your testXXX(),
setUp() and tearDown() methods :
-
request : This is the HttpServletRequest
object. Actually, it is a modified HttpServletRequest
that overrides some of the original HttpServletRequest
methods in order to return the parts of the simulated URL that
may have been set up in the beginXXX() method using
the ServletTestRequest.setURL() method. The overridden
methods are :
-
HttpServletRequest.getServerName() ,
-
HttpServletRequest.getServerPort() ,
-
HttpServletRequest.getRequestURI() ,
-
HttpServletRequest.getContextPath() ,
-
HttpServletRequest.getServletPath() ,
-
HttpServletRequest.getQueryString() ,
-
HttpServletRequest.getPathInfo()
-
response : This is the HttpServletResponse
object that will be used to return the HTTP response to the client.
-
session : This is the HttpSession
object. It is created only if the automatic session creation is
set to true (it is set using the ServletTestRequest.setAutomaticSession(boolean) ),
which is the default. If you have set it to false
then the session's value is null .
-
config : This is a ServletConfig object.
It is the configuration that comes from the Redirector Servlet. Thus
if you want to test a method that needs a ServletConfig
object to retrieve some static configuration values, you should
define these values in the web.xml mapping section for
the Redirector Servlet.
|
Implicit objects provided by JspTestCase |
All the implicit objects provided by ServletTestCase
are also provided by JspTestCase . In addition, the
following implicit objects are also provided :
-
pageContext : This is a PageContext
object. It is the page context implicit object available in any
JSP page.
-
out : This is a JspWriter object. It is
the out implicit object available in any JSP page. You should
this object to write data in the output stream.
|
Additional methods provided by some implicit objects |
Implicit objects are actually subclasses of standard servlet
objects and provides additional methods to help unit test your code :
-
Using the
config implicit object :
-
setInitParameter(String, String) : sets a
parameter as if it were set in the web.xml file
using an init-param tag,
-
setServletName(String) : sets the servlet name.
This is the value that is returned by a call to
getServletName()
|
|
Step 7 : Writing the test methods |
You write your test methods the same way as you do in JUnit, instanciating
the class to test, calling it's method to test and doing asserts
to verify the results. The only difference from JUnit is that you
can use the implicit objects defined in step 6.
|
Step 8 : Running the tests |
Cactus tests are JUnit test. As such they are run the same way JUnit
tests are run, i.e. by starting a JUnit Test Runner (either the
text runner or the graphical awt or swing test runners). This is the
beauty of it ... any tool that will run a JUnit test will also run
a Cactus test ! (i.e all JUnit IDE plugins will work for Cactus tests).
 |
An example on how to start the JUnit text test runner using Ant is
provided with the Cactus sample application which is part of the
distribution and a documentation example is also available in the
Servlet Engine integration tutorial
(step 4).
|
|
|
|
|