Quilt - Ant Tutorial

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 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

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.

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="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 "${final.name}" 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="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.

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"
                      classpath="${quilt.classes.dir}"/>

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

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

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 <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.

batchtest
classpath
env
formatter
jvmarg
sysproperty
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/quilt-${quilt.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/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.

env

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

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.

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`

jvmarg

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

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 test element may not be nested within a batchtest element.