[maven-surefire] branch master updated: [SUREFIRE-1908] Wish by Stackoverflow - Documented strategy with parallel Java packages

[ti...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tibordigana pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-surefire.git


The following commit(s) were added to refs/heads/master by this push:
     new 27ef162  [SUREFIRE-1908] Wish by Stackoverflow - Documented strategy with parallel Java packages
27ef162 is described below

commit 27ef162711425807a3647dc33e8c5267566d46dc
Author: V. Mark Lehky <ml...@switch.com>
AuthorDate: Thu Apr 15 12:05:18 2021 -0700

    [SUREFIRE-1908] Wish by Stackoverflow - Documented strategy with parallel Java packages
---
 .../fork-options-and-parallel-execution.apt.vm     | 64 ++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm b/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
index 1add809..fe9d2f6 100644
--- a/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
@@ -181,6 +181,70 @@ Fork Options and Parallel Test Execution
   See the keywords: <volatile>, <synchronized>, <<immutable>> and <final> in
   {{{https://jcp.org/en/jsr/detail?id=133}Java Memory Model - JSR-133}}.
 
+* Parallel Test-Suite Execution
+
+  ${project.artifactId}'s notion of "suite" is related to
+  {{{https://github.com/junit-team/junit4/wiki/Aggregating-tests-in-suites}junit4 Suite}}. 
+
+  For example, say your tests are laid out like this:
+
++---+
+src/test/java
++-features.areaA
+| +-SomeTest.java
+| +-AnotherTest.java
++-features.areaB
+| +-DifferentTest.java
+| +-OtherTest.java
++---+
+
+  You would add a TestSuite.java for each package, that would look something like:
+
++---+
+package features.areaA;
+
+import org.junit.runner.RunWith;
+import org.junit.runners.Suite;
+
+@RunWith(Suite.class)
+@Suite.SuiteClasses({
+    SomeTest.class,
+    AnotherTest.class
+})
+public class TestSuite {
+}
++---+
+
+  and similarly for <<<package features.areaB>>>. You would then configure
+  ${project.artifactId} as follows:
+
++---+
+<plugin>
+  <groupId>${project.groupId}</groupId>
+  <artifactId>${project.artifactId}</artifactId>
+  <version>${project.version}</version>
+  <configuration>
+    <includes>
+      <include>features.*.TestSuite</include>
+    </includes>
+    <parallel>suites</parallel>
+    <threadCountSuites>2</threadCountSuites>
+    <perCoreThreadCount>false</perCoreThreadCount>
+  </configuration>
+</plugin>
++---+
+
+  This would then run up to 2 threads, and each thread would be fed a TestSuite.class,
+  one at a time. The test classes within that Suite would be executed sequentially
+  in the order specified the Suite class.
+
+  Note that the <<<perCoreThreadCount>>> is a "multiplier" of a sorts. With this
+  parameter set to true (the default value), you will get the specified number of
+  threads <<per CPU core>>.
+
+  Also note that in this specific case <<<threadCountSuites=2>>> has the same effect
+  as <<<threadCount=2>>>, since we are using <<<parallel=suites>>>.
+
 * Parallel ${project.artifactId} Execution in Multi-Module Maven Parallel Build
 
   Maven core allows building modules of multi-module projects in parallel with