Software Testing

Customize TestNG HTML Report

Customize TestNG HTML Report

TestNG provides a built-in HTML reporting mechanism that generates useful information about test execution. Whenever tests are executed using TestNG, a default HTML report is generated in the TestNG output directory.

The default TestNG report is useful for basic test execution analysis, but many automation projects require customized reports containing additional information such as test execution status, suite names, test methods, execution time, error messages, environment information, and custom styling.

TestNG provides an IReporter interface that allows automation engineers and developers to create customized reports according to their project requirements.

What Is a TestNG HTML Report?

A TestNG HTML report is a web-based report generated after TestNG completes the execution of a test suite. It can provide information about:

  • Passed test cases
  • Failed test cases
  • Skipped test cases
  • Test suites
  • Test methods
  • Execution duration
  • Failure information

The default TestNG reports are useful for understanding the overall test execution result, but they may not satisfy the reporting requirements of every automation framework.

Why Customize the TestNG HTML Report?

Organizations often customize TestNG reports to make test results easier to understand and integrate with their reporting processes.

A customized report can include:

  • Company branding and logos
  • Custom CSS styles
  • Project and build information
  • Environment details
  • Browser and operating system information
  • Execution timestamps
  • Test duration
  • Detailed exception messages
  • Custom summary dashboards
  • Pass, fail, and skip statistics

TestNG IReporter Interface

TestNG provides the IReporter interface to create custom reports.

By implementing this interface, you can control how test execution information is collected and how the final report is generated.

The interface provides the following important method:

void generateReport(
    List<XmlSuite> xmlSuites,
    List<ISuite> suites,
    String outputDirectory
);

generateReport() Method

The generateReport() method is invoked after the TestNG suite execution has completed. It receives information about the executed suites and the directory where the report can be generated.

generateReport(
    List<XmlSuite> xmlSuites,
    List<ISuite> suites,
    String outputFileDirectory
);

Parameters of generateReport()

Parameter Description
xmlSuites A list of XmlSuite objects representing the suites defined in the TestNG XML configuration.
suites A list of ISuite objects representing the executed TestNG suites.
outputDirectory The directory where the custom report can be generated.

What Is XmlSuite?

XmlSuite is a TestNG class that represents the <suite> element in a testng.xml configuration file.

For example:

<suite name="Regression Suite">
    ...
</suite>

The corresponding suite configuration can be represented by the TestNG XmlSuite object.

What Is ISuite?

ISuite is a TestNG interface that provides information about a TestNG test suite and its execution results.

Through ISuite, the custom reporter can access information about tests that were executed within the suite.

How to Customize TestNG HTML Report

The general process for creating a customized TestNG HTML report is:

  1. Create a Java class.
  2. Implement the IReporter interface.
  3. Implement the generateReport() method.
  4. Read test execution information from the TestNG suite objects.
  5. Generate HTML content.
  6. Write the HTML content to a file.
  7. Register the reporter with TestNG.
  8. Execute the test suite.

Step 1: Create a Custom Reporter Class

Create a Java class named CustomTestNGReporter and implement the IReporter interface.

