From 72e414b2335e2aa331e4b42ca329e6ea7ba5becb Mon Sep 17 00:00:00 2001 From: stoyanK7 Date: Tue, 14 Jun 2022 21:36:06 +0200 Subject: [PATCH 1/4] Add table with relevant properties Issue: #2669 --- .../asciidoc/user-guide/writing-tests.adoc | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 89f9ea408b3e..e692c7c8be2c 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -2333,6 +2333,58 @@ to the same shared resource is running. include::{testDir}/example/SharedResourcesDemo.java[tags=user_guide] ---- +==== Relevant properties + +The below table lists out relevant parallel execution `junit-platform.properties`. +[cols="1,2,1,1"] +|=== +|Property |Description |Acceptable values |Default value + +|junit.jupiter.execution.parallel.enabled +|Enable parallel test exection +a| +* `true` +* `false` +|```false``` + +|junit.jupiter.execution.parallel.mode.default +|Set execution mode of the nodes in the test tree +a| +* `concurrent` +* `same_thread` +|```same_thread``` + +|junit.jupiter.execution.parallel.mode.classes.default +|Set execution mode of the top-level classes +a| +* `concurrent` +* `same_thread` +|```same_thread``` + +|junit.jupiter.execution.parallel.config.strategy +|Set execution strategy for desired paralellism and maximum pool size +a| +* `dynamic` +* `fixed` +* `custom` +| ```dynamic``` + +|junit.jupiter.execution.parallel.config.dynamic.factor +|Set the factor to be multiplied with the number of available processors/cores to determine the desired parallelism for the dynamic configuration strategy +|Must be a decimal number +| ```1``` + + +|junit.jupiter.execution.parallel.config.fixed.parallelism +|Set the desired parallelism for the fixed configuration strategy +|Must be an integer +|No default value + +|junit.jupiter.execution.parallel.config.custom.class +|Specify the fully qualified class name of the ```ParallelExecutionConfigurationStrategy``` to be used for the custom configuration strategy +|for instance ```org.example.CustomStrategy``` +| +|=== [[writing-tests-built-in-extensions]] === Built-in Extensions From d522d44bd5538455bda94032e8e0146c3eb42c9c Mon Sep 17 00:00:00 2001 From: stoyanK7 Date: Thu, 16 Jun 2022 19:52:44 +0200 Subject: [PATCH 2/4] Add properties styling and fill empty cell Issue: #2669 --- .../asciidoc/user-guide/writing-tests.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index e692c7c8be2c..45eedaa75a85 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -2335,33 +2335,33 @@ include::{testDir}/example/SharedResourcesDemo.java[tags=user_guide] ==== Relevant properties -The below table lists out relevant parallel execution `junit-platform.properties`. +The below table lists out relevant parallel execution properties in `junit-platform.properties`. [cols="1,2,1,1"] |=== |Property |Description |Acceptable values |Default value -|junit.jupiter.execution.parallel.enabled +| ```junit.jupiter.execution.parallel.enabled``` |Enable parallel test exection a| * `true` * `false` |```false``` -|junit.jupiter.execution.parallel.mode.default +| ```junit.jupiter.execution.parallel.mode.default``` |Set execution mode of the nodes in the test tree a| * `concurrent` * `same_thread` |```same_thread``` -|junit.jupiter.execution.parallel.mode.classes.default +| ```junit.jupiter.execution.parallel.mode.classes.default``` |Set execution mode of the top-level classes a| * `concurrent` * `same_thread` |```same_thread``` -|junit.jupiter.execution.parallel.config.strategy +| ```junit.jupiter.execution.parallel.config.strategy``` |Set execution strategy for desired paralellism and maximum pool size a| * `dynamic` @@ -2369,21 +2369,21 @@ a| * `custom` | ```dynamic``` -|junit.jupiter.execution.parallel.config.dynamic.factor +| ```junit.jupiter.execution.parallel.config.dynamic.factor``` |Set the factor to be multiplied with the number of available processors/cores to determine the desired parallelism for the dynamic configuration strategy |Must be a decimal number | ```1``` -|junit.jupiter.execution.parallel.config.fixed.parallelism +| ```junit.jupiter.execution.parallel.config.fixed.parallelism``` |Set the desired parallelism for the fixed configuration strategy |Must be an integer |No default value -|junit.jupiter.execution.parallel.config.custom.class +| ```junit.jupiter.execution.parallel.config.custom.class``` |Specify the fully qualified class name of the ```ParallelExecutionConfigurationStrategy``` to be used for the custom configuration strategy |for instance ```org.example.CustomStrategy``` -| +|No default value |=== [[writing-tests-built-in-extensions]] From 66cd5c453cfc30e46768851d0ef555470ef84643 Mon Sep 17 00:00:00 2001 From: stoyan Date: Fri, 17 Jun 2022 12:55:12 +0200 Subject: [PATCH 3/4] Fix typo Co-authored-by: Sam Brannen --- documentation/src/docs/asciidoc/user-guide/writing-tests.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 45eedaa75a85..7dc1b33cc2e5 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -2362,7 +2362,7 @@ a| |```same_thread``` | ```junit.jupiter.execution.parallel.config.strategy``` -|Set execution strategy for desired paralellism and maximum pool size +|Set execution strategy for desired parallelism and maximum pool size a| * `dynamic` * `fixed` From f351cdd0ba5ea27604641f53aace59cb78fa2dc3 Mon Sep 17 00:00:00 2001 From: stoyanK7 Date: Fri, 17 Jun 2022 13:04:46 +0200 Subject: [PATCH 4/4] Move table in the configuration section Issue: #2669 --- .../asciidoc/user-guide/writing-tests.adoc | 80 +++++++++---------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 7dc1b33cc2e5..5bb979a9c830 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -2294,46 +2294,7 @@ behind the scenes may spawn additional threads to ensure execution continues wit sufficient parallelism. Thus, if you require such guarantees in a test class, please use your own means of controlling concurrency. -[[writing-tests-parallel-execution-synchronization]] -==== Synchronization - -In addition to controlling the execution mode using the `{Execution}` annotation, JUnit -Jupiter provides another annotation-based declarative synchronization mechanism. The -`{ResourceLock}` annotation allows you to declare that a test class or method uses a -specific shared resource that requires synchronized access to ensure reliable test -execution. The shared resource is identified by a unique name which is a `String`. The -name can be user-defined or one of the predefined constants in `{Resources}`: -`SYSTEM_PROPERTIES`, `SYSTEM_OUT`, `SYSTEM_ERR`, `LOCALE`, or `TIME_ZONE`. - -If the tests in the following example were run in parallel _without_ the use of -{ResourceLock}, they would be _flaky_. Sometimes they would pass, and at other times they -would fail due to the inherent race condition of writing and then reading the same JVM -System Property. - -When access to shared resources is declared using the `{ResourceLock}` annotation, the -JUnit Jupiter engine uses this information to ensure that no conflicting tests are run in -parallel. - -[NOTE] -.Running tests in isolation -==== -If most of your test classes can be run in parallel without any synchronization but you -have some test classes that need to run in isolation, you can mark the latter with the -`{Isolated}` annotation. Tests in such classes are executed sequentially without any other -tests running at the same time. -==== - -In addition to the `String` that uniquely identifies the shared resource, you may specify -an access mode. Two tests that require `READ` access to a shared resource may run in -parallel with each other but not while any other test that requires `READ_WRITE` access -to the same shared resource is running. - -[source,java] ----- -include::{testDir}/example/SharedResourcesDemo.java[tags=user_guide] ----- - -==== Relevant properties +===== Relevant properties The below table lists out relevant parallel execution properties in `junit-platform.properties`. [cols="1,2,1,1"] @@ -2386,6 +2347,45 @@ a| |No default value |=== +[[writing-tests-parallel-execution-synchronization]] +==== Synchronization + +In addition to controlling the execution mode using the `{Execution}` annotation, JUnit +Jupiter provides another annotation-based declarative synchronization mechanism. The +`{ResourceLock}` annotation allows you to declare that a test class or method uses a +specific shared resource that requires synchronized access to ensure reliable test +execution. The shared resource is identified by a unique name which is a `String`. The +name can be user-defined or one of the predefined constants in `{Resources}`: +`SYSTEM_PROPERTIES`, `SYSTEM_OUT`, `SYSTEM_ERR`, `LOCALE`, or `TIME_ZONE`. + +If the tests in the following example were run in parallel _without_ the use of +{ResourceLock}, they would be _flaky_. Sometimes they would pass, and at other times they +would fail due to the inherent race condition of writing and then reading the same JVM +System Property. + +When access to shared resources is declared using the `{ResourceLock}` annotation, the +JUnit Jupiter engine uses this information to ensure that no conflicting tests are run in +parallel. + +[NOTE] +.Running tests in isolation +==== +If most of your test classes can be run in parallel without any synchronization but you +have some test classes that need to run in isolation, you can mark the latter with the +`{Isolated}` annotation. Tests in such classes are executed sequentially without any other +tests running at the same time. +==== + +In addition to the `String` that uniquely identifies the shared resource, you may specify +an access mode. Two tests that require `READ` access to a shared resource may run in +parallel with each other but not while any other test that requires `READ_WRITE` access +to the same shared resource is running. + +[source,java] +---- +include::{testDir}/example/SharedResourcesDemo.java[tags=user_guide] +---- + [[writing-tests-built-in-extensions]] === Built-in Extensions