Advertisement

Summary
In this tutorial, Bill Venners shows you how to create a custom reporter for Artima SuiteRunner that formats unit test results in XML.

Artima SuiteRunner is a free open source testing toolkit for Java released under the Open Software License. You can use this tool with JUnit to run existing JUnit test suites, or standalone to create unit and conformance tests for Java APIs.

One advantage of using Artima SuiteRunner to run your JUnit tests is Artima SuiteRunner's reporter architecture. A reporter is an object that collects test results and presents them in some way to users. Artima SuiteRunner includes several build-in configurable reporters that can write to the standard error and output streams, files, and a graphical user interface. But Artima SuiteRunner also supports custom reporters. If you want to present results of tests in a different way, such as HTML, email, database, or log files, you can create your own custom reporter that presents results in those ways. This tutorial will show you how to create a custom reporter, using as an example a custom reporter named com.artima.examples.reporter.xml.ex1.XMLReporter (XMLReporter) that formats test results in XML.

Class XMLReporter was added to the Artima SuiteRunner distribution zip file in version 1.0beta5. If you have a release prior to 1.0beta5, please download the latest version of Artima SuiteRunner. Once you unzip the distribution ZIP file, you'll find the source code for XMLReporter in the suiterunner-[release]/example/com/artima/examples/reporter/xml/ex1 directory. You can also view the complete listing in HTML. Because XMLReporter.java is released under the Open Software License, you can use it as a template when creating your own custom Reporter.

Reporter's Event Handler Methods

To create a custom reporter, you create a class that implements interface org.suiterunner.Reporter (Reporter). Interface Reporter declares 13 methods: a setConfiguration method, a dispose method, and 11 event handler methods. In your custom Reporter, you must of course implement all 13 of these methods.

As tests run, the 11 event handler methods are notified of events such as test starting, test succeeded, and test failed. The event handler methods determine how your Reporter will present test results to the user. For example, if you want to present test results as HTML, you write event handler methods that produce HTML. Or, if you want to store test results in a database, you write event handler methods that insert records into that database. In this article, I will show you an XMLReporter whose event handler methods write XML to the standard output.

Figure 1 shows all 11 event handler methods and their meanings.

Figure 1. Reporter's Event Handler Methods