## 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 has been tested with JUnit 3.0 up to JUnit 3.7, it won't work with versions prior to JUnit 3.0.

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 test's output (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.
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.

#### sysproperty

Use nested `<sysproperty>` 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). The attributes for this element are the same as for environment variables.

    <junit fork="no">
      <sysproperty key="basedir" value="${basedir}"/>
      ...
    </junit>

would run the test in ANT's VM and make the `basedir` property available to the test.

#### 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 emit 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 `org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter` can be specified.

Attribute | Description | Required
type | Use a predefined formatter (either "xml", "plain" or "brief"). | 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
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.
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
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.
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}`.

By using the errorProperty and failureProperty tags, 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.