maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From krosenv...@apache.org
Subject git commit: [SUREFIRE-949] update documentation with new forkCount / reuseForks options
Date Thu, 14 Feb 2013 17:45:00 GMT
Updated Branches:
  refs/heads/master e46335a78 -> 1ee6cd284


[SUREFIRE-949] update documentation with new forkCount / reuseForks options

- also make ${surefire.threadNumber} replacement undocumented, as its naming is totally misleading
and might give users wrong impressions


Project: http://git-wip-us.apache.org/repos/asf/maven-surefire/repo
Commit: http://git-wip-us.apache.org/repos/asf/maven-surefire/commit/1ee6cd28
Tree: http://git-wip-us.apache.org/repos/asf/maven-surefire/tree/1ee6cd28
Diff: http://git-wip-us.apache.org/repos/asf/maven-surefire/diff/1ee6cd28

Branch: refs/heads/master
Commit: 1ee6cd2845e56c1ea19305045c0c7ad86c9d04df
Parents: e46335a
Author: Andreas Gudian <andreas.gudian@gmail.com>
Authored: Thu Jan 24 21:12:08 2013 +0100
Committer: Kristian Rosenvold <krosenvold@apache.org>
Committed: Thu Feb 14 18:44:46 2013 +0100

----------------------------------------------------------------------
 .../plugin/surefire/AbstractSurefireMojo.java      |    5 +-
 .../src/site/apt/examples/class-loading.apt.vm     |    4 +-
 .../src/site/apt/examples/debugging.apt.vm         |   14 +-
 .../fork-options-and-parallel-execution.apt.vm     |  103 +++++++++------
 .../src/site/apt/examples/junit.apt.vm             |    4 +-
 maven-surefire-plugin/src/site/fml/faq.fml         |    4 +-
 6 files changed, 77 insertions(+), 57 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/1ee6cd28/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
----------------------------------------------------------------------
diff --git a/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
b/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
index bc8eb0b..3b5af70 100644
--- a/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
+++ b/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
@@ -332,9 +332,8 @@ public abstract class AbstractSurefireMojo
      * <strong>DEPRECATED</strong> since version 2.14. Use <code>forkCount</code>
and <code>reuseForks</code> instead.<br/>
      * <br/>
      * Option to specify the forking mode. Can be "never", "once", "always", "perthread".
"none" and "pertest" are also accepted
-     * for backwards compatibility. "always" forks for each test-class. "perthread" will
create <code>threadCount</code> parallel forks, each executing one test-class,
see also parameter <code>reuseForks</code>.<br/>
-     * The system properties and the "argLine" of the forked processes may contain the place
holder string <code>${surefire.threadNumber}</code>,
-     * which is replaced with a fixed number for each thread, ranging from 1 to <code>threadCount</code>.
+     * for backwards compatibility. "always" forks for each test-class. "perthread" will
create <code>threadCount</code>
+     * parallel forks, each executing one test-class. See also parameter <code>reuseForks</code>.<br/>
      *
      * @since 2.1
      */

http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/1ee6cd28/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm b/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
index 7fac4e8..dfa7e8a 100644
--- a/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
@@ -33,7 +33,7 @@ Classloading and Forking in Maven Surefire
 
 * Executive Summary
 
- If you're having problems, you'll probably want to tinker with these three settings: <<<forkMode>>>,
<<<useSystemClassLoader>>>, and <<<useManifestOnlyJar>>>.
+ If you're having problems, you'll probably want to tinker with these three settings: <<<forkCount>>>,
<<<useSystemClassLoader>>>, and <<<useManifestOnlyJar>>>.
 
 * What problem does the Maven Surefire project solve?
 
@@ -167,7 +167,7 @@ java -classpath booter.jar MyApp
 
  * Run mvn with --debug (aka -X) to get more detailed output
 
