<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>
Assert Task
</title>
<meta content="DocBook XSL Stylesheets V1.60.1" name="generator">
<link rel="home" href="index.html" title="Antelope Users Guide">
<link rel="up" href="bk03.html" title="Additional Ant Tasks">
<link rel="previous" href="bk03ch03.html" title="Chapter 3. Installation">
<link rel="next" href="bk03ch05.html" title="Chapter 5. If Task">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="chapter" lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="Assert">
</a>
Assert Task
</h2>
</div>
</div>
<div>
</div>
</div>
<p>
The Assert task adds an assertion capability to Ant projects. This task works in a manner very similar to the Java
<tt class="computeroutput">
assert
</tt>
keyword, and provides a limited "design by contract" facility to Ant. This is very useful for testing build scripts prior to putting them into production.
</p>
<p>
The Assert task verifies that a given property has a
given value and throws a BuildException if the property value is not as expected
or the property does not exist.
</p>
<p>
Also like Java's
<tt class="computeroutput">
assert
</tt>
keyword, the Assert task must be 'turned on' using the property
<tt class="computeroutput">
ant.enable.asserts
</tt>
. If not set, or is set to
<tt class="computeroutput">
false
</tt>
, the Assert task works exactly like the Sequential task. If the
<a href="variable_task.html" title="Variable Task">
Variable task
</a>
is used to define this property, then it can be turned on and off as needed throughout a build.
</p>
<p>
This task can hold other tasks including Assert.
</p>
<p>
The Assert task may contain one 'bool' element. The 'bool' element is identical to the ConditionTask, but unlike the ConditionTask, is actually a Task. The 'bool' element can contain all the conditions permitted by the ConditionTask, plus the
<a href="bk03ch05s02.html" title="More Conditions">
IsPropertyTrue
</a>
,
<a href="more_conditions.html" title="More Conditions">
IsPropertyFalse
</a>
,
<a href="more_conditions.html" title="More Conditions">
StartsWith
</a>
,
<a href="more_conditions.html" title="More Conditions">
EndsWith
</a>
,
<a href="more_conditions.html" title="More Conditions">
IsGreaterThan
</a>
,
<a href="more_conditions.html" title="More Conditions">
IsLessThan
</a>
and conditions.
See the If task for examples of using these conditionals.
</p>
<p>
<div class="table">
<a name="N10583">
</a>
<p class="title">
<b>
Table
4.1.
Assert Task Attributes
</b>
</p>
<table summary="Assert Task Attributes" border="1">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th>
Attribute
</th>
<th>
Description
</th>
<th>
Default
</th>
<th>
Required
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
name
</td>
<td>
The name of the property to test for.
</td>
<td>
none
</td>
<td>
Yes
</td>
</tr>
<tr>
<td>
exists
</td>
<td>
Test for existence or non-existence of the property.
</td>
<td>
True
</td>
<td>
No
</td>
</tr>
<tr>
<td>
value
</td>
<td>
The value to test for, implies 'exists=true'. If the value in the project is different than this value, a BuildException will be thrown and the build will stop.
</td>
<td>
none
</td>
<td>
No
</td>
</tr>
<tr>
<td>
execute
</td>
<td>
Should the tasks contained in this task be executed? It may be useful to set this to false when testing build files.
</td>
<td>
True
</td>
<td>
No
</td>
</tr>
<tr>
<td>
failonerror
</td>
<td>
Should the build halt if the assertion fails? Setting this to false is contrary to the intented use of assertions, but may be useful in certain situations.
</td>
<td>
True
</td>
<td>
No
</td>
</tr>
</tbody>
</table>
</div>
</p>
<p>
As stated above, the Assert task may contain a nested "bool" task, otherwise,
the Assert task does not support any nested
elements apart from Ant tasks. Any valid Ant task may be embedded within the
assert task.
</p>
<p>
In the following example, the first
<tt class="computeroutput">
assert
</tt>
task checks that the
<tt class="computeroutput">
wait
</tt>
property exists and does not execute the
<tt class="computeroutput">
echo
</tt>
and
<tt class="computeroutput">
sleep
</tt>
tasks. The second
<tt class="computeroutput">
assert
</tt>
task checks that the
<tt class="computeroutput">
wait
</tt>
property exists, has a value of 2, and executes the
<tt class="computeroutput">
echo
</tt>
task.
</p>
<p>
<table border="0" bgcolor="#E0E0E0">
<tr>
<td>
<pre class="programlisting">
<property name="wait" value="2"/
>
<assert name="wait" execute="false"
>
<echo
>
Waiting ${wait} seconds...
Click the red button to stop waiting.
</echo
>
<sleep seconds="${wait}"/
>
</assert
>
<assert name="wait" value="2" execute="true"
>
<echo
>done waiting!
</echo
>
</assert
>
</pre>
</td>
</tr>
</table>
</p>
<p>
The next example shows Assert being used in a unit test for the "limit" task:
<table border="0" bgcolor="#E0E0E0">
<tr>
<td>
<pre class="programlisting">
<property name="ant.enable.asserts" value="true"/
>
<target name="test2"
>
<!-- should not stop 'sleep' task, should print out '_passed_' --
>
<stopwatch name="timer"/
>
<limit maxwait="5"
>
<sleep seconds="1"/
>
<echo
>_passed_
</echo
>
</limit
>
<stopwatch name="timer" action="total"/
>
<assert message="Too much time."
>
<bool
>
<islessthan arg1="${timer}" arg2="2"/
>
</bool
>
</assert
>
</target
>
</pre>
</td>
</tr>
</table>
</p>
<p>
If the
<tt class="computeroutput">
ant.enable.asserts
</tt>
property is set to false, then in the above example, the
<tt class="computeroutput">
echo
</tt>
,
<tt class="computeroutput">
sleep
</tt>
, and
<tt class="computeroutput">
echo
</tt>
tasks will all execute.
</p>
<hr>
<p align="center">Copyright
© 2003 Ant-Contrib Project. All
rights Reserved.
</p>
</div>
</body>
</html>