Ant Tutorial


This is by no means a thorough introduction to Ant. Ant is wonderously complex and constantly changing as volunteer workers modify its code and add external tasks which work in cooperation with Ant, tasks such as Quilt. The discussion here is limited to Ant's use in testing with Quilt and JUnit.

In Ant terminology, this is a tutorial on the Quilt task.


Ant is a tool for automating the Java build process, probably the most widely used in the world. Ant runs anywhere that Java runs, so Ant has the same "write once, run anywhere" quality.

Ant is used by writing XML scripts describing the job to be done. Each script sets out a number of targets , tasks , properties , and dependencies and specifies the relationship among them. When the script is run, Ant will examine the dependencies between the targets, consider the value of the properties, and from this decide which tasks need to be run and in what order.

By default Ant uses build.xml as its build file; by default it looks for this in the current directory.


A target is described by an XML <target> element, which has a name, some attributes, and a number of contained elements.

<target name="compile" depends="init">
  <mkdir dir="${classes.dir}"/>
  <javac destdir="${classes.dir}">
      <pathelement location="src/java"/>
      <fileset dir="${lib.dir}">
        <include name="*.jar"/>

In this example, the target, compile, depends upon init, which must have been completed before it will be run.

There are other optional target attributes; for example, a description is commonly supplied. This will be output by Ant at run time, allowing you to see targets as they are executed.

When compile is eligible, it will first make the ${classes.dir} directory if it does not exist. This is specified by the mkdir task.


In the example above the main task is the Java compiler task, javac. It writes its output to destdir, which is given as an attribute.

The compiler reads source files from the directory specified in the src element, in this case src/java. Its classpath is specified by the classpath element, which includes a fileset. This supplies a pattern for valid names ( *.jar ) to be included in the classpath, and a directory to look for such files in as an attribute, dir.


The order in which targets become eligible to be run is determined by the depends attribute. There can be an arbitrary number of dependencies set out as a comma-separated list.

  <target name="jar" description="o Create the jar" depends="compile,test"> 


Properties are name-value pairs and are normally placed at the top of the build file.

  <property name="lib.dir" value="target/lib"/> 
  <property name="" value="quilt-dev"/>

Properties can then be used elsewhere in the build file by enclosing the names in braces and preceding this with a dollar sign. Ant will then substitute the appropriate value when it encounters the expression during the run. So in this case, the string "${lib.dir}" will be replaced by "target/lib", which will be interpreted as a path relative to the base directory for the build, ${basedir}; and "${}" would be replaced by "quilt-dev".

The Ant build.xml File

The build file is an XML file containing a <project> element and its attributes and subelements.

<project default="jar" name="quilt" basedir=".">
  <property name="noget" value="true"/>
  <property name="" value="target"/>
  <property name="lib.dir" value = target/lib"/>

In a UNIX environment, Ant can be run by simply typing its name.

% ant

In this case, Ant will look for a file build.xml in the current directory and execute it. By default, its target will be jar

Alternatively the task can be specified on the command line:

% ant compile          

In this case, Ant will read build.xml in the current directory and carry out all targets that compile depends upon and then compile itself.

It is also possible to give Ant a path to the build file and the build file a name other than build.xml:

% ant -f path/anotherbuild.xml test        

Here Ant will use path/anotherbuild.xml as its its build file, completing all targets that test depends upon and test itself.

QuiltTask Task Definition

In order to use Quilt from Ant, you need to do two things.

  • you must add a <taskdef>, which tells Ant where the Quilt task is to be found
  • you must tell Ant what you want Quilt to do

The first is the subject of this section. The second is the subject of the next.

To define the task, add an element like this to your build.xml file:

<taskdef name="quilt" classname="org.quilt.frontend.ant.QuiltTask"

where quilt.classes.dir is a predefined property telling Ant where to start looking for the class. This form is appropriate if you have obtained Quilt by CVS or have unzipped a tarball. In either case Quilt's org will be a subdirectory of quilt.classes.dir.

You can also use a form like the following, appropriate when Quilt is in its jar:

<taskdef name="quilt" classname="org.quilt.frontend.ant.QuiltTask">
    <pathelement location="lib/quilt-${quilt.version}.jar"/>

Whichever form you use, the <taskdef> element needs to appear in the build.xml file above the <quilt> element, where you actually run your tests.

Quilt Element

Like any other XML element, the <quilt> element consists of an opening tag with the element name and a number of attribute/value pairs, some subelements, and a closing tag.

<quilt dir="." haltonerror="false" checkCoverage="true"
               checkIncludes="" checkExcludes="">
  <batchtest todir="${}">
    <fileset dir="test">
      <include name="**/Test*.java"/>
      <exclude name="**/TestA*"/>

In this example, the attributes defined are dir, haltonerror, checkCoverage, checkIncludes, and checkExcludes. The batchtest subelement is directed to write its reports to ${} by setting the todir attribute. The files to be tested are defined using the very convenient Ant fileset element, which in this case looks in and below the test directory for test files, those whose names begin with Test but not TestA.

The table that follows lists the attributes used with the <quilt> element; many also can be used with subelements, allowing them to override these defaults set at the task level.

