<?xml version="1.0"?>

<!--
 * ========================================================================
 * 
 * Copyright 2001-2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * ========================================================================
-->

<document id="howto_httpunit">

  <properties>
    <title>HttpUnit Howto</title>
  </properties>

  <body>

    <section title="HttpUnit integration">

      <note>
        <strong>The HttpUnit integration is only available for Cactus v1.2 and
        later. It won't work with version 1.1 and earlier.</strong>
      </note>

      <p>
        Cactus test cases allow to assert the results of the returned server
        output stream in an <code>endXXX()</code> method (where <code>XXX</code>
        is the name of your test case).
      </p>
      <p>
        Cactus proposes 2 ways of writing your <code>endXXX()</code> methods,
      </p>
      <ul>
        <li>
          <strong>Method 1</strong>:  it allows you to do simple check on the
          returned stream like checking for returned cookies, HTTP headers and
          to do assertions on the returned content as a String,
        </li>
        <li>
          <strong>Method 2</strong>: it allows you to do complex and
          powerful assertions on the returned content. For example, you can
          get an HTML DOM view of your returned HTML page and check that a given
          named table has the correct number of columns, ....
        </li>
      </ul>
      <p>
        Method 2 is supported through the integration with
        <link href="http://httpunit.sourceforge.net">HttpUnit</link>, meaning
        you'll benefit from the full assertion power of HttpUnit in your
        <code>endXXX()</code> method. Method 1 is a class provided by Cactus.
      </p>
      <p>
        Depending on your need you can choose, on a per test case basis, the
        method you want to use.
      </p>

    </section>

    <section title="Usage">

      <p>
        The signature of an <code>endXXX()</code> method is always:
      </p>
<source><![CDATA[
public void endXXX(WebResponse theResponse)
{
[...]
}
]]></source>

      <p>
        The <code>WebResponse</code> object is passed by the Cactus framework
        to your <code>endXXX()</code> method. What changes between the 2
        methods described above is the class of the <code>WebResponse</code>
        object that is passed:
      </p>
      <ul>
        <li>
          <code>org.apache.cactus.WebResponse</code> for Method 1,
        </li>
        <li>
          <code>com.meterware.httpunit.WebResponse</code> for Method 2
          (HttpUnit)
        </li>
      </ul>

      <section title="Method 1: Cactus provided WebResponse object">

         <p>
           An example:
         </p>

<source><![CDATA[
public void endXXX(org.apache.cactus.WebResponse theResponse)
{
  // Get the returned cookies
  Hashtable cookies = theResponse.getCookies();

  // Get the returned content as a string
  String content = theResponse.getText();

  // Do some asserts
  assertEquals(content, "<html><body><h1>Hello world!</h1></body></html>");
[...]
}
]]></source>

        <note>
          For the complete list of all methods available on the
          <code>WebResponse</code> object, see the associated Javadoc.
        </note>

      </section>

      <section title="Method 2: HttpUnit provided WebResponse object">

         <p>
           An example:
         </p>

<source><![CDATA[
public void endXXX(com.meterware.httpunit.WebResponse theResponse)
{
  WebTable table = theResponse.getTables()[0];
  assertEquals("rows", 4, table.getRowCount());
  assertEquals("columns", 3, table.getColumnCount());
  assertEquals("links", 1, table.getTableCell(0, 2).getLinks().length);
[...]
}
]]></source>

        <note>
          For the complete list of all methods available on the
          HttpUnit <code>WebResponse</code> object, see the HttpUnit
          documentation.
        </note>

      </section>

    </section>

  </body>
</document>
