review comments

Issue: #4321

Author: etrandafir93

documentation/src/docs/asciidoc/user-guide/migration-from-junit4.adoc

@@ -46,7 +46,7 @@ concurrent test execution. It can be enabled and configured using the following
 
 `junit.vintage.execution.parallel.enabled=true|false`::
   Enable/disable parallel execution (defaults to `false`).
-Requires opt-in for `classes` or `methods` to be executed in parallel using the configuration parameters below.
+ Requires opt-in for `classes` or `methods` to be executed in parallel using the configuration parameters below.
 
 `junit.vintage.execution.parallel.classes=true|false`::
   Enable/disable parallel execution of test classes (defaults to `false`).
@@ -56,8 +56,10 @@ Requires opt-in for `classes` or `methods` to be executed in parallel using the
 
 `junit.vintage.execution.parallel.pool-size=<number>`::
   Specifies the size of the thread pool to be used for parallel execution.
-By default, the  number of available processors is used.
+ By default, the  number of available processors is used.
 
+[[migrating-from-junit4-parallel-execution-class-level]]
+==== Parallelization at Class Level
 
 Let's assume we have two test classes `FooTest` and `BarTest` with each class containing three unit tests.
 Now, let's enable the parallel execution of test classes:
@@ -66,6 +68,7 @@ Now, let's enable the parallel execution of test classes:
 ----
 junit.vintage.execution.parallel.enabled=true
 junit.vintage.execution.parallel.classes=true
+junit.vintage.execution.parallel.pool-size=2
 ----
 
 With this setup, the `VintageTestEngine` will use two different threads,
@@ -81,13 +84,17 @@ ForkJoinPool-1-worker-1 - BarTest::test3
 ForkJoinPool-1-worker-2 - FooTest::test3
 ----
 
-On the other hand, we can enable the parallel test execution at a `method` level,
+[[migrating-from-junit4-parallel-execution-method-level]]
+==== Parallelization at Method Level
+
+Alternatively, we can enable the parallel test execution at a `method` level,
 rather than the `class` level:
 
 [source,properties]
 ----
 junit.vintage.execution.parallel.enabled=true
 junit.vintage.execution.parallel.methods=true
+junit.vintage.execution.parallel.pool-size=4
 ----
 
 Therefore, the test methods from within a class will be executed in parallel,
@@ -104,13 +111,17 @@ ForkJoinPool-1-worker-2 - FooTest::test2
 ForkJoinPool-1-worker-1 - FooTest::test3
 ----
 
+[[migrating-from-junit4-parallel-execution-class-and-method-level]]
+==== Full Parallelization
+
 Finally, we can also enable the parallelization at both `class` and `method` level:
 
 [source,properties]
 ----
 junit.vintage.execution.parallel.enabled=true
 junit.vintage.execution.parallel.classes=true
 junit.vintage.execution.parallel.methods=true
+junit.vintage.execution.parallel.pool-size=8
 ----
 
 With these properties set, the `VintageTestEngine` will execute all the tests classes
@@ -126,6 +137,41 @@ ForkJoinPool-1-worker-5 - BarTest::test2
 ForkJoinPool-1-worker-4 - BarTest::test1
 ----
 
+[[migrating-from-junit4-parallel-execution-disabled]]
+==== Sequential Execution
+
+On the other hand, if we disable the parallel execution, the `VintageTestEngine`
+will execute the tests sequentially, regardless of the other properties:
+
+[source,properties]
+----
+junit.vintage.execution.parallel.enabled=false
+junit.vintage.execution.parallel.classes=true
+junit.vintage.execution.parallel.methods=true
+----
+
+Similarly, the parallelization won't work if we only enable the parallel execution,
+but we don't specifically enable a parallel execution level:
+
+[source,properties]
+----
+junit.vintage.execution.parallel.enabled=true
+junit.vintage.execution.parallel.classes=false
+junit.vintage.execution.parallel.methods=false
+----
+
+In such cases, all the tests will be executed sequentially:
+[source,plaintext]
+----
+main - BarTest::test1
+main - BarTest::test2
+main - BarTest::test3
+
+main - FooTest::test1
+main - FooTest::test2
+main - FooTest::test3
+----
+
 [[migrating-from-junit4-tips]]
 === Migration Tips