Author: dennisl
Date: Sat Jan 9 20:24:47 2010
New Revision: 897534
URL: http://svn.apache.org/viewvc?rev=897534&view=rev
Log:
o Minor corrections to the site, including fixing typos and adding formating
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/additional-classpath.apt.vm
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/debugging.apt
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/system-properties.apt.vm
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/usage.apt
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/additional-classpath.apt.vm
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/additional-classpath.apt.vm?rev=897534&r1=897533&r2=897534&view=diff
==============================================================================
---
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/additional-classpath.apt.vm
(original)
+++
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/additional-classpath.apt.vm
Sat Jan 9 20:24:47 2010
@@ -3,18 +3,18 @@
------
Pascal Lambert
------
- March 2008
+ 2010-01-09
------
Additional Classpath Elements
- If you need to put more stuff in your classpath when Surefire executes (e.g
some funky resources or a container special jar),
+ If you need to put more stuff in your classpath when Surefire 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
+ 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.
+---+
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm?rev=897534&r1=897533&r2=897534&view=diff
==============================================================================
---
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
(original)
+++
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/class-loading.apt.vm
Sat Jan 9 20:24:47 2010
@@ -3,7 +3,7 @@
------
Dan Fabulich
------
- May 2008
+ 2010-01-09
------
Classloading and Forking in Maven Surefire
@@ -13,7 +13,7 @@
* 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: <<<forkMode>>>, <<<useSystemClassLoader>>>, and
<<<useManifestOnlyJar>>>.
* What problem does Surefire solve?
@@ -30,7 +30,7 @@
* How do people solve this problem in general?
- There are two "tricks" you can use to workaround this problem; both of them
are can cause other problems in some cases.
+ 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")
@@ -41,18 +41,18 @@
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
+ 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
+ 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....
+ 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
+ 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,
@@ -67,10 +67,10 @@
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
+ 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!
+ our <<<booter.jar>>> there!
* Advantages/Disadvantages of each solution
@@ -95,27 +95,27 @@
* What does 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
+ 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
+ <<<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
+ <<<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
+ 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
+
+ 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.
-
+ <<<-Dsurefire.useSystemClassLoader=false>>>. If that doesn't work, try
setting
+ <<<useSystemClassLoader>>> back to <<<true>>> and setting
<<<useManifestOnlyJar>>> to <<<false>>>.
+
+---+
<project>
[...]
@@ -141,8 +141,8 @@
* 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 <<<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.
+ * 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.surefire.debug, and attach to the running process with
a debugger.
+ * Run mvn with <<<-Dmaven.surefire.debug>>>, and attach to the running
process with a debugger.
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/debugging.apt
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/debugging.apt?rev=897534&r1=897533&r2=897534&view=diff
==============================================================================
---
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/debugging.apt
(original)
+++
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/debugging.apt
Sat Jan 9 20:24:47 2010
@@ -3,13 +3,13 @@
------
Dan Fabulich
------
- January 2008
+ 2010-01-09
------
Debugging Tests
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.surefire.debug>>> property
@@ -23,7 +23,7 @@
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 value below will use port 8000
+ 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.
+---+
@@ -40,7 +40,7 @@
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:
-
+
+---+
mvnDebug -DforkMode=never test
+---+
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm?rev=897534&r1=897533&r2=897534&view=diff
==============================================================================
---
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
(original)
+++
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/inclusion-exclusion.apt.vm
Sat Jan 9 20:24:47 2010
@@ -3,7 +3,7 @@
------
Allan Ramirez
------
- July 2006
+ 2010-01-09
------
Inclusions and Exclusions of Tests
@@ -13,13 +13,13 @@
By default, the Surefire Plugin will automatically include all test classes
with the following wildcard patterns:
- * <"**/Test*.java"> - includes all of its subdirectory and all java
+ * <"**/Test*.java"> - includes all of its subdirectories and all java
filenames that start with "Test".
- * <"**/*Test.java"> - includes all of its subdirectory and all java
+ * <"**/*Test.java"> - includes all of its subdirectories and all java
filenames that end with "Test".
- * <"**/*TestCase.java"> - includes all of its subdirectory and all java
+ * <"**/*TestCase.java"> - includes all of its subdirectories and all java
filenames that end with "TestCase".
[]
@@ -75,4 +75,4 @@
</build>
[...]
</project>
-+---+
\ No newline at end of file
++---+
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/system-properties.apt.vm
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/system-properties.apt.vm?rev=897534&r1=897533&r2=897534&view=diff
==============================================================================
---
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/system-properties.apt.vm
(original)
+++
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/system-properties.apt.vm
Sat Jan 9 20:24:47 2010
@@ -4,17 +4,17 @@
Allan Ramirez
Dan Tran
------
- July 2006
+ 2010-01-09
------
Using System Properties
There are two ways to add a list of system properties to Surefire:
-* systemProperyVariable
+* systemPropertyVariables
- This configuration is the replacement of the deprecated <systemProperies>.
It can accept any value
- from Maven's properties that can be converted <<to String value>>
+ This configuration is the replacement of the deprecated
<<<systemProperties>>>. It can accept any value
+ from Maven's properties that can be converted <<to String value>>.
+---+
<project>
@@ -40,7 +40,7 @@
+---+
-* systemProperties ( deprecated )
+* systemProperties ( deprecated )
+---+
<project>
@@ -67,10 +67,10 @@
</project>
+---+
- Take note that <<String valued>> properties can only be passed as system
+ Take note that only <<String valued>> properties can be passed as system
properties. Any attempt to pass any other Maven variable type (i.e.
<<<List>>>
or a <<<URL>>> variable) will cause the variable expression to be passed
- literally (unevaluated). So having an example below:
+ literally (unevaluated). So having the example below:
+---+
<project>
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm?rev=897534&r1=897533&r2=897534&view=diff
==============================================================================
---
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
(original)
+++
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
Sat Jan 9 20:24:47 2010
@@ -3,7 +3,7 @@
------
Brett Porter <[email protected]>
------
- 2 May 2006
+ 2010-01-09
------
Using TestNG
@@ -13,21 +13,21 @@
To get started with TestNG, include the following dependency in your project:
+---+
-[...]
- <dependency>
- <groupId>org.testng</groupId>
- <artifactId>testng</artifactId>
- <version>5.8</version>
- <scope>test</scope>
- <classifier>jdk15</classifier>
- </dependency>
-[...]
+ [...]
+ <dependency>
+ <groupId>org.testng</groupId>
+ <artifactId>testng</artifactId>
+ <version>5.8</version>
+ <scope>test</scope>
+ <classifier>jdk15</classifier>
+ </dependency>
+ [...]
+---+
- <<Note:>> if you are using JDK 1.4 Javadoc annotations for your TestNG
tests, replace jdk15 with jdk14 above.
+ <<Note:>> if you are using JDK 1.4 Javadoc annotations for your TestNG
tests, replace the classifier <<<jdk15>>> with <<<jdk14>>> above.
This is the only step that is required to get started - you can now create
tests in your test source directory
- (eg, <<<src/test/java>>>, and as long as they are named using the defaults
such as *Test.java they will be run
+ (eg, <<<src/test/java>>>. As long as they are named using the defaults such
as <<<*Test.java>>> they will be run
by Surefire as TestNG tests.
If you'd like to use a different naming scheme, you can change the
<<<includes>>> parameter, as discussed in the
@@ -36,21 +36,21 @@
* Using Suite XML Files
Another alternative is to use TestNG suite XML files. This allows flexible
configuration of the tests to be run.
- These files are created as normal, and then added to the Surefire Plugin
configuration:
+ These files are created in the normal way, and then added to the Surefire
Plugin configuration:
+---+
-[...]
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <suiteXmlFiles>
- <suiteXmlFile>testng.xml</suiteXmlFile>
- </suiteXmlFiles>
- </configuration>
- </plugin>
-[...]
+ [...]
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <suiteXmlFiles>
+ <suiteXmlFile>testng.xml</suiteXmlFile>
+ </suiteXmlFiles>
+ </configuration>
+ </plugin>
+ [...]
+---+
This configuration will override the includes and excludes patterns and run
all tests in the suite files.
@@ -61,41 +61,38 @@
into your TestNG test, by specifying them as system properties, like this:
+---+
-[...]
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <systemProperties>
- <property>
- <name>browser</name>
- <value>firefox</value>
- </property>
- </systemProperties>
- </configuration>
- </plugin>
-[...]
+ [...]
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <systemPropertyVariables>
+ <propertyName>firefox</propertyName>
+ </systemPropertyVariables>
+ </configuration>
+ </plugin>
+ [...]
+---+
For more information about setting system properties in Surefire tests, see
{{{system-properties.html}System Properties}}.
* Using Groups
- TestNG allows you to group your tests. You can then execute a specific group
or groups. To do this with Surefire,
+ TestNG allows you to group your tests. You can then execute one or more
specific groups. To do this with Surefire,
use the <<<groups>>> parameter, for example:
+---+
-[...]
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <groups>functest,perftest</groups>
- </configuration>
- </plugin>
-[...]
+ [...]
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <groups>functest,perftest</groups>
+ </configuration>
+ </plugin>
+ [...]
+---+
Likewise, the <<<excludedGroups>>> parameter can be used to run all but a
certain set of groups.
@@ -107,17 +104,17 @@
For example:
+---+
-[...]
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <parallel>methods</parallel>
- <threadCount>10</threadCount>
- </configuration>
- </plugin>
-[...]
+ [...]
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <parallel>methods</parallel>
+ <threadCount>10</threadCount>
+ </configuration>
+ </plugin>
+ [...]
+---+
This is particularly useful for slow tests that can have high concurrency,
or to quickly and roughly assess the independance
@@ -127,35 +124,33 @@
TestNG provides support for attaching custom listeners, reporters,
annotation transformers and method interceptors to your tests.
By default, TestNG attaches a few basic listeners to generate HTML and XML
reports.
-
+
You can configure multiple custom listeners like this:
+---+
-[...]
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <properties>
- <property>
- <name>usedefaultlisteners</name>
- <value>false</value> <!-- disabling default listeners is optional -->
- </property>
- <property>
- <name>listener</name>
-
<value>com.mycompany.MyResultListener,com.mycompany.MyAnnotationTransformer,com.mycompany.MyMethodInterceptor</value>
- </property>
- <property>
- <name>reporter</name>
- <value>listenReport.Reporter</value>
- </property>
- </properties>
- </configuration>
- </plugin>
-[...]
+ [...]
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <properties>
+ <property>
+ <name>usedefaultlisteners</name>
+ <value>false</value> <!-- disabling default listeners is
optional -->
+ </property>
+ <property>
+ <name>listener</name>
+
<value>com.mycompany.MyResultListener,com.mycompany.MyAnnotationTransformer,com.mycompany.MyMethodInterceptor</value>
+ </property>
+ <property>
+ <name>reporter</name>
+ <value>listenReport.Reporter</value>
+ </property>
+ </properties>
+ </configuration>
+ </plugin>
+ [...]
+---+
For more information on TestNG, see the {{{http://www.testng.org}TestNG web
site}}.
-
-
Modified: maven/surefire/trunk/maven-surefire-plugin/src/site/apt/usage.apt
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/usage.apt?rev=897534&r1=897533&r2=897534&view=diff
==============================================================================
--- maven/surefire/trunk/maven-surefire-plugin/src/site/apt/usage.apt (original)
+++ maven/surefire/trunk/maven-surefire-plugin/src/site/apt/usage.apt Sat Jan
9 20:24:47 2010
@@ -4,7 +4,7 @@
Brett Porter
Allan Ramirez
------
- July 2006
+ 2010-01-09
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -53,7 +53,7 @@
Note that any normal Surefire integration works identically no matter which
providers are in use - so you can still produce a Cobertura report and a
- Surefire results report on your project web site for your TestNG tests,
+ Surefire report on your project web site for your TestNG tests,
for example.
The POJO provider above allows you to write tests that do not depend on
