[[junit-platform-reporting]]
=== JUnit Platform Reporting

The `junit-platform-reporting` artifact contains `{TestExecutionListener}` implementations
that generate XML test reports in two flavors:
<<junit-platform-reporting-legacy-xml, legacy>> and
<<junit-platform-reporting-open-test-reporting, Open Test Reporting>>.

NOTE: The module also contains other `TestExecutionListener` implementations that can be
used to build custom reporting. See <<running-tests-listeners>> for details.

[[junit-platform-reporting-legacy-xml]]
==== 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 <<running-tests-console-launcher>>
as well.

[[junit-platform-reporting-open-test-reporting]]
==== Open Test Reporting XML format

`{OpenTestReportGeneratingListener}` writes an XML report for the entire execution in the
event-based format specified by {OpenTestReporting} 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
<<running-tests-config-params>>:

`junit.platform.reporting.open.xml.enabled=true|false`::
  Enable/disable writing the report.
`junit.platform.reporting.output.dir=<path>`::
  Configure the output directory for the reports. 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.

If enabled, the listener creates an XML report file named
`junit-platform-events-<random-id>.xml` per test run in the configured output directory.

TIP: The {OpenTestReportingCliTool} 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.

[source,groovy,indent=0]
[subs=attributes+]
.Groovy DSL
----
dependencies {
    testRuntimeOnly("org.junit.platform:junit-platform-reporting:{platform-version}")
}
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)
}
----

[source,kotlin,indent=0]
[subs=attributes+]
.Kotlin DSL
----
dependencies {
    testRuntimeOnly("org.junit.platform:junit-platform-reporting:{platform-version}")
}
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:

[source,xml,indent=0]
[subs=attributes+]
----
<project>
	<!-- ... -->
	<dependencies>
		<dependency>
			<groupId>org.junit.platform</groupId>
			<artifactId>junit-platform-reporting</artifactId>
			<version>{platform-version}</version>
			<scope>test</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>{surefire-version}</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 <<running-tests-console-launcher>>, you can enable Open Test Reporting
output by setting the configuration parameters via `--config`:

[source,console,subs=attributes+]
----
$ java -jar junit-platform-console-standalone-{platform-version}.jar <OPTIONS> \
  --config=junit.platform.reporting.open.xml.enabled=true \
  --config=junit.platform.reporting.output.dir=reports
----
