Merge branch 'main' into marc/5098-package-private-hidden-methods

marcphilipp · marcphilipp · commit 94ba3f15789f · 2025-10-29T16:57:36.000+01:00
diff --git a/documentation/src/docs/asciidoc/release-notes/release-notes-6.1.0-M1.adoc b/documentation/src/docs/asciidoc/release-notes/release-notes-6.1.0-M1.adoc
@@ -28,6 +28,12 @@ repository on GitHub.
 
 * Support for creating a `ModuleSelector` from a `java.lang.Module` and using
   its classloader for test discovery.
+* `OpenTestReportGeneratingListener` now supports redirecting XML events to a socket via
+  the new `junit.platform.reporting.open.xml.socket` configuration parameter. When set to a
+  port number, events are sent to `127.0.0.1:<port>` instead of being written to a file.
+* Allow implementations of `HierarchicalTestEngine` to specify which nodes require the
+  global read lock by overriding the `Node.isGlobalReadLockRequired()` method to return
+  `false`.
 
 
 [[release-notes-6.1.0-M1-junit-jupiter]]
diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-reporting.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-reporting.adoc
@@ -42,9 +42,15 @@ The listener is auto-registered and can be configured via the following
   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 <<junit-platform-reporting-output-directory, output directory>>.
+configured <<junit-platform-reporting-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 <<running-tests-capturing-output, output capturing>> is enabled, the captured output
 written to `System.out` and `System.err` will be included in the report as well.
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -1,7 +1,7 @@
 [versions]
 ant = "1.10.15"
 apiguardian = "1.1.2"
-asciidoctorj-pdf = "2.3.21"
+asciidoctorj-pdf = "2.3.23"
 asciidoctor-plugins = "4.0.5" # Check if workaround in documentation.gradle.kts can be removed when upgrading
 assertj = "3.27.6"
 bnd = "7.1.0"
diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar
diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties
@@ -1,7 +1,7 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionSha256Sum=a17ddd85a26b6a7f5ddb71ff8b05fc5104c0202c6e64782429790c933686c806
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip
+distributionSha256Sum=df67a32e86e3276d011735facb1535f64d0d88df84fa87521e90becc2d735444
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.2.0-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/InvocationInterceptor.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/InvocationInterceptor.java
@@ -45,6 +45,16 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)}. See
+ * {@link #interceptTestClassConstructor(Invocation, ReflectiveInvocationContext, ExtensionContext)}
+ * for details.
+ *
  * @since 5.5
  * @see Invocation
  * @see ReflectiveInvocationContext
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ParameterResolver.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ParameterResolver.java
@@ -48,6 +48,15 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)} to require a
+ * test-method scoped {@code ExtensionContext}.
+ *
  * @since 5.0
  * @see #supportsParameter(ParameterContext, ExtensionContext)
  * @see #resolveParameter(ParameterContext, ExtensionContext)
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstanceFactory.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstanceFactory.java
@@ -43,6 +43,17 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)} to require a
+ * test-method scoped {@code ExtensionContext}. See
+ * {@link #createTestInstance(TestInstanceFactoryContext, ExtensionContext)} for
+ * further details.
+ *
  * @since 5.3
  * @see #createTestInstance(TestInstanceFactoryContext, ExtensionContext)
  * @see TestInstanceFactoryContext
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstancePostProcessor.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstancePostProcessor.java
@@ -33,6 +33,16 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)} to require a
+ * test-method scoped {@code ExtensionContext}. See
+ * {@link #postProcessTestInstance(Object, ExtensionContext)} for further details.
+ *
  * @since 5.0
  * @see #postProcessTestInstance(Object, ExtensionContext)
  * @see TestInstancePreDestroyCallback
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstancePreConstructCallback.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstancePreConstructCallback.java
@@ -38,6 +38,17 @@
  * <p>Consult the documentation in {@link Extension} for details on constructor
  * requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)} to require a
