ReportNG

An HTML/XML Reporting Plug-in for TestNG

Current Stable Version: 1.2.2 Source Code

ReportNG is a simple HTML reporting plug-in for the TestNG unit-testing framework. It is intended as a replacement for the default TestNG HTML report. The default report is comprehensive but is not so easy to understand at-a-glance. ReportNG provides a simple, colour-coded view of the test results.

ReportNG generates 100% valid XHTML 1.0 files. The output can be customised by over-riding the default stylesheet with your own CSS file.

Since version 0.9.0, ReportNG also includes a second reporter that produces JUnit format XML output. This enables TestNG to integrate with tools, such as Hudson, that understand these XML files. This is an alternative to the JUnit XML reporter that is provided with TestNG. The ReportNG implementation maps each test class to a single <testsuite> element, resulting in one XML file per test class. This is different from the approach taken by the core TestNG implementation. The ReportNG version of the JUnit reporter ignores TestNG's notion of suites to produce output that is closer to what you would get if you were using JUnit.

The current version is 1.2.2, which has been tested with TestNG 6.14.3.

Sample Reports

A very basic sample report with some test failures. This report demonstrates most of the features of the reporter.
The same report with a custom stylesheet.

How to use ReportNG

Apache Ant

To use the reporting plug-in, set the listeners attribute of the testng element in your Ant build file. This attribute takes a comma-separated list of reporter class names. The class names for the ReportNG reporters are:

    org.uncommons.reportng.HTMLReporter
    org.uncommons.reportng.JUnitXMLReporter

You may also want to disable the default TestNG reporters by setting the useDefaultListeners attribute to "false".

Your Ant task will probably look something like this:

    <testng classpathref="test-path"
            outputdir="${test-results.dir}"
            haltonfailure="true"
            useDefaultListeners="false"
            listeners="org.uncommons.reportng.HTMLReporter,org.uncommons.reportng.JUnitXMLReporter">
      <xmlfileset dir="." includes="testng.xml"/>
      <sysproperty key="org.uncommons.reportng.title" value="My Test Report"/>
    </testng>

The reportng-1.1.4.jar and velocity-dep-1.4.jar files must be included in the classpath used to run the tests.

Maven

Add ReportNG as a Maven dependency

        <dependency>
                <groupId>org.testng</groupId>
                <artifactId>reportng</artifactId>
                <version>1.2.2</version>
                <scope>test</scope>
        </dependency>

Now ReportNG reports will be generated for each test run. ReportNG wires-in the below mentioned mandatory listeners via Service Providers Interface, so no additional work needs to be done to start consuming them.

org.uncommons.reportng.HTMLReporter
org.uncommons.reportng.JUnitXMLReporter

Other Build Systems

If you are using Gradle, Tomek Kaczanowski has written these instructions on how to use ReportNG.

If you are using the command line, an IDE plug-in or some other build system, please refer to the TestNG documentation to find out how to register custom listeners/reporters.

Supported System Properties

The following optional system properties can be set (via nested <sysproperty> elements within the <testng> element) in order to customise the report output:

org.uncommons.reportng.coverage-report: A relative or absolute URL that links to a test coverage report.
org.uncommons.reportng.escape-output: Used to turn off escaping for log output in the reports (not recommended). The default is for output to be escaped, since this prevents characters such as '<' and '&' from causing mark-up problems. If escaping is turned off, then log text is included as raw HTML/XML, which allows for the insertion of hyperlinks and other nasty hacks.
org.uncommons.reportng.failures-only: Defaults to "false". If set to "true", the generated report will not list successful tests.
org.uncommons.reportng.frames: Defaults to "true". If set to "false", generates the HTML report without using a frameset. No navigation page is generated and the overview page becomes the index page.
org.uncommons.reportng.locale: Over-rides the default locale for localised messages in generated reports. If not specified, the JVM default locale is used. If there are no translations available for the selected locale the default English messages are used instead. This property should be set to an ISO language code (e.g. "en" or "fr") or to an ISO language code and an ISO country code separated by an underscore (e.g. "en_US" or "fr_CA"). ReportNG 1.1 includes translations for the following languages: English, French and Portuguese. If you would like to contribute translations for other languages, please open an issue in the issue tracker and attach a translated version of the properties file.
org.uncommons.reportng.show-expected-exceptions: Set to "true" or "false" to specify whether the stack-traces of expected exceptions should be included in the output for passed test cases. The default is "false" because the presence of stack-traces for successful tests may be confusing.
org.uncommons.reportng.stylesheet: The path to a custom CSS file that over-rides some or all of the default styles used by the HTMLReporter. This allows the appearance of reports to be customised. See the default stylesheet for the classes and selectors that can be styled. For an example, see this version of the sample report, which uses the bundled hudsonesque.css file to customise the report's appearance.
org.uncommons.reportng.title: Used to over-ride the report title.
org.uncommons.reportng.xml-dialect: Controls the XML generated by JUnitXMLReporter. If set to "testng" (the default), then skipped tests appear as "skipped" in the XML. This is suitable for use with tools such as Hudson that understand the TestNG dialect of the XML format. Other tools, such as Ant's junitreport task, do not have a notion of skipped tests. For these tools the dialect can be set to "junit" and skipped tests will be marked as failures.
org.uncommons.reportng.velocity-log: Since version 1.1.3, ReportNG will no longer generate a Velocity log file by default. If you want a log file you should set this property to "true".