Ant Integration

Running in Ant
Setting up the Task
Using the Task
- Nested Elements
Examples

Running in Ant

Ant provides a very useful task, junit. JUnitScript provides a similar task, junitscript. This section describes how to use this task.

Setting up the Task

Adding the junitscript task to Ant is simple, place the following in the build file:

<taskdef name="junitscript" classname="com.hjl.junitscript.ant.JUnitScriptTask"/>

Alternatively, add the task to Ant's default.properties

Using the Task

The task is very similar to the normal junit task, in fact the code is based from it. The table below describes the attributes for the task. These are mostly identical to those in the junit task, except for useargs

Parameters
Attribute	Description	Required
useargs	Indicates whether non script tests (ordinary Java test cases) should be passed commandline arguments. This means that instead of searching for a method matching static junit.framework.Test suite(), the system will search for static junit.framework.Test suite( String[] ).	No; default is no unless nested <arg> elements are used, in which case the default is yes.
printsummary	Print one-line statistics for each testcase. Can take the values on, off, and withOutAndErr. withOutAndErr is the same as on but also includes the output of the test as written to System.out and System.err.	No; default is off
fork	Run the tests in a separate VM.	No; default is off
haltonerror	Stop the build process if an error occurs during the test run.	No; default is off
errorproperty	The name of a property to set in the event of an error.	No
haltonfailure	Stop the build process if a test fails (errors are considered failures as well).	No; default is off
failureproperty	The name of a property to set in the event of a failure (errors are considered failures as well).	No
filtertrace	Filter out Junit and Ant stack frames from error and failure stack traces.	No; default is on
timeout	Cancel the individual tests if they don't finish in the given time (measured in milliseconds). Ignored if fork is disabled.	No
maxmemory	Maximum amount of memory to allocate to the forked VM. Ignored if fork is disabled.	No
jvm	The command used to invoke the Java Virtual Machine, default is 'java'. The command is resolved by java.lang.Runtime.exec(). Ignored if fork is disabled.	No; default is java
dir	The directory in which to invoke the VM. Ignored if fork is disabled.	No
newenvironment	Do not propagate the old environment when new environment variables are specified. Ignored if fork is disabled.	No; default is false
includeantruntime	Implicitly add the Ant classes required to run the tests and JUnit to the classpath in forked mode.	No; default is true
showoutput	Send any output generated by tests to Ant's logging system as well as to the formatters. By default only the formatters receive the output.	No

Nested Elements

classpath

Sets up the classpath to run the tests with. This is a standard Ant classpath element. (See the java task.)

jvmarg

Passes arguments to the forked JVM. (See the java task.)

sysproperty

Passes system properties to the test. (See the java task.)

env

Passes environment variables to the forked JVM. (See the java task.)

formatter

The results of the tests can be printed in different formats. Output will always be sent to a file, unless you set the usefile attribute to false. The name of the file is determined by the name of the test and can be set by the outfile attribute of <test>.

There are three predefined formatters - one prints the test results in XML format, the other emits plain text. The formatter named brief will only print detailed information for testcases that failed, while plain gives a little statistics line for all test cases. Custom formatters that need to implement com.hjl.junitscript.ant.JUnitResultFormatter can be specified.

Note

If you use the XML formatter, it may not include the same output that your tests have written as some characters are illegal in XML documents and will be dropped.

Warning

Formatters are identical to those in the junit task except that they have had to be moved into a different package and hence custom formatters must respect this.

Attribute	Description	Required
type	Use a predefined formatter (either xml, plain, or brief).	Exactly one of type or classname.
classname	Name of a custom formatter class.	Exactly one of type or classname.
extension	Extension to append to the output filename.	Yes, if classname has been used.
usefile	Boolean that determines whether output should be sent to a file.	No; default is true.

test

Defines a single test class, script or suite file.

Attribute	Description	Required
classname	Name of a normal test class.	Exactly one of classname and script
script	File name of a script or suite file.	Exactly one of classname and script
useargs	Indicates whether non script tests (ordinary Java test cases) should be passed commandline arguments. This means that instead of searching for a method matching static junit.framework.Test suite(), the system will search for static junit.framework.Test suite( String[] ).	No; default is no unless nested <arg> elements are used, in which case the default is yes.
fork	Run the tests in a separate VM. Overrides value set in <junit>.	No
haltonerror	Stop the build process if an error occurs during the test run. Overrides value set in <junit>.	No
errorproperty	The name of a property to set in the event of an error. Overrides value set in <junit>.	No
haltonfailure	Stop the build process if a test fails (errors are considered failures as well). Overrides value set in <junit>.	No
failureproperty	The name of a property to set in the event of a failure (errors are considered failures as well). Overrides value set in <junit>.	No
filtertrace	Filter out Junit and Ant stack frames from error and failure stack traces. Overrides value set in <junit>.	No; default is on.
todir	Directory to write the reports to.	No; default is the current directory.
outfile	Base name of the test result. The full filename is determined by this attribute and the extension of formatter.	No; default is TEST-name, where name is the name of the test specified in the name attribute.
if	Only run test if the named property is set.	No
unless	Only run test if the named property is not set.	No

