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

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

Copyright © 2003 Ant-Contrib Project. All rights Reserved.