FilterTestCase Principles

Last update : August 31 2002
Doc for : v1.4.1

About
  • What is Cactus ?
  • News
  • Changes
  • Features/Status
  • Goals
  • Roadmap/Todo
  • Contributors
  • Contributing
  • Cactus Users
  • Tested on ...
  • License


  • Downloads
  • Downloads


  • Documentation
  • How it works ?
  • Getting Started
  • Mock vs Container
  • Javadocs
  • FAQ


  • Howto Guides
  • Classpath Howto
  • Config Howto
  • Migration Howto
  • TestCase Howto
  • Jsp Howto
  • Runner Howto
  • Security Howto
  • Ant Howto
  • HttpUnit Howto
  • Sample Howto
  • EJB Howto
  • IDE Howto
  • Tomcat Howto
  • JUnitEE Howto


  • Support
  • Bug database
  • Mailing list


  • Misc.
  • Why the name ?
  • Logo Challenge
  • Resources
  • Test Coverage
  • Stats


  • Developers
  • CVS
  • Coding Conventions
  • Build results
  • Release Checklist


  • When to use ?

    Your test case class should extend FilterTestCase whenever you are unit testing :

    • Servlet Filters,
    • Any java code that uses Filter API objects (FilterConfig, ...)

    Note As filters only exist in Servlet API 2.3, you must use the Cactus version for Servlet API 2.3 if you wish to write tests for them.

    Note Filter unit testing is only available in Cactus 1.2 and above.


    Provided Implicit Objects

    Cactus automatically initializes the implicit objects for you and they are made available to your setUp(), testXXX() and tearDown() methods as instance variables of the FilterTestCase class (and thus as instance variables of your test case class as it extends FilterTestCase).

    Note You may ask yourself how Cactus initializes these objects. The mechanism is described in the How it works guide.

    The provided implicit objects are :

    request

    See ServletTestCase request implicit object for documentation.


    response

    See ServletTestCase response implicit object for documentation.


    config

    Instance variable name   config  
    Class name   org.apache.cactus.server.FilterConfigWrapper , which inherits from javax.servlet.FilterConfig  

    Cactus wraps the original Filter Config for two reasons :

    • In order to provide additional methods. For example, it is possible to initialise filter parameters without setting them in web.xml, etc...,
    • So that it can return a wrapped Servlet Context instead of the original one. This is because the Servlet Context is used to perform forwards and includes and we need to pass to these methods the original request and response. As we have wrapped the request, we need to wrap the Servlet Context to pass the original request (and not the wrapped one).

    The config implicit object will contain all initialisation parameters defined in web.xml under the Filter Redirector filter definition.

    See the javadoc for the org.apache.cactus.server.FilterConfigWrapper class for all details. You should also look at the samples provided in the Cactus distribution.

    Additional methods

    Additional methods provided:

    • setInitParameter(): sets an initialisation parameter (as if it has been defined in the web.xml file),
    • setFilterName(): sets the Filter name that will be returned by getFilterName() (if not set, the Cactus Filter redirector name will be returned).


    filterChain

    Instance variable name   filterChain  
    Class name   javax.servlet.FilterChain  

    Note Cactus does not wrap the filter chain.



    Tips and Tricks

    Simulating the next fitler in chain

    As you are performing unit testing of your filter, you may wish to simulate the next filter in the filter chain so that you can decide, as part of your unit test, what this other filter returns to your filter under test. Here is how you could do that :

    public void testDoFilterOK() throws ServletException, IOException
    {
        SampleFilter filter = new SampleFilter();
        filter.init(config);
    [...]
    
        FilterChain mockFilterChain = new FilterChain() {
            public void doFilter(ServletRequest theRequest,
                ServletResponse theResponse) throws IOException, ServletException
            {
                PrintWriter writer = theResponse.getWriter();
                writer.print("<p>some content</p>");
                writer.close();
            }
            public void init(FilterConfig theConfig)
            {
            }
            public void destroy()
            {
            }
        };
    
        filter.doFilter(request, response, mockFilterChain);
    [...]
    }
    

    See the samples provided as part of the Cactus distribution.



    Sample

    This is a very basic sample intended to give you a flavour of Filter unit testing. Check the distribution samples for extensive examples. The filter we are testing here simply adds a header and a footer to the response. The header and footer texts are defined as a parameter defined in web.xml.

    public void testXXX() throws ServletException, IOException
    {
        SampleFilter filter = new SampleFilter();
        config.setInitParameter("header", "<h1>header</h1>");
        config.setInitParameter("footer", "<h1>footer</h1>");
        filter.init(config);
    
        FilterChain mockFilterChain = new FilterChain() {
            public void doFilter(ServletRequest theRequest,
                ServletResponse theResponse) throws IOException, ServletException
            {
                PrintWriter writer = theResponse.getWriter();
                writer.print("<p>some content</p>");
                writer.close();
            }
            public void init(FilterConfig theConfig)
            {
            }
            public void destroy()
            {
            }
        };
    
        filter.doFilter(request, response, mockFilterChain);
    }
    
    public void endXXX(WebResponse theResponse)
    {
        assertEquals("<h1>header</h1><p>some content</p><h1>footer</h1>",
            theResponse.getText());
    }
    



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