[JUnit Platform] Document fixed.max-pool-size property (#2681)

With JUnit 5.9.2 we pull in junit-team/junit-framework#3044 which makes it
possible to limit the maximum number of threads used while
executing in parallel.

Closes: #2677

Author: mpkorstanje

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - [Spring] Support Spring Boot 3 and Spring 6 ([#2644](https://github.com/cucumber/cucumber-jvm/pull/2644) M.P. Korstanje)
+- [JUnit Platform] Support `cucumber.execution.parallel.config.config.fixed.max-pool-size` ([#2681](https://github.com/cucumber/cucumber-jvm/pull/2681) M.P. Korstanje)
 
 ### Changed
 - [Core] Use a [message based JUnit XML Formatter](https://github.com/cucumber/cucumber-junit-xml-formatter) ([#2638](https://github.com/cucumber/cucumber-jvm/pull/2638) M.P. Korstanje)
@@ -21,6 +22,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 - [Core] Improve test step creation performance ([#2666](https://github.com/cucumber/cucumber-jvm/issues/2666), Julien Kronegg)
+- [JUnit Platform] Use JUnit Platform 1.9.2 (JUnit Jupiter 5.9.2)
+
 
 ## [7.10.1] - 2022-12-16
 ### Fixed

cucumber-junit-platform-engine/README.md

@@ -194,18 +194,20 @@ strategy.
 * `dynamic`: Computes the desired parallelism as `<available cores>` * 
 `cucumber.execution.parallel.config.dynamic.factor`.
 
-* `fixed`: Set the desired parallelism to `cucumber.execution.parallel.config.fixed.parallelism`.
+* `fixed`: Set `cucumber.execution.parallel.config.fixed.parallelism` to the
+  desired parallelism and `cucumber.execution.parallel.config.config.fixed.max-pool-size`
+  to the maximum pool size of the underlying ForkJoin pool.
 
 * `custom`: Specify a custom `ParallelExecutionConfigurationStrategy`
 implementation through `cucumber.execution.parallel.config.custom.class`.  
 
 If no strategy is specified Cucumber will use the `dynamic` strategy with a
 factor of `1`.
 
-Note: Cucumber does not guarantee that the number of concurrently executing
-tests will not exceed the configured parallelism. The underlying `ForkJoinPool`
-used to execute scenarios may spawn additional threads. To obtain such
-guarantees us a custom parallel configuration strategy.
+Note: While `.fixed.max-pool-size` effectively limits the maximum number of
+concurrent threads, Cucumber does not guarantee that the number of concurrently
+executing scenarios will not exceed this. See (junit5/#3108)[https://github.com/junit-team/junit5/issues/3108]
+for details.
 
 ### Exclusive Resources ###
 
@@ -302,86 +304,88 @@ documentation
 documentation on Cucumber properties see [Constants](src/main/java/io/cucumber/junit/platform/engine/Constants.java).
 
 ```
-cucumber.ansi-colors.disabled=                                # true or false. 
-                                                              # default: false                     
-      
-cucumber.filter.name=                                         # a regular expression.
-                                                              # only scenarios with matching names are executed.
-                                                              # example: ^Hello (World|Cucumber)$
-                                                              # note: To ensure consistent reports between Cucumber and
-                                                              # JUnit 5 prefer using JUnit 5s discovery request filters
-                                                              # or JUnit 5 tag expressions instead.
-
-cucumber.features=                                            # comma separated paths to feature files. 
-                                                              # example: path/to/example.feature, path/to/other.feature
-                                                              # note: When used any discovery selectors from the JUnit
-                                                              # Platform will be ignored. Use with caution and care.
-
-cucumber.filter.tags=                                         # a cucumber tag expression.
-                                                              # only scenarios with matching tags are executed.
-                                                              # example: @Cucumber and not (@Gherkin or @Zucchini)
-                                                              # note: To ensure consistent reports between Cucumber and
-                                                              # JUnit 5 prefer using JUnit 5s discovery request filters
-                                                              # or JUnit 5 tag expressions instead.
-
-cucumber.glue=                                                # comma separated package names.
-                                                              # example: com.example.glue  
-
-cucumber.junit-platform.naming-strategy=                      # long or short.
-                                                              # default: short
-                                                              # include parent descriptor name in test descriptor.
-
-cucumber.plugin=                                              # comma separated plugin strings.
-                                                              # example: pretty, json:path/to/report.json
-
-cucumber.object-factory=                                      # object factory class name.
-                                                              # example: com.example.MyObjectFactory
-
-cucumber.publish.enabled                                      # true or false. 
-                                                              # default: false
-                                                              # enable publishing of test results
-
-cucumber.publish.quiet                                        # true or false. 
-                                                              # default: false
-                                                              # suppress publish banner after test execution.
-
-cucumber.publish.token                                        # any string value.
-                                                              # publish authenticated test results.
-
-cucumber.snippet-type=                                        # underscore or camelcase.
-                                                              # default: underscore
-
-cucumber.execution.dry-run=                                   # true or false.
-                                                              # default: false
-
-cucumber.execution.execution-mode.feature=                    # same_thread or concurrent
-                                                              # default: concurrent
-                                                              # same_thread - executes scenarios sequentially in the 
-                                                              # same thread as the parent feature 
-                                                              # concurrent - executes scenarios concurrently on any
-                                                              # available thread
-
-cucumber.execution.parallel.enabled=                          # true or false.
-                                                              # default: false
-
-cucumber.execution.parallel.config.strategy=                  # dynamic, fixed or custom.
-                                                              # default: dynamic
-
-cucumber.execution.parallel.config.fixed.parallelism=         # positive integer.
-                                                              # example: 4
-
-cucumber.execution.parallel.config.dynamic.factor=            # positive double.
-                                                              # default: 1.0
-
-cucumber.execution.parallel.config.custom.class=              # class name.
-                                                              # example: com.example.MyCustomParallelStrategy
-
-cucumber.execution.exclusive-resources.<tag-name>.read-write= # a comma separated list of strings
-                                                              # example: resource-a, resource-b.
-
-cucumber.execution.exclusive-resources.<tag-name>.read=       # a comma separated list of strings
-                                                              # example: resource-a, resource-b
-
+cucumber.ansi-colors.disabled=                                 # true or false. 
+                                                               # default: false                     
+       
+cucumber.filter.name=                                          # a regular expression.
+                                                               # only scenarios with matching names are executed.
+                                                               # example: ^Hello (World|Cucumber)$
+                                                               # note: To ensure consistent reports between Cucumber and
+                                                               # JUnit 5 prefer using JUnit 5s discovery request filters
+                                                               # or JUnit 5 tag expressions instead.
+
+cucumber.features=                                             # comma separated paths to feature files. 
+                                                               # example: path/to/example.feature, path/to/other.feature
+                                                               # note: When used any discovery selectors from the JUnit
+                                                               # Platform will be ignored. Use with caution and care.
+
+cucumber.filter.tags=                                          # a cucumber tag expression.
+                                                               # only scenarios with matching tags are executed.
+                                                               # example: @Cucumber and not (@Gherkin or @Zucchini)
+                                                               # note: To ensure consistent reports between Cucumber and
+                                                               # JUnit 5 prefer using JUnit 5s discovery request filters
+                                                               # or JUnit 5 tag expressions instead.
+
+cucumber.glue=                                                 # comma separated package names.
+                                                               # example: com.example.glue  
+
+cucumber.junit-platform.naming-strategy=                       # long or short.
+                                                               # default: short
+                                                               # include parent descriptor name in test descriptor.
+
+cucumber.plugin=                                               # comma separated plugin strings.
+                                                               # example: pretty, json:path/to/report.json
+ 
+cucumber.object-factory=                                       # object factory class name.
+                                                               # example: com.example.MyObjectFactory
+
+cucumber.publish.enabled                                       # true or false. 
+                                                               # default: false
+                                                               # enable publishing of test results
+
+cucumber.publish.quiet                                         # true or false. 
+                                                               # default: false
+                                                               # suppress publish banner after test execution.
+
+cucumber.publish.token                                         # any string value.
+                                                               # publish authenticated test results.
+
+cucumber.snippet-type=                                         # underscore or camelcase.
+                                                               # default: underscore
+
+cucumber.execution.dry-run=                                    # true or false.
+                                                               # default: false
+
+cucumber.execution.execution-mode.feature=                     # same_thread or concurrent
+                                                               # default: concurrent
+                                                               # same_thread - executes scenarios sequentially in the 
+                                                               # same thread as the parent feature 
+                                                               # concurrent - executes scenarios concurrently on any
+                                                               # available thread
+
+cucumber.execution.parallel.enabled=                           # true or false.
+                                                               # default: false
+
+cucumber.execution.parallel.config.strategy=                   # dynamic, fixed or custom.
+                                                               # default: dynamic
+
+cucumber.execution.parallel.config.fixed.parallelism=          # positive integer.
+                                                               # example: 4
+
+cucumber.execution.parallel.config.config.fixed.max-pool-size= # positive integer.
+                                                               # example: 4
+
+cucumber.execution.parallel.config.dynamic.factor=             # positive double.
+                                                               # default: 1.0
+
+cucumber.execution.parallel.config.custom.class=               # class name.
+                                                               # example: com.example.MyCustomParallelStrategy
+
+cucumber.execution.exclusive-resources.<tag-name>.read-write=  # a comma separated list of strings
+                                                               # example: resource-a, resource-b.
+
+cucumber.execution.exclusive-resources.<tag-name>.read=        # a comma separated list of strings
+                                                               # example: resource-a, resource-b
 ```
 
 ## Supported Discovery Selectors and Filters ##