- * Check your <<<forkMode>>>.  If <<<forkMode=never>>>,
it's impossible to use the system classloader or a plain old Java classpath; we have to use
an isolated classloader.
+ * Check your <<<forkCount>>>.  If <<<forkCount=0>>>
(or <<<forkMode=never>>>, the deprecated version of that), it's impossible
to use the system classloader or a plain old Java classpath; we have to use an isolated classloader.
 
  * If you're using the defaults, <<<useSystemClassLoader=true>>> and <<<useManifestOnlyJar=false>>>.
 In that case, look at the generated manifest-only Surefire booter JAR.  Open it up (it's
just a zip) and read its manifest.
 

http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/1ee6cd28/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm b/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
index f07ff08..6012e6c 100644
--- a/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
@@ -54,25 +54,25 @@ mvn -Dmaven.${thisPlugin.toLowerCase()}.debug verify
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
 +---+
-mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
-Xnoagent -Djava.compiler=NONE" test
+mvn -Dmaven.${thisPlugin.toLowerCase()}.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
-Xnoagent -Djava.compiler=NONE" test
 +---+
 #{else}
 +---+
-mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
-Xnoagent -Djava.compiler=NONE" verify
+mvn -Dmaven.${thisPlugin.toLowerCase()}.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
-Xnoagent -Djava.compiler=NONE" verify
 +---+
 #{end}
 
 Non-forked Tests
 
-  You can force Maven not to fork tests by configuring the <<<forkMode>>>
configuration parameter.
+  You can force Maven not to fork tests by setting the configuration parameter <<<forkCount>>>
to <0>.
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
 +---+
-mvn -DforkMode=never test
+mvn -DforkCount=0 test
 +---+
 #{else}
 +---+
-mvn -DforkMode=never verify
+mvn -DforkCount=0 verify
 +---+
 #{end}
 
@@ -81,11 +81,11 @@ mvn -DforkMode=never verify
 
 #{if}(${project.artifactId}=="maven-surefire-plugin")
 +---+
-mvnDebug -DforkMode=never test
+mvnDebug -DforkCount=0 test
 +---+
 #{else}
 +---+
-mvnDebug -DforkMode=never verify
+mvnDebug -DforkCount=0 verify
 +---+
 #{end}
 

http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/1ee6cd28/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
----------------------------------------------------------------------
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 d44f90f..42448dc 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
@@ -58,36 +58,32 @@ Fork Options and Parallel Test Execution
   memory and execution time, but you may be more vulnerable towards race
   conditions or other unexpected and hard to reproduce behavior.
 
-  The other possibility for parallel test execution is <<<forkMode=perthread>>>.
-  It spawns up to <<<threadCount>>> new JVM processes concurrently to execute
-  the tests. The next section covers the details about this and the other
-  <<<forkMode>>> settings.
+  The other possibility for parallel test execution is setting the parameter 
+  <<<forkCount>>> to a value higher than 1. The next section covers the
details 
+  about this and the related <<<reuseForks>>> property.
 
 * Forked Test Execution
 
-  The default setting is <<<forkMode=once>>>, which means that Surefire
creates
-  one new JVM process to execute all tests in one maven module.
+  The parameter <<<forkCount>>> defines the maximum number of JVM processes
+  that Surefire will spawn <concurrently> to execute the tests. It supports the
+  same syntax as <<<-T>>> in maven-core: if you termniate the value with
a 'C',
+  that value will be multiplied with the number of available CPU cores in your
+  system. For example <<<forkCount=2.5C>>> on a Quad-Core system will result
+  in up to ten forked JVM processes.
 
-  Using <<<forkMode=never>>> disables forking and executes the tests within
-  the main maven process. This avoids the additional startup and warm-up time
-  of your JVM, but also means that you might have to account for higher memory
-  requirements, especially PermGen.
+  The parameter <<<reuseForks>>> is used to define whether to terminate
the 
+  spawned process after one test class and to create a new process for the next 
+  test in line (<<<reuseForks=false>>>), or whether to reuse the processes
to 
+  execute the next tests (<<<reuseForks=true>>>).
 
-  <<<forkMode=always>>> executes each test class in its own JVM process,
one
-  after another. It creates the highest level of separation for the test
-  execution, but it would probably also give you the longest execution time
-  of all the available options. Consider it as a last resort.
+  The <default setting> is <<<forkCount=1>>>/<<<reuseForks=true>>>,
which means
+  that Surefire creates one new JVM process to execute all tests in one maven
+  module.
 