attribute description required?/default
individual test control Most of these attributes can be set at the task, batchtest, or individual test level. For completeness all are listed here.
checkCoverage enable Quilt coverage checks Not required, default is false
checkExcludes Comma-separated list of classes not to run coverage checks on. This rule is checked before the rule for inclusion. There are no wildcards. If the beginning of a class name matches a name in the list, it is excluded. Not required. java and javax classes are added to the list automatically.
checkIncludes Comma-separated list of classes to run coverage checks on. There are no wild cards. If the beginning of a class name matches a name in the list and if it has not already been excluded, it is included. Not required, no default.
errorProperty Property to be set to "true" if an unexpected error occurs during a test. Not required, no default.
failureProperty Property to be set to "true" if a failure (or unexpected error) occurs in testing. Not required, no default.
filtertrace Enable filtering of Ant/Quilt/JUnit exception stack trace lines from reports. Not required, defaults to true
fork Run tests in a separate Java Virtual Machine (JVM). Not required, defaults to false .
haltOnError Stop the run if an error occurs. Not required, defaults to false .
haltOnFailure Stop the run if a test failure (or unexpected error) occurs. Not required, defaults to false .
if Only run tests if the property with this name is set when parsing build.xml . See unless Not required, no default.
mockTestRun Do not actually run the tests; instead output the set of parameters each test would see if it had been run. Useful in getting your parameter set right. Not required, defaults to false .
name Name of an individual test. Cannot be set at task level, ignored in batchtests, where the test name is derived from the file name. Required in <test> subelements, no default.
outfile Base name of report file. Cannot be set at task level, ignored in batchtests, where the name is derived from the test file name. Not required, defaults to TEST-name.
todir Directory to write reports to. Not required, defaults to current directory.
unless Only run tests if the property with this name is NOT set when parsing build.xml . See if Not required, no default.
task control These attributes cannot be set at the batchtest or test level.
dir The default directory if the JVM is forked. Not required, no default.
includeAntRuntime Specifically include Ant, Quilt, and Java when forking tests. Try this if desperate Not required, defaults to true .
jvm The command used to invoke the Java virtual machine. Irrelevant if not forking. Not required, defaults to java.
maxmemory Set the maximum memory for the JVM. Irrelevant if not forking. Not required, no default.
mockExec Do not run tests, just display parameters for the run and test names. Useful for getting parameters right. Not required, defaults to false .
newenvironment If forking, start with a new system environment. Irrelevant if not forking. Not required, defaults to false .
printsummary Print one-line summary for each test. Acceptable values are on, true, yes, withOutAndErr; off, false, no. If the value is withOutAndErr , test output written to System.out and System.err will be included. Not required, defaults to off.
showOutput Send test output to the Ant log as well as to the formatters. Not required, defaults to false .
timeout Stop tests if they don't finish within this time limit (in milliseconds). Not required, defaults to infinity.

Nested Elements

The following elements can be nested within the Quilt task element.

  1. batchtest
  2. classpath
  3. env
  4. formatter
  5. jvmarg
  6. sysproperty
  7. test


Batchtests can have all of the test attributes except name and outfile . These are generated automatically from the names of test files supplied in the Ant fileset patterns.

If name or outfile are supplied, they are ignored.


These nested elements look like this:

  <pathelement location="lib/quilt-${quilt.version}.jar"/>
  <pathelement path="${classpath}"/>

The path form can be used with lists of locations separated by either colons (:) or semicolons (;). Ant will automatically convert the separator to whatever is expected by the operating system.

classpath will also accept path and location as attributes, so that

<classpath location="lib/quilt-${quilt.version}.jar"/>

is also valid.

It is also possible, though not necessarily advisable, to build classpaths using Ant's dirset, filelist, and filelist elements. See the Ant manual for further information on this.


This nested element sets up an environmental variable to pass to the system command. Ignored if not forking.

attribute description required?
key The name of the environmental variable yes
value The value of the environmental variable in literal form; no further translation will be supplied Exactly one of these.
file The value as a file name; Ant will translate the name supplied into an absolute path name.
path The value as a colon- or semicolon-separated list of paths. Ant will translate the separator into whatever the operating system requires


Report formatters can be set at the task, batchtest, or test level. Formatters set at low levels (test or batchtest) override any set at higher levels.

There are standard formatters identified by short names, currently three: brief, plain, and xml. A fourth, summary, is run if the summary attribute is set. Any or all of these formatters can be run in combination.

The brief formatter prints detailed information only on failed tests. The default plain formatter prints a summary line for each test.

The xml formatter supplies test output in XML format; this includes a full list of system properties, so the output can be quite verbose. The formatter may strip characters unacceptable to XML from the output.

attribute description required/default
classname Name of formatter class. Must comply with org.quilt.reports.Formatter Not required. Cannot be used if type attribute is set.
extension Extension to append to output file name. Ignored if formatter specified by type attribute. Not required, defaults to .txt
type Standard formatter - brief, plain, or xml. Not required, defaults to plain.
usefile Should output be sent to file? Not required, defaults to true


Sets additional parameters
attribute description required?
value a single command line argument; may contain spaces Exactly one of these
file a file name; Ant will translate it into the absolute path name of the file
line a comma-separated list of command line arguments avoid using this form
path a colon or semicolon separated list of paths; Ant will convert the separator to whatever the operating system needs


Sets system properties which will be passed to the JVM for the test run. Ignored if not forking.

See env for a list of attributes.


Tests are defined individually or using batchtests. In either case the test attributes in the first part of the table above can be used. Batchtest attributes are applied to all tests in the set. Test attributes apply only to that particular test. In either case they override any attributes set at the task level.

The test element may not be nested within a batchtest element.

This material is copyright 2003 by James David Dixon ("Jim Dixon") and is made available under the Artistic License .