You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by ol...@apache.org on 2012/12/11 20:53:30 UTC
[1/3] git commit: revert https://git-wip-us.apache.org/repos/asf?p=maven-surefire.git;a=commit;h=a303827d673a4821e2c7aadd8e54eab1171c070c only for apt files as site was broken. sorry I don't know how Hervé format apt files :-)
Updated Branches:
refs/heads/master 99f5db0a0 -> 8970909cf
revert https://git-wip-us.apache.org/repos/asf?p=maven-surefire.git;a=commit;h=a303827d673a4821e2c7aadd8e54eab1171c070c
only for apt files as site was broken.
sorry I don't know how Hervé format apt files :-)
Project: http://git-wip-us.apache.org/repos/asf/maven-surefire/repo
Commit: http://git-wip-us.apache.org/repos/asf/maven-surefire/commit/8970909c
Tree: http://git-wip-us.apache.org/repos/asf/maven-surefire/tree/8970909c
Diff: http://git-wip-us.apache.org/repos/asf/maven-surefire/diff/8970909c
Branch: refs/heads/master
Commit: 8970909cf61de05e17d0759a29707dffa0ec0310
Parents: 99f5db0
Author: olivier lamy <ol...@apache.org>
Authored: Tue Dec 11 20:52:26 2012 +0100
Committer: olivier lamy <ol...@apache.org>
Committed: Tue Dec 11 20:52:26 2012 +0100
----------------------------------------------------------------------
maven-surefire-plugin/src/site/apt/api.apt.vm | 105 +--
.../src/site/apt/developing.apt.vm | 148 ++--
.../src/site/apt/examples/class-loading.apt.vm | 414 ++++-----
.../site/apt/examples/configuring-classpath.apt.vm | 251 +++---
.../src/site/apt/examples/debugging.apt.vm | 180 ++--
.../site/apt/examples/inclusion-exclusion.apt.vm | 279 +++---
.../src/site/apt/examples/junit.apt.vm | 458 +++++-----
.../src/site/apt/examples/pojo-test.apt.vm | 94 +-
.../src/site/apt/examples/providers.apt.vm | 97 +-
.../src/site/apt/examples/single-test.apt.vm | 170 ++--
.../src/site/apt/examples/skipping-test.apt.vm | 224 +++---
.../src/site/apt/examples/system-properties.apt.vm | 274 +++---
.../src/site/apt/examples/testng.apt.vm | 402 ++++-----
.../src/site/apt/featurematrix.apt.vm | 49 +-
maven-surefire-plugin/src/site/apt/index.apt.vm | 175 ++--
maven-surefire-plugin/src/site/apt/usage.apt.vm | 710 +++++++--------
.../site/apt/examples/changing-report-name.apt.vm | 63 +-
.../src/site/apt/examples/cross-referencing.apt.vm | 111 +--
.../apt/examples/report-custom-location.apt.vm | 99 +--
.../src/site/apt/examples/show-failures.apt.vm | 77 +-
.../src/site/apt/usage.apt.vm | 62 +-
21 files changed, 2093 insertions(+), 2349 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/8970909c/maven-surefire-plugin/src/site/apt/api.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/api.apt.vm b/maven-surefire-plugin/src/site/apt/api.apt.vm
index 95c1a09..31572c1 100644
--- a/maven-surefire-plugin/src/site/apt/api.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/api.apt.vm
@@ -1,11 +1,11 @@
-------
-Provider API
-------
-Kristian Rosenvold
-------
-2010-12-09
-------
-
+ ------
+ Provider API
+ ------
+ Kristian Rosenvold
+ ------
+ 2010-12-09
+ ------
+
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements. See the NOTICE file
~~ distributed with this work for additional information
@@ -29,71 +29,64 @@ Kristian Rosenvold
Maven Surefire Provider API
-As of version 2.7 of surefire, there is a proposed public api available for
-external providers to use surefire features.
+ As of version 2.7 of surefire, there is a proposed public api available for
+ external providers to use surefire features.
-The key features of surefire are forking, reporting and directory/classpath scanning.
-The remaining features are implemented in the providers.
+ The key features of surefire are forking, reporting and directory/classpath scanning.
+ The remaining features are implemented in the providers.
-Please note that this API is still subject to change until otherwise declared, even in minor revisions. This would
-mostly happen to facilitate needs in new providers.
+ Please note that this API is still subject to change until otherwise declared, even in minor revisions. This would
+ mostly happen to facilitate needs in new providers.
* Requirements for a provider
-There are three things any provider must fulfill:
+ There are three things any provider must fulfill:
-* A provider must implement the <<
-<org.apache.maven.surefire.providerapi.SurefireProvider>>> interface.
+ * A provider must implement the <<<org.apache.maven.surefire.providerapi.SurefireProvider>>> interface.
- * A provider contains a <<
- <META-INF
- /services>>> file entry named <<
- <org.apache.maven.surefire.providerapi.SurefireProvider>>>
- ( as per {{{http://download.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html}ServiceLoader}}). This
- file
- contains the name of the actual provider class.
+ * A provider contains a <<<META-INF/services>>> file entry named <<<org.apache.maven.surefire.providerapi.SurefireProvider>>>
+ ( as per {{{http://download.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html}ServiceLoader}}). This file
+ contains the name of the actual provider class.
- * The actual provider class contains a one-arg constructor that accepts an instance of
- <<
- <org.apache.maven.surefire.providerapi.ProviderParameters>>>. This interface delivers all the surefire feature
- to the provider implementation, please see the javadoc of this interface for options.
+ * The actual provider class contains a one-arg constructor that accepts an instance of
+ <<<org.apache.maven.surefire.providerapi.ProviderParameters>>>. This interface delivers all the surefire feature
+ to the provider implementation, please see the javadoc of this interface for options.
- There are 4 well-known providers within surefire that are also implemented this way, so
- examples can be found by looking at the surefire source code itself. surefire-junit47 is
- the showcase implementation.
+ There are 4 well-known providers within surefire that are also implemented this way, so
+ examples can be found by looking at the surefire source code itself. surefire-junit47 is
+ the showcase implementation.
- The javadoc on the intefaces mentioned in this article should otherwise be sufficient to write a provider.
- Providers are added as dependencies to the surefire/failsafe plugins.
+ The javadoc on the intefaces mentioned in this article should otherwise be sufficient to write a provider.
+ Providers are added as dependencies to the surefire/failsafe plugins.
- ** API Changes for 2.11
+** API Changes for 2.11
- Prior to 2.11, the provider would do
+ Prior to 2.11, the provider would do
- +---+
- TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
- +---+
++---+
+ TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
++---+
- and the classes would arrive in sorted order. In 2.11, an additional step must be implemented by the
- provider;
+ and the classes would arrive in sorted order. In 2.11, an additional step must be implemented by the provider;
- +---+
- TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
- return providerParameters.getRunOrderCalculator().orderTestClasses( scanned );
- +---+
++---+
+ TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
+ return providerParameters.getRunOrderCalculator().orderTestClasses( scanned );
++---+
- ** API changes for 2.12.2:
+** API changes for 2.12.2:
- Prior to this version, the provider would do
+ Prior to this version, the provider would do
- +---+
- directoryScanner = booterParameters.getDirectoryScanner();
- final TestsToRun scanResult = directoryScanner.locateTestClasses( testClassLoader, testChecker );
- +---+
++---+
+ directoryScanner = booterParameters.getDirectoryScanner();
+ final TestsToRun scanResult = directoryScanner.locateTestClasses( testClassLoader, testChecker );
++---+
- from this version ProviderParameters#getDirectoryScanner has been deprecated, and *will* be removed
- for the next major version.
+ from this version ProviderParameters#getDirectoryScanner has been deprecated, and *will* be removed
+ for the next major version.
- +---+
- scanResult = booterParameters.getScanResult();
- final TestsToRun testsToRun = scanResult.applyFilter(testChecker, testClassLoader );
- +---+
++---+
+ scanResult = booterParameters.getScanResult();
+ final TestsToRun testsToRun = scanResult.applyFilter(testChecker, testClassLoader );
++---+
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/8970909c/maven-surefire-plugin/src/site/apt/developing.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/developing.apt.vm b/maven-surefire-plugin/src/site/apt/developing.apt.vm
index 6a5012b..954f0ce 100644
--- a/maven-surefire-plugin/src/site/apt/developing.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/developing.apt.vm
@@ -1,51 +1,51 @@
-------
-Developing surefire
-------
-Kristian Rosenvold
-------
-2011-03-07
-------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+ ------
+ Developing surefire
+ ------
+ Kristian Rosenvold
+ ------
+ 2011-03-07
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/doxia/references/apt-format.html
Developer Center
-When working with surefire, it is necessary to understand a few things:
+ When working with surefire, it is necessary to understand a few things:
* Multi-Module project
-The plugin is built as part of a multi-module plugin. The generated
-'project information' will suggest that you check out (e.g.)
-http://svn.apache.org/repos/asf/maven/surefire/trunk/${project.artifactId}.
-In fact, you need to check out (e.g.)
-http://svn.apache.org/repos/asf/maven/surefire/trunk and
-build from there.
+ The plugin is built as part of a multi-module plugin. The generated
+ 'project information' will suggest that you check out (e.g.)
+ http://svn.apache.org/repos/asf/maven/surefire/trunk/${project.artifactId}.
+ In fact, you need to check out (e.g.)
+ http://svn.apache.org/repos/asf/maven/surefire/trunk and
+ build from there.
* Making testcases for demonstrating problems
-When reporting an issue, it is immensely useful to create a small sample project
-that demonstrates the problem. Surefire already contains a large number of such
-projects, and they can be found at
-https://svn.apache.org/repos/asf/maven/surefire/trunk/surefire-integration-tests/src/test/resources/
-Typically you can check out one of the pre-existing projects and run it like this:
+ When reporting an issue, it is immensely useful to create a small sample project
+ that demonstrates the problem. Surefire already contains a large number of such
+ projects, and they can be found at
+ https://svn.apache.org/repos/asf/maven/surefire/trunk/surefire-integration-tests/src/test/resources/
+ Typically you can check out one of the pre-existing projects and run it like this:
+---+
svn co https://svn.apache.org/repos/asf/maven/surefire/trunk/surefire-integration-tests/src/test/resources/failsafe-buildfail
@@ -55,34 +55,34 @@ mvn -Dsurefire.version=2.12 verify
* Attaching a debugger
-Sometimes it's appropriate to attach a remote debugger to the surefire fork to try to determine what
-is /really/ going on. If you checkout & build trunk, you'd usually do something like this:
+ Sometimes it's appropriate to attach a remote debugger to the surefire fork to try to determine what
+ is /really/ going on. If you checkout & build trunk, you'd usually do something like this:
+---+
-mvn -Dmaven.surefire.debug=true install
+ mvn -Dmaven.surefire.debug=true install
+---+
-Load the source in your IDE, set a breakpoint at the start of ForkedBooter#main and attach
-a debugger to port 5005.
+ Load the source in your IDE, set a breakpoint at the start of ForkedBooter#main and attach
+ a debugger to port 5005.
* TestCases
-All patches to surefire must contain test coverage, either as an integration test
-or a unit test. All new features (changed/added plugin options) must be covered by
-and end-to-end integration test.
+ All patches to surefire must contain test coverage, either as an integration test
+ or a unit test. All new features (changed/added plugin options) must be covered by
+ and end-to-end integration test.
-There are
-numerous other integration tests that all operate upon small sample projects in
-surefire-integration-tests/src/test/resources
+ There are
+ numerous other integration tests that all operate upon small sample projects in
+ surefire-integration-tests/src/test/resources
-Example integration tests are Surefire141PluggableProvidersIT and the corresponding
-surefire-integration-tests/src/test/resources/surefire-141-pluggableproviders.
+ Example integration tests are Surefire141PluggableProvidersIT and the corresponding
+ surefire-integration-tests/src/test/resources/surefire-141-pluggableproviders.
* Essential source code reading list
-Some methods/classes reveal more about the basic working of a piece of code than others. The enclosed classes/methods
-are a "reading list" for getting quickly acquainted with the code:
+ Some methods/classes reveal more about the basic working of a piece of code than others. The enclosed classes/methods
+ are a "reading list" for getting quickly acquainted with the code:
+---+
AbstractSurefireMojo#executeAllProviders
@@ -92,36 +92,36 @@ ForkedBooter#main
* JDK Versions
-The surefire booter is capable of booting all the way back to jdk1.3. Specifically
-this means surefire-api, surefire-booter, common-junit3 and surefire-junit3 are
-source/target 1.3. The plugin and several providers are 1.5.
+ The surefire booter is capable of booting all the way back to jdk1.3. Specifically
+ this means surefire-api, surefire-booter, common-junit3 and surefire-junit3 are
+ source/target 1.3. The plugin and several providers are 1.5.
* Provider Isolation
-Classes in the SUT (Subject Under Test), override any classes within the
-surefire providers. This means providers using any
-third party dependencies (other than the test framework itself), should
-shade these classes to a different package.
+ Classes in the SUT (Subject Under Test), override any classes within the
+ surefire providers. This means providers using any
+ third party dependencies (other than the test framework itself), should
+ shade these classes to a different package.
* Common provider modules
-The surefire-providers module contains common-junitXX modules. These modules
-depend on the XX version of JUnit and can access the JUnit API's at the correct
-JUnit version level. Unit tests can also be written that will run with the
-correct JUnit version. At build time, all of the relevant parts of these "common"
-modules are just shaded into the providers jar files.
+ The surefire-providers module contains common-junitXX modules. These modules
+ depend on the XX version of JUnit and can access the JUnit API's at the correct
+ JUnit version level. Unit tests can also be written that will run with the
+ correct JUnit version. At build time, all of the relevant parts of these "common"
+ modules are just shaded into the providers jar files.
* Shadefire
-"Shadefire" is the first module to be run in the
-surefire build. This creates as shaded version of the JUnit provider, and this provider
-is thereafter used to build surefire itself (As of any release after 2.8). This is
-because the SUT overrides the provider, and the shadefire provider has been
-relocated to avoid this overriding when surefire is building itself.
+ "Shadefire" is the first module to be run in the
+ surefire build. This creates as shaded version of the JUnit provider, and this provider
+ is thereafter used to build surefire itself (As of any release after 2.8). This is
+ because the SUT overrides the provider, and the shadefire provider has been
+ relocated to avoid this overriding when surefire is building itself.
* Deploying/releasing surefire
-Surefire depends on a previous version of itself, which
-is too advanced for maven 2.2.x dependency resolution, and maven 3.x is
-required to build surefire
\ No newline at end of file
+ Surefire depends on a previous version of itself, which
+ is too advanced for maven 2.2.x dependency resolution, and maven 3.x is
+ required to build surefire
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/8970909c/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 719b524..7fac4e8 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
@@ -1,252 +1,174 @@
-------
-Classloading and Forking
-------
-Dan Fabulich
-------
-2010-01-09
-------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+ ------
+ Classloading and Forking
+ ------
+ Dan Fabulich
+ ------
+ 2010-01-09
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/doxia/references/apt-format.html
Classloading and Forking in Maven Surefire
-This page discusses classloading and forking under Maven Surefire which is a shared component used by both
-the Surefire and Failsafe Maven plugins, with an eye towards troubleshooting problems.
+ This page discusses classloading and forking under Maven Surefire which is a shared component used by both
+ the Surefire and Failsafe Maven plugins, with an eye towards troubleshooting problems.
* Executive Summary
-If you're having problems, you'll probably want to tinker with these three settings: <<
-<forkMode>>>, <<
- <useSystemClassLoader>>>, and <<
- <useManifestOnlyJar>>>.
-
- * What problem does the Maven Surefire project solve?
-
- Initially, the problem seems simple enough. Just launch Java with a classpath, like this:
-
- +---+
- java -classpath foo.jar:bar.jar MyApp
- +---+
-
- But there's a problem here: on some operating systems (Windows), there's a limit on how long you can make
- your command line, and therefore a limit on how long you can make your classpath. The limit is different
- on different versions of Windows; in some versions only a few hundred characters are allowed, in others
- a few thousand, but the limit can be pretty severe in either case.
-
- * Update for Maven Surefire 2.8.2
-
- It turns out setting the <<
- <CLASSPATH>>> as an environment variable may remove most of the
- practical length limitations, as documented in
- {{{http://jira.codehaus.org/browse/SUREFIRE-727}SUREFIRE-727}}.
- This means most of the length-related problems in this article may be outdated.
-
- * How do people solve this problem in general?
-
- There are two "tricks" you can use to workaround this problem; both of them can cause other problems in
- some cases.
-
- 1. <
- <Isolated Classloader>>: One workaround is to use an isolated classloader.
- Instead of launching MyApp directly, we can launch some other app (a "booter")
- with a much shorter classpath. We can then create a new java.lang.ClassLoader
- (usually a java.net.URLClassLoader) with your classpath configured. The booter
- can then load up MyApp from the classloader; when MyApp refers to other classes,
- they will be automatically loaded from our isolated classloader.
-
- The problem with using an isolated classloader is that your classpath isn't
- <really> correct, and some apps can detect this and object. For example, the
- system property <<
- <java.class.path>>> won't include your jars; if your app notices
- this, it could cause a problem.
-
- There's another similar problem with using an isolated classloader: any class
- may call the static method <<
- <ClassLoader.getSystemClassLoader
- ()>>> and attempt to
- load classes out of that classloader, instead of using the default classloader.
- Classes often do this if they need to create classloaders of their own.
- Unfortunately, Java-based web application servers like Jetty, Tomcat, BEA
- WebLogic and IBM WebSphere are very likely to try to escape the confines of an
- isolated classloader.
-
- 2. <
- <Manifest-Only JAR>>: Another workaround is to use a "manifest-only jar." In
- this case, you create a temporary jar that's almost completely empty, except for
- a META-INF/MANIFEST.MF file. Java manifests can contain attributes that the Java
- VM will honor as directives; for example, you can have a "Class-Path" attribute,
- which contains a list of other jars to add to the classpath. So then you can run
- your code like this:
-
- +---+
- java -classpath booter.jar MyApp
- +---+
-
- This is a bit more realistic, because in this case the system classloader, the
- thread context classloader and the default classloader are all the same; there's
- no possibility of "escaping" the classloader. But this is still a weird
- simulation of a "normal" classpath, and it's still possible for apps to notice
- this. Again, <<
- <java.class.path>>> may not be what you'd expect ("why does it contain
- only one jar?"). Additionally, it's possible to query the system classloader to
- get the list of jars back out of it; your app may be confused if it finds only
- our <<
- <booter.jar>>> there!
-
- * Advantages/Disadvantages of each solution
-
- If your app tries to interrogate its own classloader for a list of jars, it may
- work better under an isolated classloader than it would with a manifest-only
- jar. However, if your app tries to escape its default classloader, it may not
- work under an isolated classloader at all.
-
- One advantage of using an isolated classloader is that it's the only way to use
- an isolated classloader without forking a separate process, running all of the
- tests in the same process as Maven itself. But that itself can be pretty risky,
- especially if Maven is running embedded in your IDE!
-
- Finally, of course, you could just try to wire up a plain old Java classpath and
- hope
- it's short enough. The worst case there is that your classpath might work
- on some machines and not others. Windows boxes would behave differently from
- Linux boxes; users with short user names might have more success than users
- with long user names, etc. For this reason, we chose not to make the basic
- classpath the default, though we do provide it as an option (mostly as a last
- resort).
-
- * What does Maven Surefire do?
-
- Surefire provides a mechanism for using multiple strategies. The main parameter
- that
- determines this is called <<
- <useSystemClassLoader>>>. If <<
- <useSystemClassLoader>>> is
- <<
- <true>>>, then we use a manifest-only JAR; otherwise, we use an isolated
- classloader. If you want to use a basic plain old Java classpath,
- you can set
- <<
- <useManifestOnlyJar
- =false>>> which only has an effect when <<
- <useSystemClassLoader
- =true>>>.
-
- The default value for <<
- <useSystemClassLoader>>> changed between Surefire 2.3 and
- Surefire 2.4, which was a pretty significant change. In Surefire
- 2.3,
- <<
- <useSystemClassLoader>>> was <<
- <false>>> by default, and we used an isolated classloader.
- In Surefire 2.4, <<
- <useSystemClassLoader>>> is <<
- <true>>> by default. No value works for
- everyone, but we think this default is an
- improvement; a bunch of
- hard-to-diagnose bugs get better when we <<
- <useSystemClassLoader
- =true>>>.
-
- Unfortunately, if <<
- <useSystemClassLoader>>> is set incorrectly for
- your app, you're going to
- have a problem on your hands that can be
- quite difficult to diagnose. You might
- even be forced to read a long doc page like
- this one. ;-)
-
- If you're having problems loading classes,
- try setting <<
- <useSystemClassLoader
- =false>>>
- to see if that helps. You can do that with
- the POM snippet below, or by setting
- <<<-Dsurefire.useSystemClassLoader=false>>>.
- If that doesn't work, try setting
- <<
- <useSystemClassLoader>>> back to <<
- <true>>> and setting <<
- <useManifestOnlyJar>>> to <<
- <false>>>.
-
- +---+
- <project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <useSystemClassLoader>
- false
- </useSystemClassLoader>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
- </project>
- +---+
-
- * Debugging Classpath
- Problems
-
- If you've read this far,
- you're probably fully
- equipped to diagnose
- problems that may occur
- during classloading. Here's
- some general tips to try:
-
- * 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.
-
- * 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.
-
- * Run mvn with
- -Dmaven.${thisPlugin.toLowerCase()}
- .debug, and attach to
- the running process with
- a debugger.
\ No newline at end of file
+ If you're having problems, you'll probably want to tinker with these three settings: <<<forkMode>>>, <<<useSystemClassLoader>>>, and <<<useManifestOnlyJar>>>.
+
+* What problem does the Maven Surefire project solve?
+
+ Initially, the problem seems simple enough. Just launch Java with a classpath, like this:
+
++---+
+java -classpath foo.jar:bar.jar MyApp
++---+
+
+ But there's a problem here: on some operating systems (Windows), there's a limit on how long you can make
+ your command line, and therefore a limit on how long you can make your classpath. The limit is different
+ on different versions of Windows; in some versions only a few hundred characters are allowed, in others
+ a few thousand, but the limit can be pretty severe in either case.
+
+* Update for Maven Surefire 2.8.2
+
+ It turns out setting the <<<CLASSPATH>>> as an environment variable may remove most of the
+ practical length limitations, as documented in {{{http://jira.codehaus.org/browse/SUREFIRE-727}SUREFIRE-727}}.
+ This means most of the length-related problems in this article may be outdated.
+
+* How do people solve this problem in general?
+
+ There are two "tricks" you can use to workaround this problem; both of them can cause other problems in some cases.
+
+ 1. <<Isolated Classloader>>: One workaround is to use an isolated classloader.
+ Instead of launching MyApp directly, we can launch some other app (a "booter")
+ with a much shorter classpath. We can then create a new java.lang.ClassLoader
+ (usually a java.net.URLClassLoader) with your classpath configured. The booter
+ can then load up MyApp from the classloader; when MyApp refers to other classes,
+ they will be automatically loaded from our isolated classloader.
+
+ The problem with using an isolated classloader is that your classpath isn't
+ <really> correct, and some apps can detect this and object. For example, the
+ system property <<<java.class.path>>> won't include your jars; if your app notices
+ this, it could cause a problem.
+
+ There's another similar problem with using an isolated classloader: any class
+ may call the static method <<<ClassLoader.getSystemClassLoader()>>> and attempt to
+ load classes out of that classloader, instead of using the default classloader.
+ Classes often do this if they need to create classloaders of their own.
+ Unfortunately, Java-based web application servers like Jetty, Tomcat, BEA
+ WebLogic and IBM WebSphere are very likely to try to escape the confines of an
+ isolated classloader.
+
+ 2. <<Manifest-Only JAR>>: Another workaround is to use a "manifest-only jar." In
+ this case, you create a temporary jar that's almost completely empty, except for
+ a META-INF/MANIFEST.MF file. Java manifests can contain attributes that the Java
+ VM will honor as directives; for example, you can have a "Class-Path" attribute,
+ which contains a list of other jars to add to the classpath. So then you can run
+ your code like this:
+
++---+
+java -classpath booter.jar MyApp
++---+
+
+ This is a bit more realistic, because in this case the system classloader, the
+ thread context classloader and the default classloader are all the same; there's
+ no possibility of "escaping" the classloader. But this is still a weird
+ simulation of a "normal" classpath, and it's still possible for apps to notice
+ this. Again, <<<java.class.path>>> may not be what you'd expect ("why does it contain
+ only one jar?"). Additionally, it's possible to query the system classloader to
+ get the list of jars back out of it; your app may be confused if it finds only
+ our <<<booter.jar>>> there!
+
+* Advantages/Disadvantages of each solution
+
+ If your app tries to interrogate its own classloader for a list of jars, it may
+ work better under an isolated classloader than it would with a manifest-only
+ jar. However, if your app tries to escape its default classloader, it may not
+ work under an isolated classloader at all.
+
+ One advantage of using an isolated classloader is that it's the only way to use
+ an isolated classloader without forking a separate process, running all of the
+ tests in the same process as Maven itself. But that itself can be pretty risky,
+ especially if Maven is running embedded in your IDE!
+
+ Finally, of course, you could just try to wire up a plain old Java classpath and hope
+ it's short enough. The worst case there is that your classpath might work
+ on some machines and not others. Windows boxes would behave differently from
+ Linux boxes; users with short user names might have more success than users
+ with long user names, etc. For this reason, we chose not to make the basic
+ classpath the default, though we do provide it as an option (mostly as a last
+ resort).
+
+* What does Maven Surefire do?
+
+ Surefire provides a mechanism for using multiple strategies. The main parameter that
+ determines this is called <<<useSystemClassLoader>>>. If <<<useSystemClassLoader>>> is
+ <<<true>>>, then we use a manifest-only JAR; otherwise, we use an isolated
+ classloader. If you want to use a basic plain old Java classpath, you can set
+ <<<useManifestOnlyJar=false>>> which only has an effect when <<<useSystemClassLoader=true>>>.
+
+ The default value for <<<useSystemClassLoader>>> changed between Surefire 2.3 and
+ Surefire 2.4, which was a pretty significant change. In Surefire 2.3,
+ <<<useSystemClassLoader>>> was <<<false>>> by default, and we used an isolated classloader.
+ In Surefire 2.4, <<<useSystemClassLoader>>> is <<<true>>> by default. No value works for
+ everyone, but we think this default is an improvement; a bunch of
+ hard-to-diagnose bugs get better when we <<<useSystemClassLoader=true>>>.
+
+ Unfortunately, if <<<useSystemClassLoader>>> is set incorrectly for your app, you're going to
+ have a problem on your hands that can be quite difficult to diagnose. You might
+ even be forced to read a long doc page like this one. ;-)
+
+ If you're having problems loading classes, try setting <<<useSystemClassLoader=false>>>
+ to see if that helps. You can do that with the POM snippet below, or by setting
+ <<<-Dsurefire.useSystemClassLoader=false>>>. If that doesn't work, try setting
+ <<<useSystemClassLoader>>> back to <<<true>>> and setting <<<useManifestOnlyJar>>> to <<<false>>>.
+
++---+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <useSystemClassLoader>false</useSystemClassLoader>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
+
+* Debugging Classpath Problems
+
+ If you've read this far, you're probably fully equipped to diagnose problems that may occur during classloading. Here's some general tips to try:
+
+ * 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.
+
+ * 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.
+
+ * Run mvn with -Dmaven.${thisPlugin.toLowerCase()}.debug, and attach to the running process with a debugger.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/8970909c/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm b/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
index 2c425b9..2b2ad4c 100644
--- a/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/configuring-classpath.apt.vm
@@ -1,146 +1,135 @@
-------
-Configuring the Classpath
-------
-Pascal Lambert
-------
-2010-01-09
-------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+ ------
+ Configuring the Classpath
+ ------
+ Pascal Lambert
+ ------
+ 2010-01-09
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/doxia/references/apt-format.html
The Default Classpath
-The surefire plugin builds the test classpath in the following order:
+ The surefire plugin builds the test classpath in the following order:
#{if}(${project.artifactId}=="maven-surefire-plugin")
-[[1]] The {{{../test-mojo.html#testClassesDirectory}test-classes}} directory
+ [[1]] The {{{../test-mojo.html#testClassesDirectory}test-classes}} directory
-[[2]] The {{{../test-mojo.html#classesDirectory}classes}} directory
+ [[2]] The {{{../test-mojo.html#classesDirectory}classes}} directory
#{else}
-[[1]] The {{{../integration-test-mojo.html#testClassesDirectory}test-classes}} directory
+ [[1]] The {{{../integration-test-mojo.html#testClassesDirectory}test-classes}} directory
-[[2]] The {{{../integration-test-mojo.html#classesDirectory}classes}} directory
+ [[2]] The {{{../integration-test-mojo.html#classesDirectory}classes}} directory
#{end}
-[[3]] The project dependencies
+ [[3]] The project dependencies
-[[4]] Additional classpath elements
+ [[4]] Additional classpath elements
Additional Classpath Elements
-If you need to put more stuff in your classpath when ${thisPlugin} executes (e.g some funky resources or a container specific JAR),
-we normally recommend you add it to your classpath as a dependency. Consider deploying shared jars to a private remote repository for your
-organization.
-
-But, if you must, you can use the <<
-<additionalClasspathElements>>> element to add custom resources/jars to your classpath.
- This will be treated as an absolute file system path, so you may want use $\{basedir\} or another property combined
- with a relative path.
- Note that additional classpath elements are added to the end of the classpath, so you cannot use these to
- override project dependencies or resources.
-
- +---+
- <project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <additionalClasspathElements>
- <additionalClasspathElement>path/to/additional/resources</additionalClasspathElement>
- <additionalClasspathElement>path/to/additional/jar</additionalClasspathElement>
- </additionalClasspathElements>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
- </project>
- +---+
-
- Removing Dependency Classpath Elements
-
- Dependencies can be removed from the test classpath using the parameters <<
- <classpathDependencyExcludes>>> and
- <<
- <classpathDependencyScopeExclude>>>. A list of specific dependencies can be removed from the
- classpath by specifying the groupId:artifactId to be removed.
-
- +---+
- <project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <classpathDependencyExcludes>
- <classpathDependencyExcludes>org.apache.commons:commons-email
- </classpathDependencyExcludes>
- </classpathDependencyExcludes>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
- </project>
- +---+
-
- Dependencies under a certain scope can be removed from the classpath using
- <<
- <classpathDependencyScopeExclude>>>. The valid values for the dependency scope
- exclude are defined by <<
- <org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter>>>.
-
- * <
- <compile>> - system, provided, compile
-
- * <
- <runtime>> - compile, runtime
-
- * <
- <test>> - system, provided, compile, runtime, test
-
- +---+
- <project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <classpathDependencyScopeExclude>runtime
- </classpathDependencyScopeExclude>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
- </project>
- +---+
+ If you need to put more stuff in your classpath when ${thisPlugin} executes (e.g some funky resources or a container specific JAR),
+ we normally recommend you add it to your classpath as a dependency. Consider deploying shared jars to a private remote repository for your
+ organization.
+
+ But, if you must, you can use the <<<additionalClasspathElements>>> element to add custom resources/jars to your classpath.
+ This will be treated as an absolute file system path, so you may want use $\{basedir\} or another property combined with a relative path.
+ Note that additional classpath elements are added to the end of the classpath, so you cannot use these to
+ override project dependencies or resources.
+
++---+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <additionalClasspathElements>
+ <additionalClasspathElement>path/to/additional/resources</additionalClasspathElement>
+ <additionalClasspathElement>path/to/additional/jar</additionalClasspathElement>
+ </additionalClasspathElements>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
+
+Removing Dependency Classpath Elements
+
+ Dependencies can be removed from the test classpath using the parameters <<<classpathDependencyExcludes>>> and
+ <<<classpathDependencyScopeExclude>>>. A list of specific dependencies can be removed from the
+ classpath by specifying the groupId:artifactId to be removed.
+
++---+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <classpathDependencyExcludes>
+ <classpathDependencyExcludes>org.apache.commons:commons-email</classpathDependencyExcludes>
+ </classpathDependencyExcludes>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
+
+ Dependencies under a certain scope can be removed from the classpath using
+ <<<classpathDependencyScopeExclude>>>. The valid values for the dependency scope
+ exclude are defined by <<<org.apache.maven.artifact.resolver.filter.ScopeArtifactFilter>>>.
+
+ * <<compile>> - system, provided, compile
+
+ * <<runtime>> - compile, runtime
+
+ * <<test>> - system, provided, compile, runtime, test
+
++---+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <classpathDependencyScopeExclude>runtime</classpathDependencyScopeExclude>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/8970909c/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 9eba148..f07ff08 100644
--- a/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/debugging.apt.vm
@@ -1,100 +1,92 @@
-------
-Debugging Tests
-------
-Dan Fabulich
-------
-2010-01-09
-------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+ ------
+ Debugging Tests
+ ------
+ Dan Fabulich
+ ------
+ 2010-01-09
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/doxia/references/apt-format.html
Debugging Tests
-Sometimes you need to debug the tests exactly as Maven ran them. Here's how!
+ Sometimes you need to debug the tests exactly as Maven ran them. Here's how!
Forked Tests
-By default, Maven runs your tests in a separate ("forked") process. You can use the <<
-<maven.${thisPlugin.toLowerCase()}.debug>>> property
- to debug your forked tests remotely, like this:
-
- #{if}(${project.artifactId}=="maven-surefire-plugin")
- +---+
- mvn -Dmaven.${thisPlugin.toLowerCase()}.debug test
- +---+
- #{else}
- +---+
- mvn -Dmaven.${thisPlugin.toLowerCase()}.debug verify
- +---+
- #{end}
-
- The tests will automatically pause and await a remote debugger on port 5005. You can then attach to the running
- tests
- using Eclipse. You can setup a "Remote Java Application" launch configuration via the menu
- command "Run" > "Open Debug Dialog..."
-
- If you need to configure a different port, you may pass a more detailed value. For example, the command below will
- use port 8000
- instead of port 5005.
-
- #{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
- +---+
- #{else}
- +---+
- mvn -Dmaven.surefire.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.
-
- #{if}(${project.artifactId}=="maven-surefire-plugin")
- +---+
- mvn -DforkMode=never test
- +---+
- #{else}
- +---+
- mvn -DforkMode=never verify
- +---+
- #{end}
-
- Then all you need to do is debug Maven itself. Since Maven 2.0.8, Maven has shipped with a "mvnDebug" shell
- script that you can
- use to launch Maven with convenient debugging options:
-
- #{if}(${project.artifactId}=="maven-surefire-plugin")
- +---+
- mvnDebug -DforkMode=never test
- +---+
- #{else}
- +---+
- mvnDebug -DforkMode=never verify
- +---+
- #{end}
-
- Then you can attach Eclipse to Maven itself, which may be easier/more convenient than debugging the forked
- executable.
\ No newline at end of file
+ By default, Maven runs your tests in a separate ("forked") process. You can use the <<<maven.${thisPlugin.toLowerCase()}.debug>>> property
+ to debug your forked tests remotely, like this:
+
+#{if}(${project.artifactId}=="maven-surefire-plugin")
++---+
+mvn -Dmaven.${thisPlugin.toLowerCase()}.debug test
++---+
+#{else}
++---+
+mvn -Dmaven.${thisPlugin.toLowerCase()}.debug verify
++---+
+#{end}
+
+ The tests will automatically pause and await a remote debugger on port 5005. You can then attach to the running tests
+ using Eclipse. You can setup a "Remote Java Application" launch configuration via the menu
+ command "Run" > "Open Debug Dialog..."
+
+ If you need to configure a different port, you may pass a more detailed value. For example, the command below will use port 8000
+ instead of port 5005.
+
+#{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
++---+
+#{else}
++---+
+mvn -Dmaven.surefire.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.
+
+#{if}(${project.artifactId}=="maven-surefire-plugin")
++---+
+mvn -DforkMode=never test
++---+
+#{else}
++---+
+mvn -DforkMode=never verify
++---+
+#{end}
+
+ Then all you need to do is debug Maven itself. Since Maven 2.0.8, Maven has shipped with a "mvnDebug" shell script that you can
+ use to launch Maven with convenient debugging options:
+
+#{if}(${project.artifactId}=="maven-surefire-plugin")
++---+
+mvnDebug -DforkMode=never test
++---+
+#{else}
++---+
+mvnDebug -DforkMode=never verify
++---+
+#{end}
+
+ Then you can attach Eclipse to Maven itself, which may be easier/more convenient than debugging the forked executable.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/maven-surefire/blob/8970909c/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
----------------------------------------------------------------------
diff --git a/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm b/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
index 172d648..4c7d978 100644
--- a/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
@@ -1,165 +1,164 @@
-------
-Inclusions and Exclusions of Tests
-------
-Allan Ramirez
-------
-2010-01-09
-------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+ ------
+ Inclusions and Exclusions of Tests
+ ------
+ Allan Ramirez
+ ------
+ 2010-01-09
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/doxia/references/apt-format.html
Inclusions and Exclusions of Tests
* Inclusions
-By default, the ${thisPlugin} Plugin will automatically include all test classes
-with the following wildcard patterns:
+ By default, the ${thisPlugin} Plugin will automatically include all test classes
+ with the following wildcard patterns:
#{if}(${project.artifactId}=="maven-surefire-plugin")
-* <<<"**/Test*.java">>> - includes all of its subdirectories and all java
-filenames that start with "Test".
+ * <<<"**/Test*.java">>> - includes all of its subdirectories and all java
+ filenames that start with "Test".
-* <<<"**/*Test.java">>> - includes all of its subdirectories and all java
-filenames that end with "Test".
+ * <<<"**/*Test.java">>> - includes all of its subdirectories and all java
+ filenames that end with "Test".
-* <<<"**/*TestCase.java">>> - includes all of its subdirectories and all java
-filenames that end with "TestCase".
+ * <<<"**/*TestCase.java">>> - includes all of its subdirectories and all java
+ filenames that end with "TestCase".
#{else}
-* <<<"**/IT*.java">>> - includes all of its subdirectories and all java
-filenames that start with "IT".
+ * <<<"**/IT*.java">>> - includes all of its subdirectories and all java
+ filenames that start with "IT".
-* <<<"**/*IT.java">>> - includes all of its subdirectories and all java
-filenames that end with "IT".
+ * <<<"**/*IT.java">>> - includes all of its subdirectories and all java
+ filenames that end with "IT".
-* <<<"**/*ITCase.java">>> - includes all of its subdirectories and all java
-filenames that end with "ITCase".
+ * <<<"**/*ITCase.java">>> - includes all of its subdirectories and all java
+ filenames that end with "ITCase".
#{end}
-[]
+ []
-If the test classes does not go with the naming convention, then configure
-${thisPlugin} Plugin and specify the tests you want to include.
+ If the test classes does not go with the naming convention, then configure
+ ${thisPlugin} Plugin and specify the tests you want to include.
+---+
<project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <includes>
- <include>Sample.java</include>
- </includes>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <includes>
+ <include>Sample.java</include>
+ </includes>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
</project>
+---+
* Exclusions
-There are certain times when some tests are causing the build to fail.
-Excluding them is one of the best workarounds to continue the build.
-Exclusions can be done by configuring the <
-<excludes>> property of the
- plugin.
-
- #{if}(${project.artifactId}=="maven-surefire-plugin")
- +---+
- <project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <excludes>
- <exclude>**/TestCircle.java</exclude>
- <exclude>**/TestSquare.java</exclude>
- </excludes>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
- </project>
- +---+
- #{else}
- +---+
- <project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <excludes>
- <exclude>**/CircleIT.java</exclude>
- <exclude>**/SquareIT.java</exclude>
- </excludes>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
- </project>
- +---+
- #{end}
-
- * Regular expression support
-
- An include/exclude pattern can be an ant-style path expression, but
- regular expressions are also supported through this syntax:
-
- +---+
- <project>
- [...]
- <build>
- <plugins>
- <plugin>
- <groupId>${project.groupId}</groupId>
- <artifactId>${project.artifactId}</artifactId>
- <version>${project.version}</version>
- <configuration>
- <includes>
- <include>%regex[.*[Cat|Dog].*Test.*]</include>
- </includes>
- </configuration>
- </plugin>
- </plugins>
- </build>
- [...]
- </project>
- +---+
-
- Note the syntax %regex[expr], where expr is the actual expression and the rest is just wrapping. Also
- note that regex matches are done over .class files and not .java files.
\ No newline at end of file
+ There are certain times when some tests are causing the build to fail.
+ Excluding them is one of the best workarounds to continue the build.
+ Exclusions can be done by configuring the <<excludes>> property of the
+ plugin.
+
+#{if}(${project.artifactId}=="maven-surefire-plugin")
++---+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <excludes>
+ <exclude>**/TestCircle.java</exclude>
+ <exclude>**/TestSquare.java</exclude>
+ </excludes>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
+#{else}
++---+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <excludes>
+ <exclude>**/CircleIT.java</exclude>
+ <exclude>**/SquareIT.java</exclude>
+ </excludes>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
+#{end}
+
+* Regular expression support
+
+ An include/exclude pattern can be an ant-style path expression, but
+ regular expressions are also supported through this syntax:
+
++---+
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>${project.artifactId}</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <includes>
+ <include>%regex[.*[Cat|Dog].*Test.*]</include>
+ </includes>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++---+
+
+ Note the syntax %regex[expr], where expr is the actual expression and the rest is just wrapping. Also
+ note that regex matches are done over .class files and not .java files.
\ No newline at end of file