Document in User Guide and release notes

Author: marcphilipp

documentation/src/docs/asciidoc/link-attributes.adoc

@@ -40,13 +40,15 @@ endif::[]
 :DiscoverySelectors_selectPackage:           {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectPackage(java.lang.String)[selectPackage]
 :DiscoverySelectors_selectUniqueId:          {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectUniqueId(java.lang.String)[selectUniqueId]
 :DiscoverySelectors_selectUri:               {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/DiscoverySelectors.html#selectUri(java.lang.String)[selectUri]
+:EngineDiscoveryRequest:                     {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/EngineDiscoveryRequest.html[EngineDiscoveryRequest]
 :FileSelector:                               {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/FileSelector.html[FileSelector]
 :HierarchicalTestEngine:                     {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/support/hierarchical/HierarchicalTestEngine.html[HierarchicalTestEngine]
 :IterationSelector:                          {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/IterationSelector.html[IterationSelector]
 :MethodSelector:                             {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/MethodSelector.html[MethodSelector]
 :ModuleSelector:                             {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ModuleSelector.html[ModuleSelector]
 :NestedClassSelector:                        {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/NestedClassSelector.html[NestedClassSelector]
 :NestedMethodSelector:                       {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/NestedMethodSelector.html[NestedMethodSelector]
+:OutputDirectoryProvider:                    {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/reporting/OutputDirectoryProvider.html[OutputDirectoryProvider]
 :PackageSelector:                            {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/PackageSelector.html[PackageSelector]
 :ParallelExecutionConfigurationStrategy:     {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/support/hierarchical/ParallelExecutionConfigurationStrategy.html[ParallelExecutionConfigurationStrategy]
 :UniqueIdSelector:                           {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/UniqueIdSelector.html[UniqueIdSelector]

documentation/src/docs/asciidoc/release-notes/release-notes-5.12.0-M1.adoc

@@ -40,11 +40,16 @@ JUnit repository on GitHub.
   `--select-file` and `--select-resource`.
 * `ConsoleLauncher` now accepts multiple values for all `--select` options.
 * Add `--select-unique-id` support to ConsoleLauncher.
+* Add `getOutputDirectoryProvider()` method to `EngineDiscoveryRequest` and `TestPlan` to
+  allow test engines to publish/attach files to containers and tests by calling
+  `EngineExecutionListener.fileEntryPublished(...)`. Registered `TestExecutionListeners`
+  can then access these files by overriding the `fileEntryPublished(...)` method.
 * The following improvements have been made to the open-test-reporting XML output:
   - Information about the Git repository, the current branch, the commit hash, and the
     current worktree status are now included in the XML report, if applicable.
   - A section containing JUnit-specific metadata about each test/container to the HTML
     report is now written by open-test-reporting when added to the classpath/module path
+  - Information about published files is now included as attachments.
 
 
 [[release-notes-5.12.0-M1-junit-jupiter]]
@@ -112,6 +117,8 @@ JUnit repository on GitHub.
 * When enabled via the `junit.jupiter.execution.timeout.threaddump.enabled` configuration
   parameter, an implementation of `PreInterruptCallback` is registered that writes a
   thread dump to `System.out` prior to interrupting a test thread due to a timeout.
+* `TestReporter` now allows publishing files for a test method or test class which can be
+  used to include them in test reports, such as the Open Test Reporting format.
 
 
 [[release-notes-5.12.0-M1-junit-vintage]]

documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-reporting.adoc

@@ -3,41 +3,46 @@
 
 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>>.
+<<junit-platform-reporting-open-test-reporting, Open Test Reporting>> and
+<<junit-platform-reporting-legacy-xml, legacy>>.
 
 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
+[[junit-platform-reporting-output-directory]]
+==== Output Directory
 
-`{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 JUnit Platform provides an `{OutputDirectoryProvider}` via
+`{EngineDiscoveryRequest}` and `{TestPlan}` to registered <<test-engines, test engines>>
+and <<running-tests-listeners, listeners>>, respectively. Its root directory can be
+configured via the following <<running-tests-config-params, configuration parameter>>:
 
-The `LegacyXmlReportGeneratingListener` is used by the <<running-tests-console-launcher>>
-as well.
+`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.
 
 [[junit-platform-reporting-open-test-reporting]]
-==== Open Test Reporting XML format
+==== 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
-<<running-tests-config-params>>:
+<<running-tests-config-params, configuration parameter>>:
 
 `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.
+If enabled, the listener creates an XML report file named `open-test-report.xml` in the
+configured <<junit-platform-reporting-output-directory, output directory>>.
 
 TIP: The {OpenTestReportingCliTool} can be used to convert from the event-based format to
 the hierarchical format which is more human-readable.
@@ -145,3 +150,13 @@ via the `--config-resource` option:
 $ java -jar junit-platform-console-standalone-{platform-version}.jar <OPTIONS> \
   --config-resource=configuration.properties
 ----
+
+[[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.

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -1077,8 +1077,9 @@ include::{testDir}/example/TestInfoDemo.java[tags=user_guide]
 * `{TestReporterParameterResolver}`: if a constructor or method parameter is of type
   `{TestReporter}`, the `TestReporterParameterResolver` will supply an instance of
   `TestReporter`. The `TestReporter` can be used to publish additional data about the
-  current test run. The data can be consumed via the `reportingEntryPublished()` method in
-  a `{TestExecutionListener}`, allowing it to be viewed in IDEs or included in reports.
+  current test run or attach files to it. The data can be consumed in a
+  `{TestExecutionListener}` via the `reportingEntryPublished()` or `fileEntryPublished()`
+  method, respectively. This allows them to be viewed in IDEs or included in reports.
 +
 In JUnit Jupiter you should use `TestReporter` where you used to print information to
 `stdout` or `stderr` in JUnit 4. Using `@RunWith(JUnitPlatform.class)` will output all