Nested Arguments

Tests can have nested <formatter> elements that are the same as the those for the parent junitscript task.

Tests can also have nested <arg> elements. The syntax of these is the same as normal Ant command line argument elements. If the test is a script, then these will be collected and passed to the script in a manner dependent on the language. If the test is a normal class, then the system will search for a method, static junit.framework.Test suite( String[] ). If one is found then this method will be used to find the tests with the arguments passed as a string array. If no such method is found, then it will ignore the arguments and create a junit.framework.TestSuite based on the test class. Use of arguments is controlled by the useargs attribute.

batchtest

batchtest specify a number of tests based on nested <fileset> elements. Once the files in the file sets are expanded, the tests are treated in the same way as <test> elements, except that the choice of whether the test is a normal class or a script is determined in the following manner:

If the filename ends in .java or .class then it is assumed to be a class, as per the normal junit task. Otherwise it will be run as a script or suite file.

Attribute	Description	Required
useargs	Indicates whether non script tests (ordinary Java test cases) should be passed commandline arguments. This means that instead of searching for a method matching static junit.framework.Test suite(), the system will search for static junit.framework.Test suite( String[] ).	No; default is no unless nested <arg> elements are used, in which case the default is yes.
fork	Run the tests in a separate VM. Overrides value set in <junit>.	No
haltonerror	Stop the build process if an error occurs during the test run. Overrides value set in <junit>.	No
errorproperty	The name of a property to set in the event of an error. Overrides value set in <junit>.	No
haltonfailure	Stop the build process if a test fails (errors are considered failures as well). Overrides value set in <junit>.	No
failureproperty	The name of a property to set in the event of a failure (errors are considered failures as well). Overrides value set in <junit>	No
filtertrace	Filter out Junit and Ant stack frames from error and failure stack traces. Overrides value set in <junit>.	No; default is on.
todir	Directory to write the reports to.	No; default is the current directory.
if	Only run tests if the named property is set.	No
unless	Only run tests if the named property is not set.	No

Nested Arguments

Any number of <fileset> elements can be included to specify the tests to be run.

Tests can have nested <formatter> elements that are the same as the those for the parent junitscript task.

Examples

<junitscript>
  <test classname="my.test.TestCase"/>
  <test script="tests/test.bsh"/>
</junitscript>

This runs first the normal JUnit TestCase, my.test.TestCase. Then it runs the BeanShell script, tests/test.bsh.

The tests are run in the same VM and no output will be generated unless the tests fail.

<junitscript printsummary="yes" fork="yes" haltonfailure="yes">
  <formatter type="plain"/>
  <test classname="my.test.TestCase" useargs="true"/>
  <test classname="my.test.TestCase2">
    <arg value="Hello!"/>
  </test>
  <test classname="my.test.TestCase3" useargs="false">
    <arg value="Hello!"/>
  </test>
</junitscript>

These tests demonstrate the changes in running normal test cases with arguments. In the first case and second cases a suite method will be searched for which takes a string array. In the first it will receive a zero length array, and in the second it will receive an array containing "Hello!". The third case is treated in the same way as if no arguments were given and the normal suite method without arguments will be looked for. All handle the situation where no appropriate suite method is found in the same way, creating a standard junit.framework.TestSuite for the class.

Moreover, these tests will be run a separate VM. At the end of the tests, a one-line summary will be printed. A detailed report of the tests can be found in TEST-my.test.TestCase[1,2,3].txt. The build process will be stopped if the test fails.

<junitscript printsummary="yes" haltonfailure="yes">
  <classpath>
    <pathelement location="${build.tests}"/>
    <pathelement path="${java.class.path}"/>
  </classpath>

  <formatter type="plain"/>

  <test script="my/test/TestCase.js" haltonfailure="no" outfile="result">
    <formatter type="xml"/>
  </test>

  <batchtest fork="yes" todir="${reports.tests}">
    <fileset dir="${src.tests}">
      <include name="**/*Test*.java"/>
      <exclude name="**/AllTests.js"/>
      <exclude name="**/AllTests.bsh"/>
    </fileset>
  </batchtest>
</junitscript>

Runs the javascript file, my/test/TestCase.js, in the same VM, ignoring the given CLASSPATH; only a warning is printed if this test fails. In addition to the plain text test results, for this test a XML result will be output to result.xml. Then, for each matching file in the directory defined for ${src.tests} a test is run in a separate VM. If a test fails, the build process is aborted. Results are collected in files named TEST-name.txt and written to ${reports.tests}.

Note

A good portion of this documentation is stolen directly from the good folks that made the junit task documentation.


Copyright © 2003 Hugh Leather All rights reserved.