-Assert Task

- - -Assert Task

- -The Assert task adds an assertion capability to Ant projects. This task works in a manner very similar to the Java -assert - 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. -

- -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. -

- -Also like Java's -assert - keyword, the Assert task must be 'turned on' using the property -ant.enable.asserts -. If not set, or is set to -false -, the Assert task works exactly like the Sequential task. If the -Variable task - is used to define this property, then it can be turned on and off as needed throughout a build. -

- -This task can hold other tasks including Assert. -

- -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 -IsPropertyTrue -, -IsPropertyFalse -, - -StartsWith -, - -EndsWith -, - -IsGreaterThan -, - -IsLessThan - and conditions. -See the If task for examples of using these conditionals. -

- -

- - -

- -Table 4.1. Assert Task Attributes -

- ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-Attribute	-Description	-Default	-Required
-name	-The name of the property to test for.	-none	-Yes
-exists	-Test for existence or non-existence of the property.	-True	-No
-value	-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.	-none	-No
-execute	-Should the tasks contained in this task be executed? It may be useful to set this to false when testing build files.	-True	-No
-failonerror	-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.	-True	-No

- - -

- -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. -

- -In the following example, the first -assert - task checks that the -wait - property exists and does not execute the -echo - and -sleep - tasks. The second -assert - task checks that the -wait - property exists, has a value of 2, and executes the -echo - task. -

- - - - - -
-
- - - <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> - -
-
- -

- -The next example shows Assert being used in a unit test for the "limit" task: - - - - -
-
- - - <property name="ant.enable.asserts" value="true"/> - <target name="test2"> -  - <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> - -
-
- -

- -If the -ant.enable.asserts - property is set to false, then in the above example, the -echo -, -sleep -, and -echo - tasks will all execute. -