http://ant.apache.org/manual/Tasks/junit.html
Description
This task runs tests from the JUnit testing framework. The latest version of the framework can be found at http://www.junit.org. This task has been tested with JUnit 3.0 up to JUnit 3.8.2; it won't work with versions prior to JUnit 3.0. It also works with JUnit 4.0, including "pure" JUnit 4 tests using only annotations and no JUnit4TestAdapter.
Note: This task depends on external libraries not included in the Apache Ant distribution. See Library Dependencies for more information.
Note: You must have junit.jar available. You can do one of:
1. Put both junit.jar and ant-junit.jar in ANT_HOME/lib.
2. Do not put either in ANT_HOME/lib, and instead include their locations in your CLASSPATH environment variable.
3. Add both JARs to your classpath using -lib.
4. Specify the locations of both JARs using a element in a in the build file.
5. Leave ant-junit.jar in its default location in ANT_HOME/lib but include junit.jar in the passed to . (since Ant 1.7)
See the FAQ for details.
Tests are defined by nested test or batchtest tags (see nested elements).
Parameters
| Attribute | Description | Required |
| 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. |
| forkmode | Controls how many Java Virtual Machines get
created if you want to fork some tests. Possible values are
"perTest" (the default), "perBatch" and "once". "once" creates only
a single Java VM for all tests while "perTest" creates a new VM for
each TestCase class. "perBatch" creates a VM for each nested and
one collecting all nested s. Note that only tests with the same
settings of filtertrace, haltonerror,
haltonfailure, errorproperty and
failureproperty can share a VM, so even if you set
forkmode to "once", Ant may have to create more than a
single Java VM. This attribute is ignored for tests that don't get
forked into a new Java VM. since Ant 1.6.2 |
No; default is
perTest. |
| 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. When running multiple tests inside
the same Java VM (see forkMode), timeout applies to the time that
all tests use together, not to an individual test. |
No |
| maxmemory | Maximum amount of memory to allocate to the forked
VM. Ignored if fork is disabled.
Note: If you get java.lang.OutOfMemoryError:
Java heap space in some of your tests then you need to raise
the size like maxmemory="128m" |
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 |
| outputtoformatters | Since Ant 1.7.0. Send any output generated by tests to the test formatters. This is "true" by default. |
No |
| tempdir | Where Ant should place temporary files. Since Ant 1.6. | No; default is the project's base directory. |
| reloading | Whether or not a new classloader should be
instantiated for each test case. Ignore if fork is set to true. Since Ant
1.6. |
No; default is
true. |
| clonevm | If set to true true, then all system properties and the bootclasspath of the forked Java Virtual Machine will be the same as those of the Java VM running Ant. Default is "false" (ignored if fork is disabled). since Ant 1.7 | No |
| logfailedtests | When Ant executes multiple tests and doesn't stop on errors or failures it will log a "FAILED" message for each failing test to its logging system. If you set this option to false, the message will not be logged and you have to rely on the formatter output to find the failing tests. since Ant 1.8.0 | No |
| enableTestListenerEvents |
Whether Ant should send fine grained information
about the running tests to Ant's logging system at the verbose
level. Such events may be used by custom test listeners to show the
progress of tests. Defaults to false.Can be overridden by a magic property. since Ant 1.8.2 - Ant 1.7.0 to 1.8.1 behave as if this attribute was true by default. |
No |
By using the errorproperty and failureproperty attributes, it is possible to perform setup work (such as starting an external server), execute the test, clean up, and still fail the build in the event of a failure.
The filtertrace attribute condenses error and failure stack traces before reporting them. It works with both the plain and XML formatters. It filters out any lines that begin with the following string patterns:
"junit.framework.TestCase"
"junit.framework.TestResult"
"junit.framework.TestSuite"
"junit.framework.Assert."
"junit.swingui.TestRunner"
"junit.awtui.TestRunner"
"junit.textui.TestRunner"
"java.lang.reflect.Method.invoke("
"sun.reflect."
"org.apache.tools.ant."
"org.junit."
"junit.framework.JUnit4TestAdapter"
Nested Elements
The task supports a nested element that represents a PATH like structure.
As of Ant 1.7, this classpath may be used to refer to junit.jar as well as your tests and the tested code. jvmarg
If fork is enabled, additional parameters may be passed to the new VM via nested elements. For example:
...
would run the test in a VM without JIT.
allows all attributes described in Command-line Arguments. sysproperty
Use nested elements to specify system properties required by the class. These properties will be made available to the VM during the execution of the test (either ANT's VM or the forked VM, if fork is enabled). The attributes for this element are the same as for environment variables.
...
would run the test in ANT's VM and make the basedir property available to the test.