JUnitEE allows you to manually run test cases inside your application server. This guide will show you how to integrate the creation of the test.war and execution of your server test cases into your Ant build scripts. By doing so you will be able to automatically run - or better let Ant run - your test cases as part of your build process.

For this purpose JUnitEE contains two Ant tasks:

• the JUnitEEWar task creates the .war file you need to run your tests inside a servlet container (similar to the War task included in the standard Ant distribution)
• the JUnitEE task allows you to start execution of your server-side tests from within your ant build script (similar to the JUnit task included in the standard Ant distribution)

This HowTo will describe these tasks in more detail and show you how to use them to automate your server-side test execution.

We assume that you have your application and your JUnitEE test cases up and running. And we also assume that you already use Ant as your build system. Otherwise please check the Ant documentation to learn more about this great and useful build tool.

Before we start, you will need another software package in addition to your app server, your application, JUnit, JUnitEE, Ant, and the appropriate JDK: the Cactus test framework

Cactus also provides a way for testing server-side functionality of your applications. But as this is a JUnitEE guide, we will not use Cactus as our test framework (Cactus is a little bit more complex in usage than JUnitEE but has also some nice features, so it might be worth a closer look), but will reuse a very usefull Ant task that ships with Cactus. Details will follow soon.

The first step in using the JUnitEE tasks is to declare them in your build script:

<taskdef name="junitee" classname="org.junitee.anttask.JUnitEETask">
  <classpath>
    <pathelement location="lib/junitee-anttask.jar"/>
  </classpath>
</taskdef>

<taskdef name="juniteewar" classname="org.junitee.anttask.JUnitEEWarTask">
  <classpath>
    <pathelement location="lib/junitee-anttask.jar"/>
  </classpath>
</taskdef>

You have to replace lib/junitee-anttaks.jar in this example with the location of the junitee-anttask.jar in your directory structure.

Now that Ant knows about the JUnitEE tasks we will first use the JUnitEEWar task to create the test.war. Consider that you have a project with the following characteristics:

• the classes to test are located in build/classes
• the test classes are compiled in the directory build/test
• the test classes names have Test as a prefix
• the .jar files you need are stored in the lib directory

The following Ant task

<juniteewar destFile="myTest.war">
  <lib dir="lib" includes="junitee.jar"/>
  <lib dir="lib" includes="junit.jar"/>
  <classes dir="build/classes">
    <include name="**/*.class"/>
  </classes>
  <classes dir="build/test">
    <include name="**/*.class"/>
  </classes>
  <testcases dir="build/test">
    <include name="**/Test*.class"/>
  </testcases>
</juniteewar>

will build a file called myTest.war which contains

• junit.jar and junitee.jar under WEB-INF/lib
• the classes to test and all test cases under WEB-INF/classes
• a file named WEB-INF/testCase.txt which contains a list of all test case names
• a file named index.html which allows you to run tests manually using your browser
• the deployment descriptor WEB-INF/web.xml which makes myTest.war a deployable web archive

It would be possible to deploy myTest.war and run your tests manually by pointing your browser to the URL http://your.server:port/myTest/index.html. But we will automate these steps, too, so stay tuned.

At this point we have a deployable .war file, so in the next step we have to tell Ant how to deploy the war and how to run the tests. Let's start with the second step and define a target named do-run-tests:

<target name="do-run-tests">
  <junitee url="http://your.server:port/myTest/TestServlet" printsummary="true">
    <test runall="true"/>
  </junitee>
</target>

Executing this target will run all test cases included in myTest.war and print a summary of the test results to the console window.

Now we have a deployable war file and an Ant target to run the tests. The last missing step is to automate the deploy-run-undeploy cycle, and this is the moment when Jakarta Cactus enters the stage. Cactus provides an Ant task that does the following:

• deploy your application and wait until deployment is finished by the application server
• run your tests
• and finally undeploy your application

This is exactly what we need to reach our goal. Therefore we define another external task:

<taskdef name="runservertests"
  classname="org.apache.cactus.ant.RunServerTestsTask"
  classpath="lib/cactus-ant.jar"/>

Now we are able to define our run-tests target:

<target name="run-tests">
  <runservertests
    testURL="http://your.server:port/myTest/TestServlet"
    startTarget="deploy-test-ear"
    stopTarget="undeploy-test-ear"
    testTarget="do-run-tests" />
</target>

The testURL attribute has the same value as the url attribute of the junitee task in the do-run-tests target. The Cactus task will use this URL to check wether deployment of the application is finished.

We do not show the deploy-test-ear and undeploy-test-ear targets here. Their purpose is - what a surprise :-) - to deploy/undeploy myTest.war. There are different ways to get this done depending on your application server. Some servers support hot deployment of applications, so it is enough to copy your application to some deploy directory. Others lack this feature and therefore you have to restart the server to get your application (re)deployed. Or you have to use a command line tool to deploy the application. We can not give a general example for this step, so it is up to you to get these two targets up and running. But as you are working with your application server day by day, this shouldn't be too difficult.

That's it! Whenever you execute the run-tests target, Ant will deploy your application, run the tests and undeploy the application. And if there was a failure or error in one of the tests, the build process will be stopped with an error message.

In case you are using an application server which supports hot deploy of your applications, things are a little bit easier. You just have to hot deploy the test.war by copying the file to the deploy directory, wait for deployment and then run the tests. Here is the ant task (thanks to Gregory Joseph):

<target name="run-tests">
  <taskdef name="junitee" classname="org.junitee.anttask.JUnitEETask">
    <classpath>
      <pathelement location="lib/junitee-anttask.jar"/>
    </classpath>
  </taskdef>

  <copy file="myTest.war" todir="${test.deploy.dir}"/>

  <waitfor maxwait="10000">
    <http url="http://your.server:port/myTest/TestServlet>
  </waitfor>

  <echo>Running JUnitEE tests</ant:echo>

  <junitee url="http://your.server:port/myTest/TestServlet" printsummary="true">
     <test runall="true"/>
  </junitee>
</target>

This was a small and simple example to show you how to use JUnitEE in combination with Ant. Please have a look at the JUnitEE User's Guide for a full documentation of the JUnitEE servlet and the JUnitEE Ant tasks, and also check the Cactus Ant HowTo for a more detailed description of the runservertests task.

This project is hosted by