Test suites are often run as part of a build process. And when the build process is orchestrated by Ant, lots of test-related information gets embedded in Ant build files. Ant now has a new Antlib that makes test setup and execution easier. According to the project documentation for AntUnit 1.0:

Initially, all tests for Ant tasks were written as individual JUnit test cases. Pretty soon it was clear that most tests needed to perform common tasks like reading a build file, initializing a project instance with it and executing a target. At this point BuildFileTest was invented, a base class for almost all task test cases...

Over time a new pattern evolved, more and more tests only executed a target and didn't check any effects. Instead that target contained the assertions as a <fail> task.

The above approach is illustrated with an example for a test for ANTLR that verifies the existence of five files:

  <target name="test3" depends="setup">
    <antlr target="antlr.g" outputdirectory="${tmp.dir}"/>
    <fail>
      <condition>
        <!-- to prove each of these files exists;
             ANTLR >= 2.7.6 leaves behind new (.smap) files as well. -->
        <resourcecount when="ne" count="5">
          <fileset dir="${tmp.dir}">
            <include name="CalcParserTokenTypes.txt" />
            <include name="CalcParserTokenTypes.java" />
            <include name="CalcLexer.java" />
            <include name="CalcParser.java" />
            <include name="CalcTreeWalker.java" />
          </fileset>
        </resourcecount>
      </condition>
    </fail>
  </target>

The above XML target is then used in conjunction with the following simple Java class:

public class ANTLRTest extends BuildFileTest {

    private final static String TASKDEFS_DIR = "src/etc/testcases/taskdefs/optional/antlr/";

    public ANTLRTest(String name) {
        super(name);
    }

    public void setUp() {
        configureProject(TASKDEFS_DIR + "antlr.xml");
    }

    public void tearDown() {
        executeTarget("cleanup");
    }

    public void test3() {
        executeTarget("test3");
    }
...
}

The AntUnit project page notes that the approach of inserting test snippets directly into Ant files can, in some cases, eliminate the need for standalone JUnit test classes:

AntUnit takes this approach to testing even further, it removes JUnit completely and it comes with a set of predefined <assert> tasks in order to reuse common kind of checks.

It turns out that AntUnit lends itself as a solution to other problems as well. The assertions are an easy way to validate a setup before even starting the build process, for example. AntUnit could also be used for functional and integration tests outside of the scope of Ant tasks (assert contents of databases after running an application, assert contents of HTTP responses ...). This is an area that will need more research.

What do you think of AntUnit's approach to embedding test code directly in Ant files?

 <target name="testWeekdayCaseSensitive" depends="define">
     <au:expectfailure
       expectedMessage="not a permitted value">
       <book:weekday day="September"/>
     </au:expectfailure>
   </target>

  <target name="echo-task-jython">
    <scriptdef language="jython"
        name="echo"
        uri="http://antbook.org/script">
self.log("text: " +self.text)
    </scriptdef>
  </target>

  <target name="testEcho" depends="echo-task-jython"
      xmlns:s="http://antbook.org/script">
    <s:echo>nested text</s:echo>
    <au:assertLogContains text="text: nested text"/>
  </target>