■ 7.5—Customizing <junit> XML reports with XSLT
7.4 Reporting results in HTML with Ant’s <junitreport> task
◆ Problem
You need to easily and automatically report JUnit test results in a presentable HTML format.
◆ Background
You often need to make JUnit test results available as a report to a wider audience than the individual developer or QA engineer. The way to do this is with profes- sional looking file-based reports, which can be emailed as attachments or posted online in HTML format. Tabular, cross-linked HTML reports are useful for their hyperlinked navigability, especially if you need to navigate around hundreds or thousands of test results.
◆ Recipe
Use Ant’s <formatter> element to tell Ant to save the JUnit results in XML files.
You can specify <formatter> under either <junit> or <batchtest>, depending on how you set up your target to run JUnit tests. In the same target you use to run the JUnit tests, or in a separate target if you prefer, use the <junitreport> task with a nested <report> element to transform the XML result files’ output by the previous test run into a professional looking HTML report.
Listing 7.4 shows a simplified but functional Ant build script with one target for running a set of JUnit tests using <batchtest> and another for transforming the XML test results into HTML using the <junitreport> task.
<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="junit-run" name="myproject">
<property name="src.dir" location="${basedir}/src"/>
<property name="classes.dir" location="${basedir}/classes"/>
<property name="junit.reports.dir" location="${basedir}/junit"/>
Listing 7.4 build.xml using the <junitreport> task
203 Reporting results in HTML
with Ant’s <junitreport> task
<property name="junit.includes"
value="junit/cookbook/tests/**/*Test.java"/>
<property name="junit.excludes" value="**/AllTests.java"/>
<!-- clean, compile and other build targets omitted for brevity -->
<target name="junit-run"
description="=> run JUnit tests">
<mkdir dir="${junit.reports.dir}/xml"/>
<junit haltonfailure="no" fork="yes"
printsummary="withOutAndErr">
<classpath>
<pathelement location="${classes.dir}"/>
<pathelement path="${java.class.path}"/>
</classpath>
<batchtest fork="yes" todir="${junit.reports.dir}/xml"> B
<formatter type="xml"/> C
<fileset dir="${src.dir}">
<include name="${junit.includes}"/>
<exclude name="${junit.excludes}"/>
</fileset>
</batchtest>
</junit>
</target>
<target name="junit-report" depends="junit-run"
description="=> generate JUnit HTML report">
<junitreport todir="${junit.reports.dir}/xml">
<fileset dir="${junit.reports.dir}/xml">
<include name="TEST-*.xml"/>
</fileset>
<report format="frames" E
todir="${junit.reports.dir}"/> f
</junitreport>
</target>
</project>
The <batchtest> attribute todir specifies an output directory for individual test suite result files. For each test suite (test case class), batchtest generates a sepa- rate results file.
Select the xml formatter.
The <junitreport> attribute todir specifies an output directory for one merged XML file, containing the results of all the tests executed by <batchtest>. The
<fileset> specifies which test result files to include in the final report.
Choose the frames format to produce an HTML report that looks like Javadoc.
Specify the output directly for the final HTML report.
D
B C D E F
204 CHAPTER 7
Reporting JUnit results
Ant’s <junitreport> task comes with two embedded XSL stylesheets for generat- ing HTML reports: one with HTML frames and one without. The HTML frames report is organized similarly to standard Javadoc output with a three-paned, inter- linked frameset that facilitates navigation.
The noframes report comes out as one long HTML page, which is definitely harder to navigate than the frames version if you have more than a few unit tests.
To choose which style of report to generate, you specify either frames or no- frames to the format attribute of the <report> element. Internally, Ant maps these values to one of its two XSL stylesheets to produce the appropriate report format.
For more discussion of the reporting options, including non-HTML options and ways to customize the default capabilities, see the remaining recipes in this chapter.
◆ Discussion
Other than some dependency checking for whether to run certain batches of tests and some extra system properties (such as ${test.data.dir}) which one may want to declare, the targets shown in listing 7.4 are nearly identical to targets we have used on commercial projects to run and report JUnit tests in a team envi- ronment. We separate the running and reporting into two targets because this allows a developer to run just the tests without creating the HTML report. The printsummary="withOutAndErr" attribute setting of the <junit> task is used to output a summary of the test results to the console, so that a developer can see a summary of the test run without running the junit-report target to generate the HTML report. The report generation only takes a few seconds to execute, but it adds up over time if you are repeatedly running tests with Ant while working. We make the junit-report target depend on the junit-run target so that the release engineers can just call the junit-report target without having to call the junit- run target separately.
Using <junitreport> and its <report> element is the easiest way to produce professional looking JUnit HTML reports. If the default report formats provided by <report> are lacking or not to your taste, you can customize them or design your own reporting format, as discussed in recipe 7.5, “Customizing <junit> XML reports with XSLT” and recipe 7.6, “Extending Ant’s JUnit results format.”
◆ Related
■ 7.5—Customizing <junit> XML reports with XSLT
■ 7.6—Extending Ant’s JUnit results format
205 Customizing <junit> XML
reports with XSLT