import org.testng.IReporter;
import org.testng.ISuite;
import org.testng.ITestResult;
import org.testng.xml.XmlSuite;

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class CustomTestNGReporter implements IReporter {

    @Override
    public void generateReport(
            List<XmlSuite> xmlSuites,
            List<ISuite> suites,
            String outputDirectory) {

        StringBuilder html = new StringBuilder();

        html.append("<html>");
        html.append("<head>");
        html.append("<title>Custom TestNG Report</title>");

        html.append("<style>");
        html.append("body { font-family: Arial; margin: 30px; }");
        html.append("table { border-collapse: collapse; width: 100%; }");
        html.append("th, td { border: 1px solid #ccc; padding: 10px; }");
        html.append("th { background: #333; color: white; }");
        html.append(".pass { color: green; font-weight: bold; }");
        html.append(".fail { color: red; font-weight: bold; }");
        html.append(".skip { color: orange; font-weight: bold; }");
        html.append("</style>");

        html.append("</head>");
        html.append("<body>");

        html.append("<h1>Custom TestNG HTML Report</h1>");

        html.append("<table>");
        html.append("<tr>");
        html.append("<th>Suite</th>");
        html.append("<th>Test Method</th>");
        html.append("<th>Status</th>");
        html.append("</tr>");

        for (ISuite suite : suites) {

            Map<String, org.testng.ISuiteResult> suiteResults =
                    suite.getResults();

            for (org.testng.ISuiteResult suiteResult
                    : suiteResults.values()) {

                org.testng.ITestContext testContext =
                        suiteResult.getTestContext();

                addResults(
                        html,
                        suite.getName(),
                        testContext.getPassedTests().getAllResults()
                );

                addResults(
                        html,
                        suite.getName(),
                        testContext.getFailedTests().getAllResults()
                );

                addResults(
                        html,
                        suite.getName(),
                        testContext.getSkippedTests().getAllResults()
                );
            }
        }

        html.append("</table>");
        html.append("</body>");
        html.append("</html>");

        File reportFile =
                new File(outputDirectory, "custom-testng-report.html");

        try (FileWriter writer = new FileWriter(reportFile)) {
            writer.write(html.toString());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    private void addResults(
            StringBuilder html,
            String suiteName,
            List<ITestResult> results) {

        for (ITestResult result : results) {

            String status;

            if (result.getStatus() == ITestResult.SUCCESS) {
                status = "<span class='pass'>PASS</span>";
            } else if (result.getStatus() == ITestResult.FAILURE) {
                status = "<span class='fail'>FAIL</span>";
            } else {
                status = "<span class='skip'>SKIP</span>";
            }

            html.append("<tr>");
            html.append("<td>")
                .append(suiteName)
                .append("</td>");

            html.append("<td>")
                .append(result.getMethod().getMethodName())
                .append("</td>");

            html.append("<td>")
                .append(status)
                .append("</td>");

            html.append("</tr>");
        }
    }
}

Understanding the Custom Reporter Code

The reporter implements IReporter and overrides generateReport().

Inside the method, the code performs the following operations:

  • Creates an HTML document using StringBuilder.
  • Adds custom CSS for report styling.
  • Loops through all TestNG suites.
  • Reads the test execution results.
  • Identifies passed, failed, and skipped tests.
  • Adds the results to an HTML table.
  • Writes the final HTML into the TestNG output directory.

Step 2: Register the Custom Reporter

TestNG needs to know that the custom reporter should be executed. One convenient way to register it is with the @Listeners annotation.

import org.testng.annotations.Listeners;

@Listeners(CustomTestNGReporter.class)
public class LoginTest {

    // Test methods
}

You can also register listeners through your TestNG configuration or other listener registration mechanisms supported by your project.

Step 3: Create a TestNG Test Class

Consider the following simple TestNG test class:

import org.testng.Assert;
import org.testng.annotations.Test;

public class LoginTest {

    @Test
    public void validLoginTest() {
        Assert.assertTrue(true);
    }

    @Test
    public void invalidLoginTest() {
        Assert.assertTrue(false);
    }
}

When this test suite runs, TestNG executes the test methods and the custom reporter receives the execution information after the suite completes.

Step 4: Run the TestNG Suite

A typical testng.xml file can be used to execute the tests:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">

<suite name="Regression Suite">

    <test name="Login Tests">
        <classes>
            <class name="LoginTest"/>
        </classes>
    </test>

</suite>

After execution, TestNG creates its standard reports and the custom reporter creates an additional HTML report.

Where Is the Custom HTML Report Generated?

The outputDirectory supplied to generateReport() identifies the location where the custom HTML report can be written.

In a typical Maven-based project, TestNG commonly writes reports under the test-output directory.

For example:

test-output/
│
├── index.html
├── emailable-report.html
├── testng-results.xml
└── custom-testng-report.html

The exact generated files can vary depending on the TestNG version and project configuration.

Default TestNG Emailable Report

The default TestNG emailable report provides a compact representation of the test execution results. It is useful for quickly sharing basic execution information with developers, testers, and project stakeholders.

A typical default report contains information such as:

  • Test methods
  • Pass and failure status
  • Execution time
  • Test suites
  • Failure details

However, the default report may not provide the project-specific layout, branding, dashboards, filters, and additional metadata required by an automation framework.

Adding Test Execution Duration

You can customize the report further by displaying how long each test method took to execute.

long startTime = result.getStartMillis();
long endTime = result.getEndMillis();

long duration = endTime - startTime;

The duration can then be displayed in the HTML report:

html.append("<td>")
    .append(duration)
    .append(" ms")
    .append("</td>");

Adding Failure Messages

For failed tests, displaying the exception message can make the report more useful for debugging.

if (result.getStatus() == ITestResult.FAILURE
        && result.getThrowable() != null) {

    html.append("<td>")
        .append(result.getThrowable().getMessage())
        .append("</td>");
}

In production-quality reporting code, HTML escaping should be applied to dynamic values before inserting them into an HTML document.

Creating a TestNG Summary Dashboard

A customized report can also display an execution summary at the top of the page.

Total Tests  : 100
Passed       : 82
Failed       : 12
Skipped      : 6

You can calculate these values from the TestNG result collections and display them using HTML cards, tables, or charts.

Example Customized Report Layout

A professional TestNG HTML report can contain sections such as:

Section Example Information
Project Information Project name, build number, environment
Execution Summary Total, passed, failed, skipped
Suite Summary Suite names and execution results
Test Details Method, status, duration
Failure Details Exception and failure information
Environment Browser, operating system, Java version

Advantages of a Customized TestNG Report

Custom TestNG HTML reporting provides several benefits for automation projects.

Better Readability

You can design the report specifically for your team instead of relying on the default layout.

Project-Specific Information

Custom metadata such as environment, browser, release version, build number, and execution owner can be included.

Improved Debugging

Detailed failure messages, stack traces, test durations, and additional execution information can make troubleshooting easier.

Branding

Organizations can add project logos, custom titles, CSS, headers, and footers.

CI/CD Integration

Customized reports can be generated as build artifacts and published as part of continuous integration and continuous delivery pipelines.

Best Practices for TestNG HTML Reports

  • Keep the report simple and easy to read.
  • Display overall execution statistics prominently.
  • Include enough failure information for debugging.
  • Display test duration for performance analysis.
  • Use CSS rather than embedding excessive formatting in every HTML element.
  • Escape dynamic test data before inserting it into HTML.
  • Keep report generation separate from test business logic.
  • Generate the report in the TestNG-provided output directory.
  • Publish the report as a CI/CD build artifact when appropriate.

Common Mistakes to Avoid

Generating the Report Before Test Execution Completes

The IReporter mechanism is intended for final report generation after the suite execution has completed. Make sure the report is based on the final available results.

Mixing Reporting Logic With Test Logic

A test method should focus on testing the application. Report generation should remain inside dedicated reporting or listener classes.

Ignoring Failed Test Details

A report that shows only PASS or FAIL is often not enough. Include useful failure information whenever practical.

Not Escaping HTML Content

Test names, exception messages, and other dynamic values can contain characters that interfere with HTML rendering. Proper HTML escaping helps prevent malformed reports.

TestNG IReporter vs Default TestNG Report

Feature Default Report Custom IReporter
Basic Test Results Yes Yes
Custom HTML Layout Limited Yes
Custom CSS Not controlled by your framework Yes
Custom Metadata Limited Yes
Company Branding Not designed for this Yes
Custom Dashboard Limited Yes

When Should You Use IReporter?

The IReporter interface is a good choice when the standard TestNG output does not meet your reporting requirements and you need direct control over the final HTML report.

For example, a Selenium or API automation framework may use a custom reporter to combine TestNG results with browser, environment, build, and execution information.

Conclusion

TestNG provides a convenient default HTML reporting mechanism, but automation frameworks often need more control over how test results are presented.

The IReporter interface provides a way to generate a customized report by implementing the generateReport() method:

generateReport(
    List<XmlSuite> xmlSuites,
    List<ISuite> suites,
    String outputFileDirectory
);

By using IReporter, you can create customized HTML reports with project branding, execution summaries, test status, execution duration, failure information, environment details, and other project-specific data.

This makes TestNG reporting much more flexible and can be especially useful for Selenium, API, and other Java-based test automation frameworks integrated with CI/CD pipelines.

Frequently Asked Questions

What is IReporter in TestNG?

IReporter is a TestNG interface that can be implemented to generate customized test execution reports.

What is the generateReport() method in TestNG?

generateReport() is the method implemented by a custom IReporter. It receives TestNG suite information and the output directory and is used to generate the final custom report.

Can I change the default TestNG HTML report?

Instead of modifying TestNG’s built-in report directly, you can implement IReporter and generate your own HTML report based on TestNG execution results.

Where does TestNG generate reports?

TestNG uses an output directory for its generated results. In many common Maven/TestNG setups, this is the test-output directory, although the exact location can depend on the project and execution configuration.

Can I add screenshots to a custom TestNG report?

Yes. A custom report can be extended to reference or embed screenshots captured during test execution, provided the reporting framework manages the screenshot files correctly.

—

Customize TestNG HTML Report

In this tutorial, we will customize the default TestNG HTML report. When ever we execute tests with TestNG, it will generate a default html report with basic information.

TestNG has provided an ability to implement ‘IReporter‘ an interface which can be implemented to generate a customized report by users. It has ‘generateReport()‘ method which will be invoked after all the suite has completed its execution and gives the report into the specified output directory.

generateReport() method

//XmlSuite is a class describes the tag <suite> in testng.xml
//ISuite is an interface defining a Test Suite.

generateReport(List<XmlSuite> xmlSuites, List<ISuite> suites, 
String outputFileDirectory)

 

The below is the default TestNG emailable re