-  The most powerful setting is <<<forkMode=perthread>>>. Surefire creates
up to
-  <<<threadCount>>> JVM processes to execute tests in parallel. Each process
-  executes one test at a time. The parameter <<<reuseForks>>> is used to
define
-  whether the process shall terminate after each test and to create a new
-  process for the next test in line (<<<reuseForks=false>>>, the default
-  setting), or whether to reuse the processes to execute the next tests
-  (<<<reuseForks=true>>>, new since Surefire 2.13).
-
-  Please note that <<<reuseForks>>> currently only affects
-  <<<forkMode=perthread>>>.
+  <<<forkMode=1>>>/<<<reuseForks=false>>> executes each
test class in its own 
+  JVM process, one after another. It creates the highest level of separation for 
+  the test execution, but it would probably also give you the longest execution 
+  time of all the available options. Consider it as a last resort.
 
   With the <<<argLine>>> property, you can specify additional parameters
to be
   passed to the forked JVM process, such as memory settings. System property
@@ -96,13 +92,13 @@ Fork Options and Parallel Test Execution
   specify variables and values to be added to the system properties during the
   test execution.
 
-  You can use the place holder <<<$\{surefire.threadNumber\}>>> within
+  You can use the place holder <<<$\{surefire.forkNumber\}>>> within
   <<<argLine>>>, or within the system properties (both those specified
via
   <<<mvn test -D...>>> and via <<<systemPropertyVariables>>>).
Before executing
   the tests, Surefire replaces that place holder by the number of the actually
-  executing process, counting from 1 to the value of <<<threadCount>>>.
+  executing process, counting from 1 to the effective value of <<<forkCount>>>.
 
-  For the fork modes other than <<<perthread>>>, the place holder will
always be
+  In case forkig is disabled (<<<forkCount=0>>>), the place holder will
be
   replaced with <1>.
 
   The following is an example configuration that makes use of up to three forked
@@ -120,12 +116,11 @@ Fork Options and Parallel Test Execution
     <artifactId>${project.artifactId}</artifactId>
     <version>${project.version}</version>
     <configuration>
-        <forkMode>perthread</forkMode>
+        <forkCount>3</threadCount>
         <reuseForks>true</reuseForks>
-        <threadCount>3</threadCount>
         <argLine>-Xmx1024m -XX:MaxPermSize=256m</argLine>
         <systemPropertyVariables>
-            <databaseSchema>MY_TEST_SCHEMA_${surefire.threadNumber}</databaseSchema>
+            <databaseSchema>MY_TEST_SCHEMA_${surefire.forkNumber}</databaseSchema>
         </systemPropertyVariables>
     </configuration>
   </plugin>
@@ -142,20 +137,44 @@ Fork Options and Parallel Test Execution
   Port numbers and file names are other examples of resources for which it may
   be hard or undesired to be shared among concurrent test executions.
 
-* Combining forkMode and parallel
+* Combining forkCount and parallel
 
-  The modes <<<forkMode=never>>> and <<<forkMode=once>>>
can be combined freely 
-  with the available settings for <<<parallel>>>.
+  The modes <<<forkCount=0>>> and <<<forkCount=1>>>/<<<reuseForks=true>>>
can
+  be combined freely with the available settings for <<<parallel>>>.
 
-  As <<<forkMode=always>>> creates a new JVM process for each test class,
+  As <<<reuseForks=false>>> creates a new JVM process for each test class,
   using <<<parallel=classes>>> would have no effect. You can still use
   <<<parallel=methods>>>, though.
 
