◆ Problem
You want to output JUnit test reports in plain text.
2 If you run your tests from Ant’s <junit> tasks, then this option doesn’t exist, but that is no problem because Ant uses its own test runner.
199 Getting plain text results with Ant
◆ Background
Plain text reports are useful in contexts such as Telnet terminals, UNIX and DOS command shells, and inline in email messages. Ant has the built-in capability to produce two types of plain text JUnit test reports: brief and plain, which are useful in these contexts.
◆ Recipe
Use the brief or plain formatter type to output plain text reports to a file or to the console. The <junit>, <test>, and <batchtest> tasks all support the use of the nested <formatter> element. Table 7.1 describes the attributes of the <formatter>
element:
Table 7.1 Attributes of the <formatter> element of Ant’s <junit>, <test>, and
<batchtest> tasks for executing JUnit tests
The two formatting options we are concerned with in this recipe are the brief and plain types.
Listing 7.3 shows an Ant target for running a set of JUnit tests with the brief results formatter. You typically use this target in a complete Ant build script, of course. See recipe 7.4, “Reporting results in HTML with Ant’s <junitreport> task”
for a more complete build.xml example.
<!--property declarations, clean, compile and other build targets omitted to save page space -->
<target name="junit-run"
description="=> run JUnit tests">
<junit haltonfailure="no" fork="yes" printsummary="no"> B
<classpath>
Attribute Description
classname Lets you specify your own custom formatter implementation class instead of using xml, plain, or brief (see recipe 7.6, “Extending Ant's JUnit results format” for use of this extension feature).
extension Extension to append to files output by the formatter. Required if using a custom format- ter, but defaults to .txt for plain and brief, and .xml when using xml.
type Choice of xml, plain, or brief (unless using your own formatter implementation with the classname attribute).
usefile Whether to output formatted results to a file. Defaults to true.
Listing 7.3 junit-run Ant target using brief results formatter
200 CHAPTER 7
Reporting JUnit results
<pathelement location="${classes.dir}"/>
<pathelement path="${java.class.path}"/>
</classpath>
<batchtest fork="yes">
<formatter type="brief" C
usefile="no"/> D
<fileset dir="${src.dir}">
<include name="${junit.includes}"/>
<exclude name="${junit.excludes}"/>
</fileset>
</batchtest>
</junit>
</target>
Eliminate duplicate summary information—The brief text formatter already includes a summary at the end of a test run, so we set printsummary to no to avoid duplicat- ing that information.
Use brief formatter—This is how to specify the brief formatting type. As we have mentioned previously, the other available values are plain and xml.
Display results to console—We have decided to display test results to the console, rather than to a file, so we set usefile to no.
The brief format type output looks like this on the console (we ran this Ant build target with the -emacs flag to reduce logging adornments):
junit-run:
Testsuite: junit.cookbook.tests.extensions.ReloadableTestClassLoaderTest Tests run: 4, Failures: 0, Errors: 0, Time elapsed: 0.02 sec
Testsuite: junit.cookbook.tests.reporting.CookbookTestListenerTest Tests run: 4, Failures: 0, Errors: 0, Time elapsed: 0.591 sec
Change the formatter to type="plain" and run it again. You can see the plain type output prints the name and elapsed time of each test method:
junit-run:
Testsuite: junit.cookbook.tests.extensions.ReloadableTestClassLoaderTest Tests run: 4, Failures: 0, Errors: 0, Time elapsed: 0.03 sec
Testcase: testGetResourceString took 0.01 sec Testcase: testGetResourceAsStreamString took 0 sec Testcase: testLoadClassString took 0.02 sec Testcase: testIsJar took 0 sec
Testsuite: junit.cookbook.tests.reporting.CookbookTestListenerTest Tests run: 4, Failures: 0, Errors: 0, Time elapsed: 0.591 sec
B
C
D TE AM FL Y
Team-Fly®
201 Getting plain text results with Ant
Testcase: testStartTest took 0.561 sec Testcase: testEndTest took 0.01 sec Testcase: testAddError took 0.01 sec Testcase: testAddFailure took 0 sec
We set printsummary="no" when using these formatters because the summary out- put just repeats some of the same information output by these formatters.
Both of these formatters will output one text file per test case class if you run your tests using the <batchtest> task, since the <batchtest> task dynamically picks up tests to run based on pattern matching for file names. We have our includes/excludes pattern match the source files here, but you could use classes (we use source file names because it saves time in pattern matching a mix of outer and inner class file names). If you want to automatically send the output of the results as text in the body of an e-mail message (since attaching dozens or hun- dreds of text files would be unusable to recipients of the e-mail), you can use the Ant <concat> and <mail> tasks to do so with a target like this:
<target name="mail-report">
<property name="junit.report.file" value="junit-results.txt"/>
<concat destfile="${junit.report.file}">
<fileset dir="${junit.reports.dir}" includes="TEST-*.txt"/>
</concat>
<mail mailhost="mail.manning.net"
mailport="25"
subject="JUnit test results"
tolist="jb@manning.com,ss@manning.com"
messagefile="${junit.results.file}">
<from address="autobuild@manning.com"/>
</mail>
</target>
Each test result file is automatically named by the formatters as TEST-class- name.txt, so it’s easy to include them all in a <fileset>. The <concat> task concat- enates all these files into one new file named by the destfile attribute, which is set by a property in our example to ensure that the same file is picked up and used below in the <mail> task. The messagefile attribute of the <mail> task will use the file specified by ${junit.results.file} as the body of the email message that is sent. You could easily spruce up the target as shown to make it more dynamic, such as by using the <tstamp> task to create a time stamp property, which you could use to append to the email subject.
◆ Discussion
The easiest way to get off the ground with automated JUnit test results is by run- ning JUnit tests in Ant, and running the outputs into automated emails or HTML
202 CHAPTER 7
Reporting JUnit results
reports. Test results can be output in XML by the <junit> task and transformed to HTML using the <junitreport> task.
◆ Related