Chapter 4. Assert Task
Prev | Additional Ant Tasks | Next

## Chapter 4. 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, DateTimeBefore, DateTimeDifference, MathEquals conditions. See the If task for examples of using these conditionals.

To use this task in your build files, include a task definition like this:

        <taskdef name="assert" classname="ise.antelope.tasks.Assert"/>
        <property name="ant.enable.asserts" value="true"/>

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
message | A message to include with the output in the event of this assert failing. | none | No
level | A "level" for the assert, similar to debug levels. Valid values are 'error', 'warning', 'info', 'debug'. | error | 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.

The "level" attribute is only (so far) useful when Assert is used in conjunction with the Testcase task. Setting this attribute to "warning", "info", or "debug" will force "failonerror" to false.

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.

Prev | Up | Next
Chapter 3. Installation | Home | Chapter 5. If Task