-  When using <<<forkMode=perthread>>>, test classes are handed over to
the
-  forked process one-by-one. Thus, <<<parallel=classes>>> would not change
-  anything. However, you can use <<<parallel=methods>>>: classes are executed
in
-  <<<threadCount=X>>> concurrent processes, each of the processes can then
use
-  the same number of <<<X>>> threads to execute the methods of one class
in
-  parallel. Please note, that the option <<<perCoreThreadCount>>> only
has an
-  effect on the number of threads for method-concurrency, but not on the number
-  of forked processes. 
+  When using <<<reuseForks=true>>> and a <<<forkCount>>>
value larger than one,
+  test classes are handed over to the forked process one-by-one. Thus,
+  <<<parallel=classes>>> would not change anything. However, you can use
+  <<<parallel=methods>>>: classes are executed in <<<forkCount>>>
concurrent
+  processes, each of the processes can then use <<<threadCount>>> threads
to
+  execute the methods of one class in parallel.
+
+* Migrating the Deprecated forkMode Parameter to forkCount and reuseForks
+
+  Surefire versions prior 2.14 used the parameter <<<forkMode>>> to configure
+  forking. Although that parameter is still supported for backward
+  compatibility, users are strongly encouraged to migrate their configuration
+  and use <<<forkCount>>> and <<<reuseForks>>> instead.
+
+  The migration is quite simple, given the following mapping:
+
+*--------------------------+-------------------------------------------+
+ <<Old Setting>>           | <<New Setting>>                    
      |
+*--------------------------+-------------------------------------------+
+ <<<forkMode=once>>>       | <<<forkCount=1>>> (default),
             |
+ (default)                 | <<<reuseForks=true>>> (default)          
|
+*--------------------------+-------------------------------------------+
+ <<<forkMode=always>>>     | <<<forkCount=1>>> (default),
             |
+                           | <<<reuseForks=false>>>                   
|
+*--------------------------+-------------------------------------------+
+ <<<forkMode=never>>>      | <<<forkCount=0>>>      
                  |
+*--------------------------+-------------------------------------------+
+ <<<forkMode=perthread>>>, | <<<forkCount=N>>>,     
                  |
+ <<<threadCount=N>>>       | (<<<reuseForks=false>>>,
if you did not   |
+                           | had that one set)                         |
+*--------------------------+-------------------------------------------+
+

http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/1ee6cd28/maven-surefire-plugin/src/site/apt/examples/junit.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/examples/junit.apt.vm b/maven-surefire-plugin/src/site/apt/examples/junit.apt.vm
index a421f93..74e32cb 100644
--- a/maven-surefire-plugin/src/site/apt/examples/junit.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/junit.apt.vm
@@ -142,6 +142,8 @@ else
   This is particularly useful for slow tests that can have high concurrency.
 
   As of surefire 2.7, no additional dependencies are needed to use the full set of options
with parallel.
+  
+  See also {{{./fork-options-and-parallel-execution.html}Fork Options and Parallel Test Execution}}.
 
 * Using custom listeners and reporters
 
@@ -170,7 +172,7 @@ else
 
 * Using a security manager (JUnit3 only)
 
-   As long as forkMode!=never and you use JUnit3, you can run your tests with a java security
manager active.
+   As long as forkCount!=0 and you use JUnit3, you can run your tests with a java security
manager active.
    The classname of the security manager must be sent as a system property variable to the
JUnit3 provider.
 
    JUnit4 uses mechanisms internally that are not compatible with the tested security managers
and is not supported

http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/1ee6cd28/maven-surefire-plugin/src/site/fml/faq.fml
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/fml/faq.fml b/maven-surefire-plugin/src/site/fml/faq.fml
index e7f6a93..9c44fbc 100644
--- a/maven-surefire-plugin/src/site/fml/faq.fml
+++ b/maven-surefire-plugin/src/site/fml/faq.fml
@@ -77,9 +77,9 @@ under the License.
         <code>
         <![CDATA[ <useSystemClassLoader>true</useSystemClassLoader>]]><br/>
         <![CDATA[ <useManifestOnlyJar>false</useManifestOnlyJar>]]><br/>
-        <![CDATA[ <forkMode>once</forkMode>]]><br/>
+        <![CDATA[ <forkCount>1</forkCount>]]><br/>
         </code>
-        forkMode at least once, always if not enough
+        try reuseForks=true and if it doesn't work, fall back to reuseForks=false
         </p>
       </answer>
     </faq>


Mime
View raw message