JUnit Platform Reporting

The junit-platform-reporting artifact contains TestExecutionListener implementations that generate XML test reports in two flavors: Open Test Reporting and legacy.

The module also contains other TestExecutionListener implementations that can be used to build custom reporting. See Using Listeners and Interceptors for details.

Output Directory

The JUnit Platform provides an OutputDirectoryCreator via EngineDiscoveryRequest and TestPlan to registered test engines and listeners, respectively. Its root directory can be configured via the following configuration parameter:

junit.platform.reporting.output.dir=<path>: Configure the output directory for reporting. By default, build is used if a Gradle build script is found, and target if a Maven POM is found; otherwise, the current working directory is used.

To create a unique output directory per test run, you can use the {uniqueNumber} placeholder in the path. For example, reports/junit-{uniqueNumber} will create directories like reports/junit-8803697269315188212. This can be useful when using Gradle’s or Maven’s parallel execution capabilities which create multiple JVM forks that run concurrently.

Open Test Reporting

OpenTestReportGeneratingListener writes an XML report for the entire execution in the event-based format specified by Open Test Reporting which supports all features of the JUnit Platform such as hierarchical test structures, display names, tags, etc.

The listener is auto-registered and can be configured via the following configuration parameters:

junit.platform.reporting.open.xml.enabled=true|false: Enable/disable writing the report; defaults to false.
junit.platform.reporting.open.xml.git.enabled=true|false: Enable/disable including information about the Git repository (see Git extension schema of open-test-reporting); defaults to false.

If enabled, the listener creates an XML report file named open-test-report.xml in the configured output directory.

If output capturing is enabled, the captured output written to System.out and System.err will be included in the report as well.

The Open Test Reporting CLI Tool can be used to convert from the event-based format to the hierarchical format which is more human-readable.

Gradle

For Gradle, writing Open Test Reporting compatible XML reports can be enabled and configured via system properties. The following samples configure its output directory to be the same directory Gradle uses for its own XML reports. A CommandLineArgumentProvider is used to keep the tasks relocatable across different machines which is important when using Gradle’s Build Cache.

Groovy DSL

dependencies {
    testRuntimeOnly("org.junit.platform:junit-platform-reporting:1.14.1")
}
tasks.withType(Test).configureEach {
    def outputDir = reports.junitXml.outputLocation
    jvmArgumentProviders << ({
        [
            "-Djunit.platform.reporting.open.xml.enabled=true",
            "-Djunit.platform.reporting.output.dir=${outputDir.get().asFile.absolutePath}"
        ]
    } as CommandLineArgumentProvider)
}

Kotlin DSL

dependencies {
    testRuntimeOnly("org.junit.platform:junit-platform-reporting:1.14.1")
}
tasks.withType<Test>().configureEach {
    val outputDir = reports.junitXml.outputLocation
    jvmArgumentProviders += CommandLineArgumentProvider {
		listOf(
			"-Djunit.platform.reporting.open.xml.enabled=true",
			"-Djunit.platform.reporting.output.dir=${outputDir.get().asFile.absolutePath}"
		)
	}
}

Maven

For Maven Surefire/Failsafe, you can enable Open Test Reporting output and configure the resulting XML files to be written to the same directory Surefire/Failsafe uses for its own XML reports as follows:

<project>
	<!-- ... -->
	<dependencies>
		<dependency>
			<groupId>org.junit.platform</groupId>
			<artifactId>junit-platform-reporting</artifactId>
			<version>1.14.1</version>
			<scope>test</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>3.5.3</version>
				<configuration>
					<properties>
						<configurationParameters>
							junit.platform.reporting.open.xml.enabled = true
							junit.platform.reporting.output.dir = target/surefire-reports
						</configurationParameters>
					</properties>
				</configuration>
			</plugin>
		</plugins>
	</build>
	<!-- ... -->
</project>

Console Launcher

When using the Console Launcher, you can enable Open Test Reporting output by setting the configuration parameters via --config:

$ java -jar junit-platform-console-standalone-1.14.1.jar <OPTIONS> \
  --config=junit.platform.reporting.open.xml.enabled=true \
  --config=junit.platform.reporting.output.dir=reports

Configuration parameters can also be set in a custom properties file supplied as a classpath resource via the --config-resource option:

$ java -jar junit-platform-console-standalone-1.14.1.jar <OPTIONS> \
  --config-resource=configuration.properties

Legacy XML format

LegacyXmlReportGeneratingListener generates a separate XML report for each root in the TestPlan. Note that the generated XML format is compatible with the de facto standard for JUnit 4 based test reports that was made popular by the Ant build system.

The LegacyXmlReportGeneratingListener is used by the Console Launcher as well.