2011/08/05 - Jakarta Cactus has been retired.

For more information, please explore the Attic.

RunServerTests Task

The runservertests task provides support for starting up a servlet container to run in-container tests, and shutting it down again after the tests have completed.

This task will perform several actions, in the following order:

  • Check if a server is already started by constantly trying to call the test URL defined by the testurl attribute.
  • If a server is not running, call the Ant target defined by the starttarget attribute. This target is supposed to start your container. The runservertests task will then constantly poll the server by calling the test URL until the server answers back.
  • It will then call the Ant target defined by the testtarget attribute. This target is supposed to run the unit tests. This is usually implemented by using the Ant junit task.
  • Once the tests are finished (i.e. when the testtarget has finished executing), it will then call the Ant target defined by the stoptarget attribute. This target is supposed to stop the container. The runservertests task will then constantly poll the server by calling the test URL until the server stops answering, at which point it will consider the server to be stopped. Note that the stoptarget will only get called if the server was not already started when the runservertests task began executing. This is to allow keeping running servers for intensive debugging phases.
The runservertests task is generic in the sense that you are free to define the starttarget, testtarget and stoptarget as you wish and they will get called at the right time. Since Ant 1.5, the effects of this task can also be achieved by using a combination of the built-in Ant tasks waitfor (with the http condition), parallel, sequential and antcall.

Parameters

Name Description Required
testurl The HTTP URL to check whether the server is running. Yes
starttarget The target that is called when the server needs to be started. Yes
stoptarget The target that is called when the server should be shut down. Yes
testtarget The target that is called once the server is running. This target will normally perform the actual unit tests. Yes
timeout The timeout in seconds. If the server could not be started before the timeout is reached, the task will terminate and report a failure. No

Examples

In the following example, the target start.tomcat.40 will be called if the specified test URL is not available. After the server has started up so that requests to the test URL return successful HTTP status codes, the target test is called. Finally, after the test target has completed, the target stop.tomcat.40 is called to shut down the servlet container.
<runservertests
    testurl="http://localhost:${test.port}/test/ServletRedirector?Cactus_Service=RUN_TEST"
    starttarget="start.tomcat.40"
    stoptarget="stop.tomcat.40"
    testtarget="test"/>