| 1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 4. Assert Task</title><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="Antelope Users Guide"><link rel="up" href="bk03.html" title="Additional Ant Tasks"><link rel="prev" 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="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. Assert Task</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk03ch03.html">Prev</a> </td><th width="60%" align="center">Additional Ant Tasks</th><td width="20%" align="right"> <a accesskey="n" href="bk03ch05.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Assert"></a>Chapter 4. Assert Task</h2></div></div></div>
|
|---|
| 2 | <STYLE TYPE="text/css"> <!-- @import url(./style.css); --> </STYLE>
|
|---|
| 3 | <p>
|
|---|
| 4 | The Assert task adds an assertion capability to Ant projects. This task works in a manner very similar to the Java <code class="computeroutput">assert</code> 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.
|
|---|
| 5 | </p><p>
|
|---|
| 6 | The Assert task verifies that a given property has a
|
|---|
| 7 | given value and throws a BuildException if the property value is not as expected
|
|---|
| 8 | or the property does not exist.
|
|---|
| 9 | </p><p>
|
|---|
| 10 | Also like Java's <code class="computeroutput">assert</code> keyword, the Assert task must be 'turned on' using the property <code class="computeroutput">ant.enable.asserts</code>. If not set, or is set to <code class="computeroutput">false</code>, the Assert task works exactly like the Sequential task. If the <a href="bk03ch09.html" title="Chapter 9. Variable Task">Variable task</a> is used to define this property, then it can be turned on and off as needed throughout a build.
|
|---|
| 11 | </p><p>
|
|---|
| 12 | This task can hold other tasks including Assert.
|
|---|
| 13 | </p><p>
|
|---|
| 14 | 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="bk03ch05s02.html" title="More Conditions">IsPropertyFalse</a>,
|
|---|
| 15 | <a href="bk03ch05s02.html" title="More Conditions">StartsWith</a>,
|
|---|
| 16 | <a href="bk03ch05s02.html" title="More Conditions">EndsWith</a>,
|
|---|
| 17 | <a href="bk03ch05s02.html" title="More Conditions">IsGreaterThan</a>,
|
|---|
| 18 | <a href="bk03ch05s02.html" title="More Conditions">IsLessThan</a>,
|
|---|
| 19 | <a href="bk03ch05s02.html" title="More Conditions">DateTimeBefore</a>,
|
|---|
| 20 | <a href="bk03ch05s02.html" title="More Conditions">DateTimeDifference</a>,
|
|---|
| 21 | <a href="bk03ch05s02.html" title="More Conditions">MathEquals</a> conditions.
|
|---|
| 22 | See the <a href="bk03ch05.html" title="Chapter 5. If Task">If task</a> for examples of using these conditionals.
|
|---|
| 23 | </p><p>
|
|---|
| 24 | To use this task in your build files, include a task definition like this:
|
|---|
| 25 | </p><p>
|
|---|
| 26 | </p><pre class="programlisting">
|
|---|
| 27 |
|
|---|
| 28 | <taskdef name="assert" classname="ise.antelope.tasks.Assert"/>
|
|---|
| 29 | <property name="ant.enable.asserts" value="true"/>
|
|---|
| 30 |
|
|---|
| 31 | </pre><p>
|
|---|
| 32 | </p><p>
|
|---|
| 33 | </p><div class="table"><a name="id2518779"></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><tr><td>message</td><td>A message to include with the output in the event of this assert failing.</td><td>none</td><td>No</td></tr><tr><td>level</td><td>A "level" for the assert, similar to debug levels. Valid values are 'error', 'warning', 'info', 'debug'.</td><td>error</td><td>No</td></tr></tbody></table></div><p>
|
|---|
| 34 |
|
|---|
| 35 | </p><p>
|
|---|
| 36 | As stated above, the Assert task may contain a nested "bool" task, otherwise,
|
|---|
| 37 | the Assert task does not support any nested
|
|---|
| 38 | elements apart from Ant tasks. Any valid Ant task may be embedded within the
|
|---|
| 39 | assert task.
|
|---|
| 40 | </p><p>
|
|---|
| 41 | The "level" attribute is only (so far) useful when Assert is used in conjunction with the <a href="bk03ch26.html" title="Chapter 26. TestCase Task">Testcase task</a>. Setting this attribute to "warning", "info", or "debug" will force "failonerror" to false.
|
|---|
| 42 | </p><p>
|
|---|
| 43 | In the following example, the first <code class="computeroutput">assert</code> task checks that the <code class="computeroutput">wait</code> property exists and does not execute the <code class="computeroutput">echo</code> and <code class="computeroutput">sleep</code> tasks. The second <code class="computeroutput">assert</code> task checks that the <code class="computeroutput">wait</code> property exists, has a value of 2, and executes the <code class="computeroutput">echo</code> task.
|
|---|
| 44 | </p><p>
|
|---|
| 45 | </p><pre class="programlisting">
|
|---|
| 46 |
|
|---|
| 47 | <property name="wait" value="2"/>
|
|---|
| 48 | <assert name="wait" execute="false">
|
|---|
| 49 | <echo>
|
|---|
| 50 | Waiting ${wait} seconds...
|
|---|
| 51 | Click the red button to stop waiting.
|
|---|
| 52 | </echo>
|
|---|
| 53 | <sleep seconds="${wait}"/>
|
|---|
| 54 | </assert>
|
|---|
| 55 | <assert name="wait" value="2" execute="true">
|
|---|
| 56 | <echo>done waiting!</echo>
|
|---|
| 57 | </assert>
|
|---|
| 58 |
|
|---|
| 59 | </pre><p>
|
|---|
| 60 | </p><p>
|
|---|
| 61 | The next example shows Assert being used in a unit test for the "limit" task:
|
|---|
| 62 | </p><pre class="programlisting">
|
|---|
| 63 |
|
|---|
| 64 | <property name="ant.enable.asserts" value="true"/>
|
|---|
| 65 | <target name="test2">
|
|---|
| 66 | <!-- should not stop 'sleep' task, should print out '_passed_' -->
|
|---|
| 67 | <stopwatch name="timer"/>
|
|---|
| 68 | <limit maxwait="5">
|
|---|
| 69 | <sleep seconds="1"/>
|
|---|
| 70 | <echo>_passed_</echo>
|
|---|
| 71 | </limit>
|
|---|
| 72 | <stopwatch name="timer" action="total"/>
|
|---|
| 73 | <assert message="Too much time.">
|
|---|
| 74 | <bool>
|
|---|
| 75 | <islessthan arg1="${timer}" arg2="2"/>
|
|---|
| 76 | </bool>
|
|---|
| 77 | </assert>
|
|---|
| 78 | </target>
|
|---|
| 79 |
|
|---|
| 80 | </pre><p>
|
|---|
| 81 | </p><p>
|
|---|
| 82 | If the <code class="computeroutput">ant.enable.asserts</code> property is set to false, then in the above example, the <code class="computeroutput">echo</code>, <code class="computeroutput">sleep</code>, and <code class="computeroutput">echo</code> tasks will all execute.
|
|---|
| 83 | </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk03ch03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk03ch05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Installation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. If Task</td></tr></table></div></body></html>
|
|---|
