cmlenz 2003/03/17 15:05:45
Modified: documentation/docs/xdocs/integration/ant navigation.xml
howto_ant_cactus.xml
documentation/docs/xdocs sitemap.xml
Added: documentation/docs/xdocs/integration/ant
task_runservertests.xml
Log:
Put the documentation about the <runservertests> task on a page in its
own right, plus some minor cleanup/updates to the Ant integration
howto.
Revision Changes Path
1.3 +1 -0
jakarta-cactus/documentation/docs/xdocs/integration/ant/navigation.xml
Index: navigation.xml
===================================================================
RCS file:
/home/cvs/jakarta-cactus/documentation/docs/xdocs/integration/ant/navigation.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- navigation.xml 17 Mar 2003 17:44:47 -0000 1.2
+++ navigation.xml 17 Mar 2003 23:05:44 -0000 1.3
@@ -13,6 +13,7 @@
</menu>
<menu label="Ant Tasks">
+ <item id="task_runservertests" label="RunServerTests"/>
<item id="task_webxmlmerge" label="WebXmlMerge"/>
</menu>
1.3 +61 -138
jakarta-cactus/documentation/docs/xdocs/integration/ant/howto_ant_cactus.xml
Index: howto_ant_cactus.xml
===================================================================
RCS file:
/home/cvs/jakarta-cactus/documentation/docs/xdocs/integration/ant/howto_ant_cactus.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- howto_ant_cactus.xml 8 Feb 2003 16:56:03 -0000 1.2
+++ howto_ant_cactus.xml 17 Mar 2003 23:05:44 -0000 1.3
@@ -6,6 +6,7 @@
<title>Running Cactus tests from Ant</title>
<authors>
<author name="Vincent Massol" email="[EMAIL PROTECTED]"/>
+ <author name="Christopher Lenz" email="[EMAIL PROTECTED]"/>
</authors>
</properties>
@@ -16,13 +17,13 @@
<note>
<strong>You need to have a good understanding of Ant before
reading this tutorial. If you don't, I suggest you read the
- <link href="http://jakarta.apache.org/ant/manual/index.html";>Ant
+ <link href="http://ant.apache.org/manual/index.html";>Ant
User Manual</link> first</strong>.
</note>
<p>
- This tutorial explains how start Cactus tests from your Ant build
- script (i.e. <code>build.xml</code>).
+ This tutorial explains how to integrate Cactus tests with a build
+ process based on Apache <link href="ext:ant">Ant</link>.
</p>
<p>
The Ant tasks involved for running a Cactus test are the following:
@@ -30,159 +31,81 @@
<ul>
<li>
<em>Step 0</em>: (optional) Deploy configuration files for your
- container,
+ container
</li>
<li>
<em>Step 1</em>: Package your Cactus tests as a WAR file and
- deploy it to your servlet engine webapps directory,
+ deploy it to your servlet engine webapps directory
</li>
<li>
<em>Step 2</em>: Start your servlet engine if it is not already
- started,
- </li>
- <li>
- <em>Step 3</em>: Run the tests using JUnit,
- </li>
- <li>
- <em>Step 4</em>: Stop the servlet engine (if need be)
- </li>
- </ul>
- <p>
- Cactus provides a custom Ant task (called the
- <code><runservertests></code> task) that helps perform all these
- tasks. The rest of this tutorial will explain how to write an Ant
- build file (<code>build.xml</code>) that performs these tasks and use
- the Cactus custom Ant task.
- </p>
- <p>
- During the remainder of this tutorial we will show examples for
- Tomcat 4.0. However, the principle can be applied to any other
- container. Ant Scripts for other containers can be found in the
- <code>/sample/build</code> directory where you have unpacked the
- Cactus distribution.
- </p>
-
- </section>
-
- <section title="The <runservertests> task">
-
- <p>
- This task will perform several actions, in the following order:
- </p>
+ started
+ </li>
+ <li>
+ <em>Step 3</em>: Run the tests using JUnit
+ </li>
+ <li>
+ <em>Step 4</em>: Stop the servlet engine if it hadn't been running
+ before
+ </li>
+ </ul>
+ <p>
+ Cactus provides a couple of custom Ant tasks that help perform these
+ steps. The rest of this tutorial will explain how to write an Ant
+ build file (<code>build.xml</code>) that performs the above steps using
+ the Cactus custom Ant tasks.
+ </p>
+ <p>
+ During the remainder of this tutorial we will show examples for
+ Tomcat 4.0. However, the principle can be applied to any other
+ container. Ant scripts for other containers are included with the
+ distribution of the Cactus/Ant-integration.
+ </p>
+
+ </section>
+
+ <section title="Using the Cactus Ant Tasks">
+
+ <p>
+ The Cactus/Ant-integration includes some custom tasks that can be used
+ from within Ant build files.
<ul>
<li>
- Check if a server is already started by constantly trying to
- call the test URL defined by the <code>testURL</code>
- attribute (see the example below),
- </li>
- <li>
- If a server is not started, call the Ant target defined by the
- <code>startTarget</code> attribute (see the example below). This
- target is
- supposed to start your container. The
<code><runservertests></code>
- task will then constantly poll the server by calling the test URL
- until the server answers back,
- </li>
- <li>
- It will then call the Ant target defined by the
- <code>testTarget</code> attribute (see the example below). This
- target is
- supposed to start the unit tests. This is usually implemented
- by using the Ant <code>junit</code> task,
+ <link href="site:task_runservertests">RunServerTests</link>
+ provides support for starting up a servlet container to run
+ in-container tests, and shutting it down again after the tests have
+ completed.
</li>
<li>
- Once the tests are finished (i.e. when the
- <code>testTarget</code> has finished executing), it will then
- call the Ant target defined by the <code>stopTarget</code>
- attribute (see the example below). This target is supposed to stop
- the container. The <code><runservertests></code>
- 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 <code>stopTarget</code>
- will only get called if the server was not already started when
- the <code><runservertests></code> task began executing. This
- is to allow keeping running servers for intensive debugging phases.
+ <link href="site:task_webxmlmerge">WebXmlMerge</link> provides a
+ convenient way to inject external definitions into a web deployment
+ descriptor (<code>web.xml</code>) from an Ant build
</li>
</ul>
- <p>
- The <code><runservertests></code> task is generic in the sense
- that you are free to implement the <code>startTarget</code>,
- <code>testTarget</code> and <code>stopTarget</code> as you wish and
- they will get called at the right time.
- </p>
- <p>
- Example:
- </p>
-
-<source><![CDATA[
-<!--
- ========================================================================
- Run Tomcat 4.0 tests
- ========================================================================
--->
-<target name="test.tomcat.40" depends="prepare.test.tomcat.40"
- if="tomcat.home.40" description="Run tests on Tomcat 4.0">
-
- <!-- Start the servlet engine, wait for it to be started, run the
- unit tests, stop the servlet engine, wait for it to be stopped.
- The servlet engine is stopped if the tests fail for any reason -->
-
- <runservertests
-
testURL="http://localhost:${test.port}/test/ServletRedirector?Cactus_Service=RUN_TEST";
- startTarget="start.tomcat.40"
- stopTarget="stop.tomcat.40"
- testTarget="test"/>
-
-</target>
-]]></source>
-
- <p>
- Before you can execute the <code><runservertests></code> task,
- you need to define it for Ant as it is not a standard Ant task. A
- good place to do this is in an <code>init</code> target.
- </p>
- <p>
- Example:
- </p>
+ </p>
+
+ <p>
+ Before you can use one of these tasks, you need to introduce it to Ant
+ as it is not a built-in task. This is done in a build file using the
+ <code>taskdef</code> task:
+ </p>
<source><![CDATA[
-<!--
- ======================================================================
- Initialize the build. Must be called by all targets
- ======================================================================
--->
-<target name="init">
- [...]
- <taskdef resource="cactus.tasks">
- <classpath>
- <pathelement location="${cactus.ant.jar}"/>
- </classpath>
- </taskdef>
- [...]
-</target>
+<taskdef resource="cactus.tasks">
+ <classpath>
+ <pathelement location="${cactus-ant.jar}"/>
+ </classpath>
+</taskdef>
]]></source>
<p>
- where <code>${cactus.ant.jar}</code> is an Ant property that points
- to the <code>cactus-ant.jar</code> file found in the
- <code>lib/</code> directory where you unpacked the Cactus
- distribution. In this example, <em>"cactus.tasks"</em>
- refers to a property file contained in the
- <code>cactus-ant.jar</code>. This property file lists the Ant
- tasks provided by Cactus, so you don't need to specify the class name
- that implements the task.
+ In this example, <code>${cactus-ant.jar}</code> is an Ant property that
+ points to the Cactus JAR that contains the custom Ant tasks. Note that
+ by specifying the <code>resource</code> attribute, it is not
+ necessary to define each task individually. The value of this
+ attribute, <code>cactus.tasks</code>, is a property file contained in
+ the JAR file which lists all tasks provided by Cactus.
</p>
-
- <note>
- The <code>prepare.test.tomcat.40</code> target is described in
- Step 0 below.
- </note>
-
- <note>
- The <code>tomcat.home.40</code> is simply an Ant property that
- points to the directory where Tomcat 4.0 has been installed. If this
- property is not defined we don't run the tests.
- </note>
</section>
1.1
jakarta-cactus/documentation/docs/xdocs/integration/ant/task_runservertests.xml
Index: task_runservertests.xml
===================================================================
<?xml version="1.0"?>
<document id="task_runservertests">
<properties>
<title>RunServerTests Ant Task</title>
<authors>
<author name="Vincent Massol" email="[EMAIL PROTECTED]"/>
<author name="Christopher Lenz" email="[EMAIL PROTECTED]"/>
</authors>
</properties>
<body>
<section title="RunServerTests Task">
<p>
The <strong>runservertests</strong> task provides support for starting up
a servlet container to run in-container tests, and shutting it down again
after the tests have completed.
</p>
<p>
This task will perform several actions, in the following order:
</p>
<ul>
<li>
Check if a server is already started by constantly trying to
call the test URL defined by the <code>testurl</code> attribute.
</li>
<li>
If a server is not running, call the Ant target defined by the
<code>starttarget</code> attribute. This target is supposed to start
your container. The <strong>runservertests</strong> task will then
constantly poll the server by calling the test URL until the server
answers back.
</li>
<li>
It will then call the Ant target defined by the <code>testtarget</code>
attribute. This target is supposed to run the unit tests. This is
usually implemented by using the Ant <code>junit</code> task.
</li>
<li>
Once the tests are finished (i.e. when the
<code>testtarget</code> has finished executing), it will then
call the Ant target defined by the <code>stoptarget</code> attribute.
This target is supposed to stop the container. The
<strong>runservertests</strong> 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
<code>stoptarget</code> will only get called if the server was not
already started when the <strong>runservertests</strong> task began
executing. This is to allow keeping running servers for intensive
debugging phases.
</li>
</ul>
<p>
The <strong>runservertests</strong> task is generic in the sense that you
are free to define the <code>starttarget</code>, <code>testtarget</code>
and <code>stoptarget</code> as you wish and they will get called at the
right time.
</p>
<note>
Since Ant 1.5, the effects of this task can also be achieved by using a
combination of the built-in Ant tasks <code>waitfor</code> (with the
<code>http</code> condition), <code>parallel</code>,
<code>sequential</code> and <code>antcall</code>.
</note>
<section title="Parameters">
<table>
<tr>
<th>Name</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td>testurl</td>
<td>
The HTTP URL to check whether the server is running.
</td>
<td>Yes</td>
</tr>
<tr>
<td>starttarget</td>
<td>
The target that is called when the server needs to be started.
</td>
<td>Yes</td>
</tr>
<tr>
<td>stoptarget</td>
<td>
The target that is called when the server should be shut down.
</td>
<td>Yes</td>
</tr>
<tr>
<td>testtarget</td>
<td>
The target that is called once the server is running. This target
will normally perform the actual unit tests.
</td>
<td>Yes</td>
</tr>
</table>
</section>
<section title="Examples">
<p>
In the following example, the target <code>start.tomcat.40</code> 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 <code>test</code> is called. Finally, after the
<code>test</code> target has completed, the target
<code>stop.tomcat.40</code> is called to shut down the servlet
container.
</p>
<source><![CDATA[
<runservertests
testurl="http://localhost:${test.port}/test/ServletRedirector?Cactus_Service=RUN_TEST";
starttarget="start.tomcat.40"
stoptarget="stop.tomcat.40"
testtarget="test"/>
]]></source>
</section>
</section>
</body>
</document>
1.20 +1 -0 jakarta-cactus/documentation/docs/xdocs/sitemap.xml
Index: sitemap.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/sitemap.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- sitemap.xml 17 Mar 2003 17:44:47 -0000 1.19
+++ sitemap.xml 17 Mar 2003 23:05:44 -0000 1.20
@@ -60,6 +60,7 @@
<resource id="howto_ant_cactus" target="integration/ant/howto_ant_cactus.html"/>
<resource id="howto_ant_install" target="integration/ant/howto_ant_install.html"/>
<resource id="howto_ant_primer" target="integration/ant/howto_ant_primer.html"/>
+ <resource id="task_runservertests"
target="integration/ant/task_runservertests.html"/>
<resource id="task_webxmlmerge" target="integration/ant/task_webxmlmerge.html"/>
<resource id="howto_httpunit" target="writing/howto_httpunit.html"/>
<resource id="howto_sample" target="howto_sample.html"/>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
