Implement parallel executor service without ForkJoinPool

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

@@ -21,13 +21,20 @@ repository on GitHub.
 [[release-notes-6.1.0-M1-junit-platform-deprecations-and-breaking-changes]]
 ==== Deprecations and Breaking Changes
 
-* ❓
+* Deprecate constructors for `ForkJoinPoolHierarchicalTestExecutorService` in favor of the
+  new `ParallelHierarchicalTestExecutorServiceFactory` that also supports
+  `WorkerThreadPoolHierarchicalTestExecutorService`.
 
 [[release-notes-6.1.0-M1-junit-platform-new-features-and-improvements]]
 ==== New Features and Improvements
 
 * Support for creating a `ModuleSelector` from a `java.lang.Module` and using
   its classloader for test discovery.
+* New `WorkerThreadPoolHierarchicalTestExecutorService` implementation used for parallel
+  test execution that is backed by a regular thread pool rather than a `ForkJoinPool`.
+  Engine authors should switch to use `ParallelHierarchicalTestExecutorServiceFactory`
+  rather than instantiating a concrete `HierarchicalTestExecutorService` implementation
+  for parallel execution directly.
 * `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.
@@ -61,6 +68,13 @@ repository on GitHub.
 * Enrich `assertInstanceOf` failure using the test subject `Throwable` as cause. It
   results in the stack trace of the test subject `Throwable` to get reported along with
   the failure.
+* Make implementation of `HierarchicalTestExecutorService` used for parallel test
+  execution configurable via the new
+  `junit.jupiter.execution.parallel.config.executor-service` configuration parameter to
+  in order to add support for `WorkerThreadPoolHierarchicalTestExecutorService`. Please
+  refer to the
+  <<../user-guide/index.adoc#writing-tests-parallel-execution-config-executor-service, User Guide>>
+  for details.
 
 [[release-notes-6.1.0-M1-junit-vintage]]
 === JUnit Vintage

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

@@ -3433,6 +3433,33 @@ used instead.
 [[writing-tests-parallel-execution-config]]
 ==== Configuration
 
+[[writing-tests-parallel-execution-config-executor-service]]
+===== Executor Service
+
+If parallel execution is enabled, a thread pool is used behind the scenes to execute tests
+concurrently. You can configure which implementation of `HierarchicalTestExecutorService`
+is used be setting the `junit.jupiter.execution.parallel.config.executor-service`
+configuration parameter to one of the following options:
+
+`fork_join_pool` (default)::
+Use an executor service that is backed by a `ForkJoinPool` from the JDK. This will cause
+tests to be executed in a `ForkJoinWorkerThread`. In some cases, usages of
+`ForkJoinPool` in test or production code or calls to blocking JDK APIs may cause the
+number of concurrently executing tests to increase. To avoid this situation, please use
+`worker_thread_pool`.
+
+`worker_thread_pool` (experimental)::
+Use an executor service that is backed by a regular thread pool and does not create
+additional threads if test or production code uses `ForkJoinPool` or calls a blocking
+API in the JDK.
+
+WARNING: Using `worker_thread_pool` is currently an _experimental_ feature. You're invited
+to give it a try and provide feedback to the JUnit team so they can improve and eventually
+<<api-evolution, promote>> this feature.
+
+[[writing-tests-parallel-execution-config-strategies]]
+===== Strategies
+
 Properties such as the desired parallelism and the maximum pool size can be configured
 using a `{ParallelExecutionConfigurationStrategy}`. The JUnit Platform provides two
 implementations out of the box: `dynamic` and `fixed`. Alternatively, you may implement a
@@ -3464,13 +3491,12 @@ strategy with a factor of `1`. Consequently, the desired parallelism will be equ
 number of available processors/cores.
 
 .Parallelism alone does not imply maximum number of concurrent threads
-NOTE: By default JUnit Jupiter does not guarantee that the number of concurrently
-executing tests will not exceed the configured parallelism. For example, when using one
-of the synchronization mechanisms described in the next section, the `ForkJoinPool` that
-is used behind the scenes may spawn additional threads to ensure execution continues with
-sufficient parallelism.
-If you require such guarantees, it is possible to limit the maximum number of concurrent
-threads by controlling the maximum pool size of the `dynamic`, `fixed` and `custom`
+NOTE: By default, JUnit Jupiter does not guarantee that the number of threads used to
+execute test will not exceed the configured parallelism. For example, when using one
+of the synchronization mechanisms described in the next section, the executor service
+implementation may spawn additional threads to ensure execution continues with sufficient
+parallelism. If you require such guarantees, it is possible to limit the maximum number of
+threads by configuring the maximum pool size of the `dynamic`, `fixed` and `custom`
 strategies.
 
 [[writing-tests-parallel-execution-config-properties]]
@@ -3479,86 +3505,66 @@ strategies.
 The following table lists relevant properties for configuring parallel execution. See
 <<running-tests-config-params>> for details on how to set such properties.
 
-[cols="d,d,a,d"]
-|===
-|Property |Description |Supported Values |Default Value
-
-| ```junit.jupiter.execution.parallel.enabled```
-| Enable parallel test execution
-|
-  * `true`
-  * `false`
-| ```false```
-
-| ```junit.jupiter.execution.parallel.mode.default```
-| Default execution mode of nodes in the test tree
-|
-  * `concurrent`
-  * `same_thread`
-| ```same_thread```
-
-| ```junit.jupiter.execution.parallel.mode.classes.default```
-| Default execution mode of top-level classes
-|
-  * `concurrent`
-  * `same_thread`
-| ```same_thread```
-
-| ```junit.jupiter.execution.parallel.config.strategy```
-| Execution strategy for desired parallelism and maximum pool size
-|
-  * `dynamic`
-  * `fixed`
-  * `custom`
-| ```dynamic```
-
-| ```junit.jupiter.execution.parallel.config.dynamic.factor```
-| Factor to be multiplied by the number of available processors/cores to determine the
-  desired parallelism for the ```dynamic``` configuration strategy
-| a positive decimal number
-| ```1.0```
-
-| ```junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor```
-| Factor to be multiplied by the number of available processors/cores and the value of
+====== General
+
+`junit.jupiter.execution.parallel.enabled=true|false`::
+  Enable/disable parallel test execution (defaults to `false`).
+
+`junit.jupiter.execution.parallel.mode.default=concurrent|same_thread`::
+  Default execution mode of nodes in the test tree (defaults to `same_thread`).
+
+`junit.jupiter.execution.parallel.mode.classes.default=concurrent|same_thread`::
+  Default execution mode of top-level classes (defaults to `same_thread`).
+
+`junit.jupiter.execution.parallel.config.executor-service=fork_join_pool|worker_thread_pool`::
+  Type of `HierarchicalTestExecutorService` to use for parallel execution (defaults to
+  `fork_join_pool`).
+
+`junit.jupiter.execution.parallel.config.strategy=dynamic|fixed|custom`::
+  Execution strategy for desired parallelism, maximum pool size, etc. (defaults to `dynamic`).
+
+====== Dynamic strategy
+
+`junit.jupiter.execution.parallel.config.dynamic.factor=decimal`::
+  Factor to be multiplied by the number of available processors/cores to determine the
+  desired parallelism for the ```dynamic``` configuration strategy.
+  Must be a positive decimal number (defaults to `1.0`).
+
+`junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor=decimal`::
+  Factor to be multiplied by the number of available processors/cores and the value of
   `junit.jupiter.execution.parallel.config.dynamic.factor` to determine the desired
-  parallelism for the ```dynamic``` configuration strategy
-| a positive decimal number, must be greater than or equal to `1.0`
-| 256 + the value of `junit.jupiter.execution.parallel.config.dynamic.factor` multiplied
-  by the number of available processors/cores
-
-| ```junit.jupiter.execution.parallel.config.dynamic.saturate```
-| Disable saturation of the underlying fork-join pool for the ```dynamic``` configuration
-strategy
-|
-* `true`
-* `false`
-| ```true```
-
-| ```junit.jupiter.execution.parallel.config.fixed.parallelism```
-| Desired parallelism for the ```fixed``` configuration strategy
-| a positive integer
-| no default value
-
-| ```junit.jupiter.execution.parallel.config.fixed.max-pool-size```
-| Desired maximum pool size of the underlying fork-join pool for the ```fixed```
-  configuration strategy
-| a positive integer, must be greater than or equal to `junit.jupiter.execution.parallel.config.fixed.parallelism`
-| 256 + the value of `junit.jupiter.execution.parallel.config.fixed.parallelism`
-
-| ```junit.jupiter.execution.parallel.config.fixed.saturate```
-| Disable saturation of the underlying fork-join pool for the ```fixed``` configuration
-  strategy
-|
-  * `true`
-  * `false`
-| ```true```
-
-| ```junit.jupiter.execution.parallel.config.custom.class```
-| Fully qualified class name of the _ParallelExecutionConfigurationStrategy_ to be
-  used for the ```custom``` configuration strategy
-| for example, _org.example.CustomStrategy_
-| no default value
-|===
+  parallelism for the ```dynamic``` configuration strategy.
+  Must be a positive decimal number greater than or equal to `1.0` (defaults to 256 plus
+  the value of `junit.jupiter.execution.parallel.config.dynamic.factor` multiplied by the
+  number of available processors/cores)
+
+`junit.jupiter.execution.parallel.config.dynamic.saturate=true|false`::
+  Enable/disable saturation of the underlying `ForkJoinPool` for the ```dynamic```
+  configuration strategy (defaults to `true`). Only used if
+  `junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`.
+
+====== Fixed strategy
+
+`junit.jupiter.execution.parallel.config.fixed.parallelism=integer`::
+  Desired parallelism for the ```fixed``` configuration strategy (no default value). Must
+  be a positive integer.
+
+`junit.jupiter.execution.parallel.config.fixed.max-pool-size=integer`::
+  Desired maximum pool size of the underlying fork-join pool for the ```fixed```
+  configuration strategy. Must be a positive integer greater than or equal to
+  `junit.jupiter.execution.parallel.config.fixed.parallelism` (defaults to 256 plus the
+  value of `junit.jupiter.execution.parallel.config.fixed.parallelism`).
+
+`junit.jupiter.execution.parallel.config.fixed.saturate=true|false`::
+  Enable/disable saturation of the underlying `ForkJoinPool` for the ```fixed```
+  configuration strategy (defaults to `true`). Only used if
+  `junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`.
+
+====== Custom strategy
+
+`junit.jupiter.execution.parallel.config.custom.class=classname`::
+  Fully qualified class name of the `ParallelExecutionConfigurationStrategy` to be used
+  for the ```custom``` configuration strategy (no default value).
 
 [[writing-tests-parallel-execution-synchronization]]
 ==== Synchronization

documentation/src/test/resources/junit-platform.properties

@@ -1,5 +1,6 @@
 junit.jupiter.execution.parallel.enabled=true
 junit.jupiter.execution.parallel.mode.default=concurrent
+junit.jupiter.execution.parallel.config.executor-service=worker_thread_pool
 junit.jupiter.execution.parallel.config.strategy=fixed
 junit.jupiter.execution.parallel.config.fixed.parallelism=6
 

documentation/src/test/resources/log4j2-test.xml

@@ -5,7 +5,7 @@
 			   xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-2.xsd">
 	<Appenders>
 		<Console name="Console" target="SYSTEM_OUT">
-			<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
+			<PatternLayout pattern="%d{HH:mm:ss.SSSSSS} [%-18t] %-5level %logger{1.} - %msg%n"/>
 		</Console>
 	</Appenders>
 	<Loggers>

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/Constants.java

@@ -39,6 +39,8 @@
 import org.junit.jupiter.engine.config.JupiterConfiguration;
 import org.junit.platform.commons.util.ClassNamePatternFilterUtils;
 import org.junit.platform.engine.support.hierarchical.ParallelExecutionConfigurationStrategy;
+import org.junit.platform.engine.support.hierarchical.ParallelHierarchicalTestExecutorServiceFactory;
+import org.junit.platform.engine.support.hierarchical.ParallelHierarchicalTestExecutorServiceFactory.ParallelExecutorServiceType;
 
 /**
  * Collection of constants related to the {@link JupiterTestEngine}.
@@ -237,7 +239,21 @@ public final class Constants {
 	@API(status = STABLE, since = "5.10")
 	public static final String DEFAULT_CLASSES_EXECUTION_MODE_PROPERTY_NAME = Execution.DEFAULT_CLASSES_EXECUTION_MODE_PROPERTY_NAME;
 
-	static final String PARALLEL_CONFIG_PREFIX = "junit.jupiter.execution.parallel.config.";
+	/**
+	 * Property name used to determine the desired
+	 * {@link ParallelExecutorServiceType ParallelExecutorServiceType}:
+	 * {@value}
+	 *
+	 * <p>Value must be
+	 * {@link ParallelExecutorServiceType#FORK_JOIN_POOL FORK_JOIN_POOL} or
+	 * {@link ParallelExecutorServiceType#WORKER_THREAD_POOL WORKER_THREAD_POOL},
+	 * ignoring case.
+	 *
+	 * @since 6.1
+	 * @see ParallelHierarchicalTestExecutorServiceFactory
+	 */
+	@API(status = EXPERIMENTAL, since = "6.1")
+	public static final String PARALLEL_CONFIG_EXECUTOR_SERVICE_PROPERTY_NAME = JupiterConfiguration.PARALLEL_CONFIG_EXECUTOR_SERVICE_PROPERTY_NAME;
 
 	/**
 	 * Property name used to select the
@@ -249,7 +265,7 @@ public final class Constants {
 	 * @since 5.3
 	 */
 	@API(status = STABLE, since = "5.10")
-	public static final String PARALLEL_CONFIG_STRATEGY_PROPERTY_NAME = PARALLEL_CONFIG_PREFIX
+	public static final String PARALLEL_CONFIG_STRATEGY_PROPERTY_NAME = JupiterConfiguration.PARALLEL_CONFIG_PREFIX
 			+ CONFIG_STRATEGY_PROPERTY_NAME;
 
 	/**
@@ -261,7 +277,7 @@ public final class Constants {
 	 * @since 5.3
 	 */
 	@API(status = STABLE, since = "5.10")
-	public static final String PARALLEL_CONFIG_FIXED_PARALLELISM_PROPERTY_NAME = PARALLEL_CONFIG_PREFIX
+	public static final String PARALLEL_CONFIG_FIXED_PARALLELISM_PROPERTY_NAME = JupiterConfiguration.PARALLEL_CONFIG_PREFIX
 			+ CONFIG_FIXED_PARALLELISM_PROPERTY_NAME;
 
 	/**
@@ -275,7 +291,7 @@ public final class Constants {
 	 * @since 5.10
 	 */
 	@API(status = MAINTAINED, since = "5.13.3")
-	public static final String PARALLEL_CONFIG_FIXED_MAX_POOL_SIZE_PROPERTY_NAME = PARALLEL_CONFIG_PREFIX
+	public static final String PARALLEL_CONFIG_FIXED_MAX_POOL_SIZE_PROPERTY_NAME = JupiterConfiguration.PARALLEL_CONFIG_PREFIX
 			+ CONFIG_FIXED_MAX_POOL_SIZE_PROPERTY_NAME;
 
 	/**
@@ -291,7 +307,7 @@ public final class Constants {
 	 * @since 5.10
 	 */
 	@API(status = MAINTAINED, since = "5.13.3")
-	public static final String PARALLEL_CONFIG_FIXED_SATURATE_PROPERTY_NAME = PARALLEL_CONFIG_PREFIX
+	public static final String PARALLEL_CONFIG_FIXED_SATURATE_PROPERTY_NAME = JupiterConfiguration.PARALLEL_CONFIG_PREFIX
 			+ CONFIG_FIXED_SATURATE_PROPERTY_NAME;
 
 	/**
@@ -304,7 +320,7 @@ public final class Constants {
 	 * @since 5.3
 	 */
 	@API(status = STABLE, since = "5.10")
-	public static final String PARALLEL_CONFIG_DYNAMIC_FACTOR_PROPERTY_NAME = PARALLEL_CONFIG_PREFIX
+	public static final String PARALLEL_CONFIG_DYNAMIC_FACTOR_PROPERTY_NAME = JupiterConfiguration.PARALLEL_CONFIG_PREFIX
 			+ CONFIG_DYNAMIC_FACTOR_PROPERTY_NAME;
 
 	/**
@@ -315,7 +331,7 @@ public final class Constants {
 	 * @since 5.3
 	 */
 	@API(status = STABLE, since = "5.10")
-	public static final String PARALLEL_CONFIG_CUSTOM_CLASS_PROPERTY_NAME = PARALLEL_CONFIG_PREFIX
+	public static final String PARALLEL_CONFIG_CUSTOM_CLASS_PROPERTY_NAME = JupiterConfiguration.PARALLEL_CONFIG_PREFIX
 			+ CONFIG_CUSTOM_CLASS_PROPERTY_NAME;
 
 	/**

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/JupiterTestEngine.java

@@ -29,9 +29,9 @@
 import org.junit.platform.engine.UniqueId;
 import org.junit.platform.engine.support.config.PrefixedConfigurationParameters;
 import org.junit.platform.engine.support.discovery.DiscoveryIssueReporter;
-import org.junit.platform.engine.support.hierarchical.ForkJoinPoolHierarchicalTestExecutorService;
 import org.junit.platform.engine.support.hierarchical.HierarchicalTestEngine;
 import org.junit.platform.engine.support.hierarchical.HierarchicalTestExecutorService;
+import org.junit.platform.engine.support.hierarchical.ParallelHierarchicalTestExecutorServiceFactory;
 import org.junit.platform.engine.support.hierarchical.ThrowableCollector;
 
 /**
@@ -79,8 +79,8 @@ public TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId
 	protected HierarchicalTestExecutorService createExecutorService(ExecutionRequest request) {
 		JupiterConfiguration configuration = getJupiterConfiguration(request);
 		if (configuration.isParallelExecutionEnabled()) {
-			return new ForkJoinPoolHierarchicalTestExecutorService(new PrefixedConfigurationParameters(
-				request.getConfigurationParameters(), Constants.PARALLEL_CONFIG_PREFIX));
+			return ParallelHierarchicalTestExecutorServiceFactory.create(new PrefixedConfigurationParameters(
+				request.getConfigurationParameters(), JupiterConfiguration.PARALLEL_CONFIG_PREFIX));
 		}
 		return super.createExecutorService(request);
 	}

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/DefaultJupiterConfiguration.java

@@ -16,6 +16,8 @@
 import static org.junit.jupiter.api.io.TempDir.DEFAULT_CLEANUP_MODE_PROPERTY_NAME;
 import static org.junit.jupiter.api.io.TempDir.DEFAULT_FACTORY_PROPERTY_NAME;
 import static org.junit.jupiter.engine.config.FilteringConfigurationParameterConverter.exclude;
+import static org.junit.platform.engine.support.hierarchical.ParallelHierarchicalTestExecutorServiceFactory.ParallelExecutorServiceType.FORK_JOIN_POOL;
+import static org.junit.platform.engine.support.hierarchical.ParallelHierarchicalTestExecutorServiceFactory.ParallelExecutorServiceType.WORKER_THREAD_POOL;
 
 import java.util.List;
 import java.util.Optional;
@@ -100,6 +102,17 @@ private void validateConfigurationParameters(DiscoveryIssueReporter issueReporte
 							Please remove it from your configuration.""".formatted(key));
 					issueReporter.reportIssue(warning);
 				}));
+		if (isParallelExecutionEnabled()
+				&& configurationParameters.get(PARALLEL_CONFIG_EXECUTOR_SERVICE_PROPERTY_NAME).isEmpty()) {
+			var info = DiscoveryIssue.create(Severity.INFO,
+				"Parallel test execution is enabled but the default ForkJoinPool-based executor service will be used. "
+						+ "Please give the new implementation based on a regular thread pool a try by setting the '"
+						+ PARALLEL_CONFIG_EXECUTOR_SERVICE_PROPERTY_NAME + "' configuration parameter to '"
+						+ WORKER_THREAD_POOL + "' and report any issues to the JUnit team. "
+						+ "Alternatively, set the configuration parameter to '" + FORK_JOIN_POOL
+						+ "' to hide this message and keep using the original implementation.");
+			issueReporter.reportIssue(info);
+		}
 	}
 
 	@Override