JUnit 5 HTML Reports using Maven Surefire Report Plugin

Learn to create an HTML report for the test execution results using JUnit 5. In this example, we are creating an HTML report for JUnit-Examples project available on Github.

1. Maven Surefire Report Plugin

To generate an HTML report, you can use the Maven Surefire Report Plugin, which converts the test results into readable HTML files.

1.1. Add Plugin Dependency

Add the latest version of maven-surefire-report-plugin into the reporting section of pom.xml.

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.8.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Maven Surefire Plugin for running JUnit tests -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.0.0-M5</version>
        </plugin>
    </plugins>
</build>

<reporting>
    <plugins>
        <!-- Surefire Report Plugin to generate HTML reports -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-report-plugin</artifactId>
            <version>2.22.2</version>
        </plugin>
    </plugins>
</reporting>

1.2. How It Works?

When we run the JUnit tests with Maven Surefire plugin, it generates the reports in plain-text and XML formats.

mvn test

When invoked, the Surefire Report plugin parses the generated target/surefire-reports/TEST-*.xml files and renders them using DOXIA (content generation framework), creating the test results’ HTML interface version.

Notice that by default, the plugin is not attached to any of the core phases, which we generally invoke using mvn command. So, we have to call it directly from the command line:

mvn surefire-report:report

This command will generate an HTML report from the XML results and place it in the target/site directory. If we open the generated HTML report, it will include sections such as:

• Test details: Each test method’s result with a breakdown of execution time, status, and any failure messages.
• Overview of tests: Total tests run, tests passed, tests failed, and tests with errors.

2. Cofiguration Options

We can further customize the Surefire Report Plugin to include additional details about the test environment or customize the report output.

2.1. Customizing the Output Directory

We can change the output directory for the reports by adding a configuration block in the plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-report-plugin</artifactId>
    <version>2.22.2</version>
    <configuration>
        <outputDirectory>custom-report-directory</outputDirectory>
    </configuration>
</plugin>

2.2. Aggregating Reports for Multi-Module Projects

If we have a multi-module Maven project, we can aggregate the test results into a single report using the following configuration:

<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-report-plugin</artifactId>
            <version>2.22.2</version>
            <configuration>
                <aggregate>true</aggregate>
            </configuration>
        </plugin>
    </plugins>
</reporting>

2.3. Showing Only Failed Tests

By default, the Surefire Report Plugin shows all the successes and failures in the generated HTML report. To display the failed tests only, the property showSuccess should be set to false.

<reporting>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-surefire-report-plugin</artifactId>
			<version>2.22.2</version>
			<configuration>
				<showSuccess>false</showSuccess>
			</configuration>
		</plugin>
	</plugins>
</reporting>

2.4. Custom Report Name

To set the custom file name for the generated HTML report, the outputName property should be set to the desired name.

After executing mvn site, the generated report file is named JUnit-Examples-Test-Report.html.

<reporting>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-surefire-report-plugin</artifactId>
			<version>2.22.2</version>
			<configuration>
				<outputName>JUnit-Examples-Test-Report</outputName>
			</configuration>
		</plugin>
	</plugins>
</reporting>

2.5. Source Code Reference for Failed Tests

For the failed tests, we may wish to report the line number at which they failed. This can be done using the maven-jxr-plugin plugin.

Add this plugin to the reporting section of pom.xml file for reporting the line numbers.

<reporting>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-surefire-report-plugin</artifactId>
			<version>2.22.2</version>
			<configuration>
				<outputName>JUnit-Examples-Test-Report</outputName>
			</configuration>
		</plugin>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-jxr-plugin</artifactId>
			<version>3.1.1</version>
		</plugin>
	</plugins>
</reporting>

3. Summary

In this guide, we learned how to:

• Use the Maven Surefire Plugin to run tests.
• Configure the Maven Surefire Report Plugin to generate HTML reports.
• View and customize the generated HTML reports.

Happy Learning !!