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

  <properties>
    <title>Runners Howto</title>
  </properties>

  <body>

    <section title="Starting Cactus tests">

      <p>
        The Cactus tests are started using a JUnit Test Runner. There are
        several integration clients you can use for executing these test runners:
      </p>
      <ul>
        <li>
          <link href="site:integration_manual">Manually</link>. This means 
          that you need to deploy your code and tests into your container and
          start this container by yourself. Then you can execute the tests 
          by running a standard JUnit test Runner. For example, you can start
          the tests:
          <ul>
            <li>
              From the java command line, calling the <code>main()</code> 
              method of a JUnit Test Runner. For example, running the JUnit 
              Swing Test Runner:
              <code>junit.swingui.TestRunner.main [test case class]</code>
            </li>
            <li>
              <link href="site:howto_ide">From an IDE</link> or any tool 
              providing a JUnit integration plugin.
            </li>
            <li>
              <link href="site:integration_browser">From a browser</link>, by
              using the Cactus Servlet Test Runner, which is a special JUnit 
              Test Runner. Please also check the 
              <link href="site:howto_tomcat">Tomcat quick start tutorial</link>
              which is a step by step tutorial describing how to deploy Cactus 
              tests in Tomcat and how to execute them through a browser.
            </li>
            <li>
              From Ant by simply using the <code>&lt;junit&gt;</code> Ant task
              found in the Ant distribution.
            </li>
          </ul>
        </li>
        <li>
          Using the Cactus <link href="site:integration_ant">Ant 
          integration</link>. Cactus provides several custom Ant task to
          automate the deployment of Cactus tests 
          (<code>&lt;cactifywar&gt;</code>) and the 
          start/stop/configuration of your container 
          (<code>&lt;cactus&gt;</code>). Note that you can also use the 
          custom <code>&lt;runservertests&gt;</code> Ant task which allows you 
          to use your existing container configuration should you wish to.
        </li>
        <li>
          Using the Cactus <link href="ext:integration_maven">Maven 
          plugin</link>. As with the Ant tasks this plugin offers a fully 
          automated solution to deploy and execute Cactus tests.
        </li>
        <li>
          Using the <link href="site:integration_jetty">Jetty 
          integration</link>. Cactus provides a 
          <code>JettyTestSetup</code> class that you can directly 
          use in your Cactus TestCase's <code>suite()</code> method. This 
          <code>TestSetup</code> class will automatically configure and start
          Jetty for you before the tests are executed and it will stop it once
          the tests are finished. The nice thing is that starting Jetty takes
          only a few hundreds of milliseconds making this solution the fastest 
          one to execute your Cactus tests. Obviously it is only interesting if
          you wish to test using Jetty.
        </li>
      </ul>

    </section>

  </body>
</document>
