= JUnit Platform Reporting

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

NOTE: The module also contains other `TestExecutionListener` implementations that can be
used to build custom reporting. See xref:running-tests/using-listeners-and-interceptors.adoc[] for details.

[[output-directory]]
== Output Directory

The JUnit Platform provides an `{OutputDirectoryCreator}` via `{EngineDiscoveryRequest}`
and `{TestPlan}` to registered xref:advanced-topics/engines.adoc[test engines] and
xref:running-tests/using-listeners-and-interceptors.adoc[listeners], respectively. Its root directory can be configured
via the following xref:running-tests/configuration-parameters.adoc[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]]
== Open Test Reporting

`{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
xref:running-tests/configuration-parameters.adoc[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 https://github.com/ota4j-team/open-test-reporting#git[Git extension schema] of open-test-reporting); defaults to `false`.
`junit.platform.reporting.open.xml.socket=<port>`::
  Optional port number to redirect events to a socket instead of a file. When specified, the
  listener will connect to `127.0.0.1:<port>` and send the XML events to the socket. The socket
  connection is automatically closed when the test execution completes.

If enabled, the listener creates an XML report file named `open-test-report.xml` in the
configured <<output-directory, output directory>>, unless the
`junit.platform.reporting.open.xml.socket` configuration parameter is set, in which case the
events are sent to the specified socket instead.

If xref:running-tests/capturing-standard-output-error.adoc[output capturing] is enabled, the captured output
written to `System.out` and `System.err` will be included in the report as well.

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:{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:{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>{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 xref:running-tests/console-launcher.adoc[], you can enable Open Test Reporting
output by setting the configuration parameters via `--config`:

[source,console,subs=attributes+]
----
$ java -jar junit-platform-console-standalone-{version}.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:

[source,console,subs=attributes+]
----
$ java -jar junit-platform-console-standalone-{version}.jar <OPTIONS> \
  --config-resource=configuration.properties
----

[[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 xref:running-tests/console-launcher.adoc[]
as well.
