JUnitReport Task

## JUnitReport

### Description

Merge the individual XML files generated by the `JUnit` task and eventually apply a stylesheet on the resulting merged document to provide a browsable report of the testcases results.

Note: This task depends on external libraries not included in the Apache Ant distribution. See Library Dependencies for more information.

### Requirements

The task needs Apache Xalan 2.4.1+ or Xalan XSLTC (JDK 1.4 contains a version of Xalan 2.x, while JDK 1.5 ships with a version of XSLTC). JDK 1.4.2-01 and later ships with a bundled Xalan 2.4.1+, meaning that JDKs prior to version 1.4.2-01 won't work out of the box. The table below summarize the compatibility status.

Xalan | Sun JDK Bundle | Status |
--- | --- | --- | ---
2.4.1+ | JDK 1.4.2-01+ | OK
XSLTC | JDK 1.5.x | OK
2.x | JDK 1.4.x | Deprecated, use `${ant.home}/etc/junit-frames-xalan1.xsl` Upgrade Xalan using the JDK endorsement mechanism

In Ant 1.6.2, we had to decide between supporting Xalan 1/Xalan 2.4.1- and Xalan 2.4.1+/XSLTC, because there was no way to support both couples at the same time.

Since Ant 1.7, we dropped support for Xalan 1, because Xalan 1 was not available anymore for quite some time.

### Parameters

Attribute | Description | Required
--- | --- | ---
tofile | The name of the XML file that will aggregate all individual XML testsuites previously generated by the `JUnit` task. | No; defaults to `TESTS-TestSuites.xml`
todir | The directory where the file resulting from the individual XML testsuite aggregation should be written. | No; defaults to current directory

### Parameters specified as nested elements

#### fileset

`junitreport` collects individual xml files generated by the `JUnit` task using the nested `<FileSet>` element.

#### report

Generate a browsable report based on the document created by the merge.

### Parameters

Attribute | Description | Required
--- | --- | ---
format | The format of the generated report. Must be either noframes or frames. | No; defaults to frames
styledir | The directory where the stylesheets are defined. They must be conforming to the following conventions: frames format: the stylesheet must be named `junit-frames.xsl`, or `junit-frames-saxon.xsl` if you are using Saxon 9+. noframes format: the stylesheet must be named `junit-noframes.xsl`, or `junit-noframes-saxon.xsl` if you are using Saxon 9+. | No; defaults to embedded stylesheets
todir | The directory where the files resulting from the transformation should be written to. | No; defaults to current directory

Ant assumes the following concerning the frames and noframes formats:

- The frames format uses a stylesheet which is generating output only by redirecting.
- The noframes format does not use redirecting and generates one file called `junit-noframes.html`.

Custom versions of `junit-frames.xsl` or `junit-noframes.xsl` must adhere to the above conventions.

### Nested element of the report tag

#### param

Since Ant 1.7, the report tag supports nested `param` tags. These tags can pass XSL parameters to the stylesheet.

### Parameters

Attribute | Description | Required
--- | --- | ---
name | Name of the XSL parameter | Yes
expression | Text value to be placed into the `param`. Was originally intended to be an XSL expression. | Yes
if | The `param` will only be passed if this property is set. | No
unless | The `param` will not be passed if this property is set. | No

The built-in stylesheets support the following parameters:

XSL Parameter | Description | Required
--- | --- | ---
TITLE | Title used in `<title>` and `<h1>` tags | No; defaults to Unit Test Results

#### classpath

Since Ant 1.9.5. Like for the XSLT task, a nested `<classpath>` will be used to load the processor.

#### factory

Since Ant 1.9.5. Like for the XSLT task, a nested `<factory>` can be used to specify factory settings.

### Example of report

    <junitreport todir="./reports">
        <fileset dir="./reports">
            <include name="TEST-*.xml"/>
        </fileset>
        <report format="frames" todir="./report/html"/>
    </junitreport>

would generate a `TESTS-TestSuites.xml` file in the directory `reports` and generate the default framed report in the directory `report/html`.

### Example of report with XSL params

    <junitreport todir="${outputdir}">
        <fileset dir="${jrdir}">
            <include name="TEST-*.xml"/>
        </fileset>
        <report todir="${outputdir}/html"
                styledir="junitreport"
                format="frames">
            <param name="key1" expression="value1"/>
            <param name="key2" expression="value2"/>
        </report>
    </junitreport>

This example requires a file called `junitreport/junit-frames.xsl`. The XSL parameters key1 and key2 will be passed to the XSL transformation.