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 UCovered. The discussion here is limited to Ant's use in testing with UCovered and JUnit.

In Ant terminology, this is a tutorial on the UCovered 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.

Using Ant with JUnit

A glance through the Ant users list ( show that among the most common question are those relating to getting JUnit to work with Ant. You can avoid these problems by making absolutely certain that JUnit is on the classpath

  • when Ant is interpreting the build file: Ant needs to be able to find JUnit or UCovered
  • when Ant is invoking JUnit or UCovered: it needs to pass the right classpaths to them
  • and when your software is running: your software needs a correct classpath

To see this working, look at the example/3x6. Alternatively, look at the JXCL and UCovered build files.

Insofar as possible, we automate the process, putting jars in a standard place, describing the setup in a master project.xml configuration file, and then generating the underlying directory structure, Ant's build.xml build file, and the command files ( and from that.


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="ucovered-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 "ucovered-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="ucovered" 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.

UCoveredTask Task Definition

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

  • you must add a <taskdef>, which tells Ant where the UCovered task is to be found
  • you must tell Ant what you want UCovered 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="ucovered" classname="org.jxcl.ucovered.frontend.ant.UCoveredTask"

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

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

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

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

UCovered Element

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

<ucovered 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 <ucovered> element; many also can be used with subelements, allowing them to override these defaults set at the task level.

individual test control Most of these attributes can be set at the task, batchtest, or individual test level. For completeness all are listed here.
checkCoverageenable UCovered coverage checksNot required, default is false
checkExcludesComma-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.
checkIncludesComma-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.
errorPropertyProperty to be set to "true" if an unexpected error occurs during a test.Not required, no default.
failurePropertyProperty to be set to "true" if a failure (or unexpected error) occurs in testing.Not required, no default.
filtertraceEnable filtering of Ant/UCovered/JUnit exception stack trace lines from reports.Not required, defaults to true
forkRun tests in a separate Java Virtual Machine (JVM).Not required, defaults to false.
haltOnErrorStop the run if an error occurs.Not required, defaults to false.
haltOnFailureStop the run if a test failure (or unexpected error) occurs.Not required, defaults to false.
ifOnly run tests if the property with this name is set when parsing build.xml. See unlessNot required, no default.
mockTestRunDo 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.
nameName 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.
outfileBase 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.
todirDirectory to write reports to.Not required, defaults to current directory.
unlessOnly run tests if the property with this name is NOT set when parsing build.xml. See ifNot required, no default.
task control These attributes cannot be set at the batchtest or test level.
dirThe default directory if the JVM is forked.Not required, no default.
includeAntRuntimeSpecifically include Ant, UCovered, and Java when forking tests. Try this if desperateNot required, defaults to true.
jvmThe command used to invoke the Java virtual machine. Irrelevant if not forking.Not required, defaults to java.
maxmemorySet the maximum memory for the JVM. Irrelevant if not forking.Not required, no default.
mockExecDo not run tests, just display parameters for the run and test names. Useful for getting parameters right.Not required, defaults to false.
newenvironmentIf forking, start with a new system environment. Irrelevant if not forking.Not required, defaults to false.
printsummaryPrint 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.
showOutputSend test output to the Ant log as well as to the formatters.Not required, defaults to false.
timeoutStop 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 UCovered 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/ucovered-${ucovered.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/ucovered-${ucovered.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.

keyThe name of the environmental variableyes
valueThe value of the environmental variable in literal form; no further translation will be suppliedExactly one of these.
fileThe value as a file name; Ant will translate the name supplied into an absolute path name.
pathThe 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.

classnameName of formatter class. Must comply with org.jxcl.ucovered.reports.FormatterNot required. Cannot be used if type attribute is set.
extensionExtension to append to output file name. Ignored if formatter specified by type attribute.Not required, defaults to .txt
typeStandard formatter - brief, plain, or xml.Not required, defaults to plain.
usefileShould output be sent to file?Not required, defaults to true


Sets additional parameters
valuea single command line argument; may contain spacesExactly one of these
filea file name; Ant will translate it into the absolute path name of the file
linea comma-separated list of command line arguments avoid using this form
patha 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 testelement 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.