## JUnit

### 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 requires JUnit 3.0 or above.

Tests are defined by nested `test` or `batchtest` tags, see nested elements.

### Parameters

Attribute | Description | Required
printsummary | Print one line statistics for each testcase. | 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"
haltonfailure | Stop the build process if a test fails (errors are considered failures as well). | No, default is "off"
timeout | Cancel the individual tests if the don't finish in the given time (measured in milliseconds). Ignored if fork is disabled. | No
maxmemory | Max 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 "java"
dir | The directory to invoke the VM in. (ignored if fork is disabled) | No

### Nested Elements

`junit` supports a nested `<classpath>` element, that represents a PATH like structure.

#### jvmarg

If fork is enabled, additional parameters may be passed to the new VM via nested `<jvmarg>` attributes, for example:

    <junit fork="yes">
      <jvmarg value="-Djava.compiler=NONE"/>
    </junit>

would run the test in a VM without JIT.

`<jvmarg>` allows all attributes described in Command line arguments.

#### 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 two predefined formatters, one prints the test results in XML format, the other emits plain text. Custom formatters that need to implement `org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter` can be specified.

Attribute | Description | Required
type | Use a predefined formatter (either "xml" or "plain"). | Exactly one of these.
classname | Name of a custom formatter class.
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 true.

#### test

Defines a single test class.

Attribute | Description | Required
name | Name of the test class | 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
haltonfailure | Stop the build process if a test fails (errors are considered failures as well). Overrides value set in `<junit>`. | No
todir | Directory to write the reports to. | No, default is 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` using 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

Tests can define their own formatters via nested `<formatter>` elements.

#### batchtest

Define a number of tests based on pattern matching.

`batchtest` collects the included files from any number of nested `<fileset>`s. It then generates a test class name for each file that ends in `.java` or `.class`.

Attribute | Description | Required
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
haltonfailure | Stop the build process if a test fails (errors are considered failures as well). Overrides value set in `<junit>`. | No
todir | Directory to write the reports to. | No, default is 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

Batchtests can define their own formatters via nested `<formatter>` elements.

### Examples

    <junit>
      <test name="my.test.TestCase" />
    </junit>

Runs the test defined in `my.test.TestCase` in the same VM. No output will be generated unless the test fails.

    <junit printsummary="yes" fork="yes" haltonfailure="yes">
      <formatter type="plain" />
      <test name="my.test.TestCase" />
    </junit>

Runs the test defined in `my.test.TestCase` in a separate VM. At the end of the test a single line summary will be printed. A detailed report of the test can be found in `TEST-my.test.TestCase.txt`. The build process will be stopped if the test fails.

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

      <formatter type="plain" />

      <test name="my.test.TestCase" 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.java" /<
        </fileset>
      </batchtest>
    </junit>

Runs `my.test.TestCase` 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`.

For each matching file in the directory `${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}`.