<?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_junitee">

  <properties>
    <title>JUnitEE Howto</title>
  </properties>

  <body>

    <section title="JUnitEE, a TestRunner inside the Container">

      <note>
        Since Version 1.4 Cactus contains a new Servlet Test Runner that
        enables the same features than the JUnitEE was providing, but in an
        even easier way. Please check the
        <link href="site:howto_runner">TestRunner Howto</link> tutorial.
      </note>

      <p>
        You can use the
        <link href="ext:junitee">JUnitEE</link> user
        interface to run your all your tests inside the Container. JUnitEE is
        a JUnit TestRunner that has been written as a servlet with the user
        interface in HTML format.
      </p>

      <p>
        You cannot achieve all features of Cactus using JUnitEE as
        part of them depend on being executed on the client side.
        Executing JUnitEE from ANT commands will probably not be possible.
        Some benefits however of JUnitEE are:
      </p>

      <ul>
        <li>
          <strong>All class files are in one place</strong>:  Install all your
          TestCase class-files only in your container classpath. Both
          TestCases derived from
          <code>junit.framework.TestCase</code> and from
          <code>org.apache.cactus.JspTestCase</code>
          will be located in the same place and only once.
        </li>
        <li>
          <strong>Run all TestCases in the container</strong>: You can mix
          both types of TestCases mentioned above in your test. All tests are
          executed inside the Container. You can use testcases derived from
          <code>junit.framework.TestCase</code> to test methods that do not
          require the http objects such as the
          <code>HttpServletRequest</code> or
          <code>HttpServletResponse</code> objects.
        </li>
      </ul>

      <p>
        Using JUnitEE is (relatively) simple. Assuming you have a container
        such as Weblogic, Tomcat or Orion functioning and you know how to
        configure Servlets and adding libraries to the Containers classpath and
        you are familiar with the basics of Cactus then the rest is easy.
      </p>

      <ul>
        <li>
          One good reason to use JUnitEE would be when you want to try Cactus
          quickly and are not concerned with automatic unit testing.
      </li>
        <li>
          Usage of standard JUnit testrunner (textui,swingui, ...) will not be
          possible if cactus is configured this way and thus the ant junit task
          cannot be used to automate the test.
        </li>
      </ul>

    </section>

    <section title="How to install JUnitEE">

      <p>
        Download the <link href="ext:junitee">JUnitEE</link>
        zip-file. Add a reference to <code>junitee.jar</code> to your Container
        classpath. Add also references to
        <code>junit.jar</code>,
        <code>httpunit.jar</code>
        <code>cactus.jar</code> and
        <code>aspectjrt.jar</code> if you have not
        already done that.
      </p>

      <note>
        add
        <code>junitee.jar</code> in the same way as cactus.jar is added.
      </note>

      <p>
        Configure TestServlet in your Container. You may use the example servlet
        <code>org.infohazard.servlet.TestServlet</code> that
        comes with JUnitEE. Check JUnitEE documentation. TestServlet extends
        <code>junit.htmlui.TestServletBase</code> that executes
        <code>junit.htmlui.TestRunner</code>
        i.e. the JUnitEE interface.
      </p>

    </section>

    <section title="Executing the tests with JUnitEE">
      <p>
        You request the tests from an html-page in your container. You can
        write the name of your testclasses according to the examples with
        JUnitEE as:
      </p>

      <ul>
        <li>
          a commandstring parameter such as "
          <code>/TestServlet?suite=fi.iki.kaila.MyTests&amp;list=yes</code>"
        </li>
        <li>
          as input using
          <code>&lt;input type="text" name="suite" size=60 /&gt;</code> in
          a form element that requests TestServlet
        </li>
        <li>
          as one or more option elements in a select element in the
          form-element
        </li>
      </ul>
    </section>

    <section title="Tell JUnitEE to use Cactus redirector">

      <p>
        The
        <code>cactus.properties</code> file must be located so that your
        container can find it e.g. in your containers classpath.
      </p>

    </section>

  </body>
</document>
