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.