<terp.fail> - an alternative <fail> task

The <terp.fail> task

Using the <terp.fail> task requires that the ant-terp.jar file be available to ant and that the task be registered via a <taskdef> statement:

<taskdef name="terp.fail" classname="com.codemesh.terp.ant.Fail"/>

Please note that you could use any value for the name attribute that you wish; you are not limited to terp.fail. All our examples and documentation use the terp.fail name and use a name prefix of terp. to signal that they originate with and rely on the terp framework.

The <terp.fail> task is not an extension of the ANT <fail> task. It extends the abstract TerpAwareTask type, which is a plain ANT task type providing support for the if and unless attributes available to all tasks in the terp framework:

terp.fail attributes

Name	Type	Description
if	String	Optional attribute specifying a boolean terp expression. The expression represents a condition that must be satisfied for the task to be executed.
message	String	Optional attribute specifying the text to be displayed in case of failure.
messageexpression	String	Optional attribute specifying a terp expression that will be evaluated in the current context to create the failure message. This is an expression, not an embedded expression delimited by ${}.
unless	String	Optional attribute specifying a boolean terp expression. The expression represents a condition that must not be satisfied for the task to be executed.

Purpose

The <terp.fail> task is most useful for unit tests of ANT functionality. When the if condition is true or the unless condition is false, the task throws a BuildException with the conditions as the exception message. As both conditions are interpreted as terp expressions, it is very easy to express complex conditions without having massively nested ANT <condition> clauses.

Example

The following example invokes a shell command to execute the application myapp. It also illustrates how the result can be used in later build steps.

<terp.exec expression="^shell('myapp')()"
           result="res"
           failonerror="false"
/>
<terp.fail if="res.exitcode!=0 || res.outraw!='Test'" 
           messageexpression="'Expected \'Test\', got \'' + res.outraw + '\''" 
/>

Please remember that while you can simply use || to represent a logical OR condition, logical AND conditions need to be expressed as && because the ampersand is an escape character in XML files.