@@ -3433,6 +3433,33 @@ used instead.
34333433[[writing-tests-parallel-execution-config]]
34343434==== Configuration
34353435
3436+ [[writing-tests-parallel-execution-config-executor-service]]
3437+ ===== Executor Service
3438+
3439+ If parallel execution is enabled, a thread pool is used behind the scenes to execute tests
3440+ concurrently. You can configure which implementation of `HierarchicalTestExecutorService`
3441+ is used be setting the `junit.jupiter.execution.parallel.config.executor-service`
3442+ configuration parameter to one of the following options:
3443+
3444+ `fork_join_pool` (default)::
3445+ Use an executor service that is backed by a `ForkJoinPool` from the JDK. This will cause
3446+ tests to be executed in a `ForkJoinWorkerThread`. In some cases, usages of
3447+ `ForkJoinPool` in test or production code or calls to blocking JDK APIs may cause the
3448+ number of concurrently executing tests to increase. To avoid this situation, please use
3449+ `worker_thread_pool`.
3450+
3451+ `worker_thread_pool` (experimental)::
3452+ Use an executor service that is backed by a regular thread pool and does not create
3453+ additional threads if test or production code uses `ForkJoinPool` or calls a blocking
3454+ API in the JDK.
3455+
3456+ WARNING: Using `worker_thread_pool` is currently an _experimental_ feature. You're invited
3457+ to give it a try and provide feedback to the JUnit team so they can improve and eventually
3458+ <<api-evolution, promote>> this feature.
3459+
3460+ [[writing-tests-parallel-execution-config-strategies]]
3461+ ===== Strategies
3462+
34363463Properties such as the desired parallelism and the maximum pool size can be configured
34373464using a `{ParallelExecutionConfigurationStrategy}`. The JUnit Platform provides two
34383465implementations 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
34643491number of available processors/cores.
34653492
34663493.Parallelism alone does not imply maximum number of concurrent threads
3467- NOTE: By default JUnit Jupiter does not guarantee that the number of concurrently
3468- executing tests will not exceed the configured parallelism. For example, when using one
3469- of the synchronization mechanisms described in the next section, the `ForkJoinPool` that
3470- is used behind the scenes may spawn additional threads to ensure execution continues with
3471- sufficient parallelism.
3472- If you require such guarantees, it is possible to limit the maximum number of concurrent
3473- threads by controlling the maximum pool size of the `dynamic`, `fixed` and `custom`
3494+ NOTE: By default, JUnit Jupiter does not guarantee that the number of threads used to
3495+ execute test will not exceed the configured parallelism. For example, when using one
3496+ of the synchronization mechanisms described in the next section, the executor service
3497+ implementation may spawn additional threads to ensure execution continues with sufficient
3498+ parallelism. If you require such guarantees, it is possible to limit the maximum number of
3499+ threads by configuring the maximum pool size of the `dynamic`, `fixed` and `custom`
34743500strategies.
34753501
34763502[[writing-tests-parallel-execution-config-properties]]
@@ -3479,86 +3505,66 @@ strategies.
34793505The following table lists relevant properties for configuring parallel execution. See
34803506<<running-tests-config-params>> for details on how to set such properties.
34813507
3482- [cols="d,d,a,d"]
3483- |===
3484- |Property |Description |Supported Values |Default Value
3485-
3486- | ```junit.jupiter.execution.parallel.enabled```
3487- | Enable parallel test execution
3488- |
3489- * `true`
3490- * `false`
3491- | ```false```
3492-
3493- | ```junit.jupiter.execution.parallel.mode.default```
3494- | Default execution mode of nodes in the test tree
3495- |
3496- * `concurrent`
3497- * `same_thread`
3498- | ```same_thread```
3499-
3500- | ```junit.jupiter.execution.parallel.mode.classes.default```
3501- | Default execution mode of top-level classes
3502- |
3503- * `concurrent`
3504- * `same_thread`
3505- | ```same_thread```
3506-
3507- | ```junit.jupiter.execution.parallel.config.strategy```
3508- | Execution strategy for desired parallelism and maximum pool size
3509- |
3510- * `dynamic`
3511- * `fixed`
3512- * `custom`
3513- | ```dynamic```
3514-
3515- | ```junit.jupiter.execution.parallel.config.dynamic.factor```
3516- | Factor to be multiplied by the number of available processors/cores to determine the
3517- desired parallelism for the ```dynamic``` configuration strategy
3518- | a positive decimal number
3519- | ```1.0```
3520-
3521- | ```junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor```
3522- | Factor to be multiplied by the number of available processors/cores and the value of
3508+ ====== General
3509+
3510+ `junit.jupiter.execution.parallel.enabled=true|false`::
3511+ Enable/disable parallel test execution (defaults to `false`).
3512+
3513+ `junit.jupiter.execution.parallel.mode.default=concurrent|same_thread`::
3514+ Default execution mode of nodes in the test tree (defaults to `same_thread`).
3515+
3516+ `junit.jupiter.execution.parallel.mode.classes.default=concurrent|same_thread`::
3517+ Default execution mode of top-level classes (defaults to `same_thread`).
3518+
3519+ `junit.jupiter.execution.parallel.config.executor-service=fork_join_pool|worker_thread_pool`::
3520+ Type of `HierarchicalTestExecutorService` to use for parallel execution (defaults to
3521+ `fork_join_pool`).
3522+
3523+ `junit.jupiter.execution.parallel.config.strategy=dynamic|fixed|custom`::
3524+ Execution strategy for desired parallelism, maximum pool size, etc. (defaults to `dynamic`).
3525+
3526+ ====== Dynamic strategy
3527+
3528+ `junit.jupiter.execution.parallel.config.dynamic.factor=decimal`::
3529+ Factor to be multiplied by the number of available processors/cores to determine the
3530+ desired parallelism for the ```dynamic``` configuration strategy.
3531+ Must be a positive decimal number (defaults to `1.0`).
3532+
3533+ `junit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor=decimal`::
3534+ Factor to be multiplied by the number of available processors/cores and the value of
35233535 `junit.jupiter.execution.parallel.config.dynamic.factor` to determine the desired
3524- parallelism for the ```dynamic``` configuration strategy
3525- | a positive decimal number, must be greater than or equal to `1.0`
3526- | 256 + the value of `junit.jupiter.execution.parallel.config.dynamic.factor` multiplied
3527- by the number of available processors/cores
3528-
3529- | ```junit.jupiter.execution.parallel.config.dynamic.saturate```
3530- | Disable saturation of the underlying fork-join pool for the ```dynamic``` configuration
3531- strategy
3532- |
3533- * `true`
3534- * `false`
3535- | ```true```
3536-
3537- | ```junit.jupiter.execution.parallel.config.fixed.parallelism```
3538- | Desired parallelism for the ```fixed``` configuration strategy
3539- | a positive integer
3540- | no default value
3541-
3542- | ```junit.jupiter.execution.parallel.config.fixed.max-pool-size```
3543- | Desired maximum pool size of the underlying fork-join pool for the ```fixed```
3544- configuration strategy
3545- | a positive integer, must be greater than or equal to `junit.jupiter.execution.parallel.config.fixed.parallelism`
3546- | 256 + the value of `junit.jupiter.execution.parallel.config.fixed.parallelism`
3547-
3548- | ```junit.jupiter.execution.parallel.config.fixed.saturate```
3549- | Disable saturation of the underlying fork-join pool for the ```fixed``` configuration
3550- strategy
3551- |
3552- * `true`
3553- * `false`
3554- | ```true```
3555-
3556- | ```junit.jupiter.execution.parallel.config.custom.class```
3557- | Fully qualified class name of the _ParallelExecutionConfigurationStrategy_ to be
3558- used for the ```custom``` configuration strategy
3559- | for example, _org.example.CustomStrategy_
3560- | no default value
3561- |===
3536+ parallelism for the ```dynamic``` configuration strategy.
3537+ Must be a positive decimal number greater than or equal to `1.0` (defaults to 256 plus
3538+ the value of `junit.jupiter.execution.parallel.config.dynamic.factor` multiplied by the
3539+ number of available processors/cores)
3540+
3541+ `junit.jupiter.execution.parallel.config.dynamic.saturate=true|false`::
3542+ Enable/disable saturation of the underlying `ForkJoinPool` for the ```dynamic```
3543+ configuration strategy (defaults to `true`). Only used if
3544+ `junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`.
3545+
3546+ ====== Fixed strategy
3547+
3548+ `junit.jupiter.execution.parallel.config.fixed.parallelism=integer`::
3549+ Desired parallelism for the ```fixed``` configuration strategy (no default value). Must
3550+ be a positive integer.
3551+
3552+ `junit.jupiter.execution.parallel.config.fixed.max-pool-size=integer`::
3553+ Desired maximum pool size of the underlying fork-join pool for the ```fixed```
3554+ configuration strategy. Must be a positive integer greater than or equal to
3555+ `junit.jupiter.execution.parallel.config.fixed.parallelism` (defaults to 256 plus the
3556+ value of `junit.jupiter.execution.parallel.config.fixed.parallelism`).
3557+
3558+ `junit.jupiter.execution.parallel.config.fixed.saturate=true|false`::
3559+ Enable/disable saturation of the underlying `ForkJoinPool` for the ```fixed```
3560+ configuration strategy (defaults to `true`). Only used if
3561+ `junit.jupiter.execution.parallel.config.executor-service` is set to `fork_join_pool`.
3562+
3563+ ====== Custom strategy
3564+
3565+ `junit.jupiter.execution.parallel.config.custom.class=classname`::
3566+ Fully qualified class name of the `ParallelExecutionConfigurationStrategy` to be used
3567+ for the ```custom``` configuration strategy (no default value).
35623568
35633569[[writing-tests-parallel-execution-synchronization]]
35643570==== Synchronization
0 commit comments