Limitations

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

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 (user@ant.apache.org) 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 (classpath.sh and build.sh) from that.

Targets

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}">
    <src>
      <pathelement location="src/java"/>
    </src>
    <classpath>
      <fileset dir="${lib.dir}">
        <include name="*.jar"/>
      </fileset>
    </classpath>
  </javac>
</target>

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.

Tasks

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.

Dependencies

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

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="final.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 "${final.name}" 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="default.target.dir" 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"
                      classpath="${ucovered.classes.dir}"/>

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">
  <classpath>
    <pathelement location="lib/ucovered-${ucovered.version}.jar"/>
  </classpath>
</taskdef>

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="com.xyz." checkExcludes="com.xyz.Test">
  <batchtest todir="${test.report.dir}">
    <fileset dir="test">
      <include name="**/Test*.java"/>
      <exclude name="**/TestA*"/>
    </fileset>          
  </batchtest>
</ucovered>

In this example, the attributes defined are dir, haltonerror, checkCoverage, checkIncludes, and checkExcludes. The batchtest subelement is directed to write its reports to ${test.report.dir} 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.

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

batchtest

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.

classpath

These nested elements look like this:

<classpath>
  <pathelement location="lib/ucovered-${ucovered.version}.jar"/>
  <pathelement path="${classpath}"/>
</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.

env

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

formatter

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.

jvmarg

sysproperty

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.

test

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.