+ * test-method scoped {@code ExtensionContext}. See
+ * {@link #preConstructTestInstance(TestInstanceFactoryContext, ExtensionContext)}
+ * for further details.
+ *
  * @since 5.9
  * @see TestInstancePreDestroyCallback
  * @see TestInstanceFactory
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstantiationAwareExtension.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestInstantiationAwareExtension.java
@@ -14,79 +14,119 @@
 import static org.apiguardian.api.API.Status.MAINTAINED;
 
 import org.apiguardian.api.API;
-import org.junit.jupiter.api.TestInstance;
-import org.junit.jupiter.api.extension.ExtensionContext.Store;
 
 /**
- * Interface for {@link Extension Extensions} that are aware and can influence
- * the instantiation of test instances.
+ * {@code TestInstantiationAwareExtension} defines the API for {@link Extension
+ * Extensions} that are aware of or influence the instantiation of test classes.
  *
- * <p>This interface is not intended to be implemented directly. Instead, extend
- * one of its sub-interfaces.
+ * <p>This interface is not intended to be implemented directly. Instead, extensions
+ * should implement one of the sub-interfaces listed below.
+ *
+ * <ul>
+ * <li>{@link InvocationInterceptor}</li>
+ * <li>{@link ParameterResolver}</li>
+ * <li>{@link TestInstancePreConstructCallback}</li>
+ * <li>{@link TestInstancePostProcessor}</li>
+ * <li>{@link TestInstanceFactory}</li>
+ * </ul>
+ *
+ * <p>See {@link #getTestInstantiationExtensionContextScope(ExtensionContext)} for
+ * further details.
  *
  * @since 5.12
- * @see InvocationInterceptor#interceptTestClassConstructor
- * @see ParameterResolver
- * @see TestInstancePreConstructCallback
- * @see TestInstancePostProcessor
- * @see TestInstanceFactory
  */
 @API(status = MAINTAINED, since = "5.13.3")
 public interface TestInstantiationAwareExtension extends Extension {
 
 	/**
-	 * Whether this extension should receive a test-scoped
-	 * {@link ExtensionContext} during the instantiation of test instances.
+	 * Determine whether this extension should receive a test-method scoped
+	 * {@link ExtensionContext} during the instantiation of test classes or
+	 * processing of test instances.
 	 *
-	 * <p>If an extension returns
-	 * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} from this method,
-	 * the following extension methods will be called with a test-scoped
-	 * {@link ExtensionContext} instead of a class-scoped one, unless the
-	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used:
+	 * <p>If an extension returns {@link ExtensionContextScope#TEST_METHOD TEST_METHOD}
+	 * from this method, methods defined in the following extension APIs will be
+	 * called with a test-method scoped {@code ExtensionContext} instead of a
+	 * test-class scoped context. Note, however, that a test-class scoped context
+	 * will always be supplied if the
+	 * {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
+	 * test instance lifecycle is used.
 	 *
 	 * <ul>
-	 * <li>{@link InvocationInterceptor#interceptTestClassConstructor}</li>
-	 * <li>{@link ParameterResolver} when resolving constructor parameters</li>
+	 * <li>{@link InvocationInterceptor}: only the
+	 * {@link InvocationInterceptor#interceptTestClassConstructor
+	 * interceptTestClassConstructor(...)} method</li>
+	 * <li>{@link ParameterResolver}: only when resolving constructor parameters</li>
 	 * <li>{@link TestInstancePreConstructCallback}</li>
 	 * <li>{@link TestInstancePostProcessor}</li>
 	 * <li>{@link TestInstanceFactory}</li>
 	 * </ul>
 	 *
-	 * <p>In such cases, implementations of these extension callbacks can
-	 * observe the following differences:
+	 * <p>When a test-method scoped {@code ExtensionContext} is supplied, implementations
+	 * of the above extension APIs will observe the following differences.
 	 *
 	 * <ul>
-	 * <li>{@link ExtensionContext#getElement() getElement()} may refer to the
-	 * test method and {@link ExtensionContext#getTestClass() getTestClass()}
-	 * may refer to a nested test class.
-	 * Use {@link TestInstanceFactoryContext#getTestClass()} to get the class
-	 * under construction.</li>
-	 * <li>{@link ExtensionContext#getTestMethod() getTestMethod()} is no longer
-	 * empty, unless the {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS}
-	 * lifecycle is used.</li>
-	 * <li>If the callback adds a new {@link Store.CloseableResource} or
-	 * {@link AutoCloseable} to the {@link Store Store} (unless the
-	 * {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
-	 * configuration parameter is set to {@code false}), then
-	 * the resource is closed just after the instance is destroyed.</li>
-	 * <li>The callbacks can now access data previously stored by
-	 * {@link TestTemplateInvocationContext}, unless the
-	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.</li>
+	 *   <li>
+	 *     {@link ExtensionContext#getElement() getElement()} may refer to the
+	 *     test method.
+	 *   </li>
+	 *   <li>
+	 *     {@link ExtensionContext#getTestClass() getTestClass()} may refer to a
+	 *     nested test class.
+	 *     <ul>
+	 *       <li>
+	 *         For {@link TestInstancePostProcessor}, use {@code testInstance.getClass()}
+	 *         to get the test class associated with the supplied instance.
+	 *       </li>
+	 *       <li>
+	 *         For {@link TestInstanceFactory} and {@link TestInstancePreConstructCallback},
+	 *         use {@link TestInstanceFactoryContext#getTestClass()} to get the
+	 *         class under construction.
+	 *       </li>
+	 *       <li>
+	 *         For {@link ParameterResolver}, when resolving a parameter for a
+	 *         constructor, ensure that the
+	 *         {@link ParameterContext#getDeclaringExecutable() Executable} is a
+	 *         {@link java.lang.reflect.Constructor Constructor}, and then use
+	 *         {@code constructor.getDeclaringClass()} to get the test class
+	 *         associated with the constructor.
+	 *       </li>
+	 *     </ul>
+	 *   </li>
+	 *   <li>
+	 *     {@link ExtensionContext#getTestMethod() getTestMethod()} is no longer
+	 *     empty, unless the
+	 *     {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
+	 *     test instance lifecycle is used.
+	 *   </li>
+	 *   <li>
+	 *     If the extension adds a {@link ExtensionContext.Store.CloseableResource
+	 *     CloseableResource} or {@link AutoCloseable} to the
+	 *     {@link ExtensionContext.Store Store} (unless the
+	 *     {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
+	 *     configuration parameter is set to {@code false}), then the resource will
+	 *     be closed just after the instance is destroyed.
+	 *   </li>
+	 *   <li>
+	 *     Extensions can now access data previously stored by a
+	 *     {@link TestTemplateInvocationContext}, unless the
+	 *     {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
+	 *     test instance lifecycle is used.
+	 *   </li>
 	 * </ul>
 	 *
 	 * <p><strong>Note</strong>: The behavior which is enabled by returning
 	 * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} from this method
 	 * will become the default in future versions of JUnit. To ensure forward
-	 * compatibility, extension implementors are therefore advised to opt in,
-	 * even if they don't require the new functionality.
+	 * compatibility, extension authors are therefore advised to opt into this
+	 * feature, even if they do not require the new functionality.
 	 *
-	 * @implNote There are no guarantees about how often this method is called.
-	 *           Therefore, implementations should be idempotent and avoid side
-	 *           effects. They may, however, cache the result for performance in
-	 *           the {@link Store Store} of the supplied
-	 *           {@link ExtensionContext}, if necessary.
+	 * @implNote There are no guarantees about how often this method will be called.
+	 * Therefore, implementations should be idempotent and avoid side effects.
+	 * If computation of the return value is costly, implementations may wish to
+	 * cache the result in the {@link ExtensionContext.Store Store} of the supplied
+	 * {@code ExtensionContext}.
 	 * @param rootContext the root extension context to allow inspection of
-	 *                    configuration parameters; never {@code null}
+	 * configuration parameters; never {@code null}
 	 * @since 5.12
 	 */
 	@API(status = MAINTAINED, since = "5.13.3")
@@ -96,25 +136,25 @@ default ExtensionContextScope getTestInstantiationExtensionContextScope(Extensio
 
 	/**
 	 * {@code ExtensionContextScope} is used to define the scope of the
-	 * {@link ExtensionContext} passed to an extension during the instantiation
-	 * of test instances.
+	 * {@link ExtensionContext} supplied to an extension during the instantiation
+	 * of test classes or processing of test instances.
 	 *
 	 * @since 5.12
-	 * @see TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope
+	 * @see TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
 	 */
 	@API(status = MAINTAINED, since = "5.13.3")
 	enum ExtensionContextScope {
 
 		/**
-		 * The extension should receive an {@link ExtensionContext} scoped to
-		 * in the <em>default</em> scope.
+		 * The extension should receive an {@link ExtensionContext} for the
+		 * the <em>default</em> scope.
 		 *
 		 * <p>The default scope is determined by the configuration parameter
 		 * {@link #DEFAULT_SCOPE_PROPERTY_NAME}. If not specified, extensions
 		 * will receive an {@link ExtensionContext} scoped to the test class.
 		 *
 		 * @deprecated This behavior will be removed from future versions of
-		 * JUnit and {@link #TEST_METHOD} will become the default.
+		 * JUnit, and {@link #TEST_METHOD} will become the default.
 		 *
 		 * @see #DEFAULT_SCOPE_PROPERTY_NAME
 		 */
@@ -124,8 +164,12 @@ enum ExtensionContextScope {
 
 		/**
 		 * The extension should receive an {@link ExtensionContext} scoped to
-		 * the test method, unless the
-		 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.
+		 * the test method.
+		 *
+		 * <p>Note, however, that a test-class scoped context will always be
+		 * supplied if the
+		 * {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
+		 * test instance lifecycle is used.
 		 */
 		TEST_METHOD;
 
@@ -140,6 +184,7 @@ enum ExtensionContextScope {
 		 * @see #DEFAULT
 		 */
 		public static final String DEFAULT_SCOPE_PROPERTY_NAME = "junit.jupiter.extensions.testinstantiation.extensioncontextscope.default";
+
 	}
 
 }
diff --git a/junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/Node.java b/junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/Node.java
@@ -11,6 +11,7 @@
 package org.junit.platform.engine.support.hierarchical;
 
 import static java.util.Collections.emptySet;
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.MAINTAINED;
 import static org.apiguardian.api.API.Status.STABLE;
 
@@ -182,6 +183,23 @@ default Set<ExclusiveResource> getExclusiveResources() {
 		return emptySet();
 	}
 
+	/**
+	 * {@return whether this node requires the global read-write lock}
+	 *
+	 * <p>Engines should return {@code true} for all nodes that have behavior,
+	 * including tests but also containers with before/after lifecycle hooks.
+	 *
+	 * <p>The default implementation returns {@code true}. The value returned by
+	 * engine-level nodes is ignored. Otherwise, if a container node returns
+	 * {@code true}, the value returned by its descendants is ignored.
+	 *
+	 * @since 6.1
+	 */
+	@API(status = EXPERIMENTAL, since = "6.1")
+	default boolean isGlobalReadLockRequired() {
+		return true;
+	}
+
 	/**
 	 * Get the preferred of {@linkplain ExecutionMode execution mode} for
 	 * parallel execution of this node.
diff --git a/junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/NodeTreeWalker.java b/junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/NodeTreeWalker.java
diff --git a/junit-platform-reporting/src/main/java/org/junit/platform/reporting/open/xml/OpenTestReportGeneratingListener.java b/junit-platform-reporting/src/main/java/org/junit/platform/reporting/open/xml/OpenTestReportGeneratingListener.java
diff --git a/platform-tests/src/test/java/org/junit/platform/engine/support/hierarchical/NodeTreeWalkerIntegrationTests.java b/platform-tests/src/test/java/org/junit/platform/engine/support/hierarchical/NodeTreeWalkerIntegrationTests.java
diff --git a/platform-tests/src/test/java/org/junit/platform/reporting/open/xml/OpenTestReportGeneratingListenerTests.java b/platform-tests/src/test/java/org/junit/platform/reporting/open/xml/OpenTestReportGeneratingListenerTests.java
