Author: brett
Date: Mon May 1 11:07:17 2006
New Revision: 398656
URL: http://svn.apache.org/viewcvs?rev=398656&view=rev
Log:
add docs
Modified:
maven/plugins/trunk/maven-surefire-plugin/src/site/apt/howto.apt
maven/plugins/trunk/maven-surefire-plugin/src/site/site.xml
Modified: maven/plugins/trunk/maven-surefire-plugin/src/site/apt/howto.apt
URL:
http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-surefire-plugin/src/site/apt/howto.apt?rev=398656&r1=398655&r2=398656&view=diff
==============================================================================
--- maven/plugins/trunk/maven-surefire-plugin/src/site/apt/howto.apt (original)
+++ maven/plugins/trunk/maven-surefire-plugin/src/site/apt/howto.apt Mon May 1
11:07:17 2006
@@ -3,14 +3,44 @@
------
Johnny R. Ruiz III <[EMAIL PROTECTED]>
Allan Ramirez <[EMAIL PROTECTED]>
+ Brett Porter <[EMAIL PROTECTED]>
------
September 20, 2005
How to Use
+* Using different testing providers
+
+ Tests in your tes source directory can be any combination of the following:
+
+ * Test NG
+
+ * JUnit
+
+ * POJO
+
+ Which providers are available is controlled simply by the inclusion of the
appropriate
+ dependencies (ie, junit:junit for JUnit, org.testng:testng 4.7+ for Test
NG). Since this is
+ required to compile the test classes anyway, no additional configuration is
required.
+
+ 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 Test NG tests, for example.
+
+ The POJO provider above allows you to write tests that do not depend on
JUnit. They behave in
+ the same way, running all <<<test*>>> methods that are public in the class,
but the API
+ dependency is not required. To perform assertions, the JDK 1.4 <<<assert>>>
keyword can be
+ used, or you can use <<<org.apache.maven.surefire.assertion.Assert>>>.
+
+ All of the providers support the following configuration. However, there are
additional
+ options available if you are running TestNG tests (including if you are
using TestNG to
+ execute your JUnit tests, which occurs by default if both are present in
Surefire).
+
+ See {{{testng.html} Test NG Configuration}} for more information.
+
* Skipping Tests
- These example shows how to skip test when using m2:
+ To skip running the tests for a particular project, you configure the skip
parameter:
-----
<project>
@@ -38,7 +68,7 @@
* Using System Properties
- To add a System property, you can try this one.
+ To add a System property, use the following configuration:
-----
<project>
@@ -89,8 +119,14 @@
</project>
-----
- You may need to fork due to an issue with java.lang.LinkageError: loader
constraints violated when linking
- system classes - e.g. javax.*. If this happens you need to fork and you need
to disable childDelegation.
+ <<Note:>> You do not need to manually enable assertions if you are using them
in your unit tests - Surefire enables
+ them on your test classes automatically under JDK 1.4+.
+
+* Class Loading Issues
+
+ By default, Surefire loads classes "child first", like a web application -
meaning your dependencies take precedence over those
+ in the JDK. With endorsed APIs like XML parsers, this may cause problems. You
can either make sure you provide a full, compatible
+ implementation, or revert to "parent first" class loading by setting the
<<<childDelegation>>> flag to <<<false>>>:
----
<project>
@@ -102,8 +138,6 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
- <forkMode>once</forkMode>
- <testFailureIgnore>true</testFailureIgnore>
<childDelegation>false</childDelegation>
</configuration>
@@ -116,49 +150,17 @@
* Tests Inclusion and Exclusion
- The following are the sample test classes.
-
- TestCircle.java.\
- TestRectangle.java.\
- TestSquare.java.\
- TestTriangle.java.\
- PentagonTest.java.\
- HeptagonTest.java.\
- OctagonTest.java.\
- Sample.java.
-
** Inclusions
- By default, the surefire plugin will automatically include all test classes
with the following wildcard patterns
+ 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 filename
that starts with "Test".\
- <"**/*Test.java"> - includes all of its subdirectory and all java filename
that ends with "Test".\
- <"**/*TestCase.java"> - includes all of its subdirectory and all java
filename that ends with "TestCase".
+ * <"**/Test*.java"> - includes all of its subdirectory and all java
filename that starts with "Test".
- If your test classes does not go with the naming convention, then configure
surefire plugin and include your test.
+ * <"**/*Test.java"> - includes all of its subdirectory and all java
filename that ends with "Test".
-+---+
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <configuration>
- <includes>
- <include>Sample.java</include>
- </includes>
- </configuration>
- </plugin>
- </plugins>
- </build>
- ...
-</project>
-+---+
+ * <"**/*TestCase.java"> - includes all of its subdirectory and all java
filename that ends with "TestCase".
- Another scenario to use inclusion is when you most of your test classes
should be excluded and only few of them are
- need to be included.
+ If your test classes does not go with the naming convention, then configure
surefire plugin and include your test.
+---+
<project>
@@ -169,12 +171,8 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
- <excludes>
- <exclude>**/*.java</exclude>
- </excludes>
<includes>
- <include>PentagonTest.java</include>
- <include>OctagonTest.java</include>
+ <include>Sample.java</include>
</includes>
</configuration>
</plugin>
@@ -184,14 +182,11 @@
</project>
+---+
-
** Exclusions
There are certain times that some tests are causing the build to fail. If
the bad test classes are only few
we may exclude them to continue the build. Exclusions can be done by the
following:
- * Excluding per java file.
-
+---+
<project>
...
@@ -202,8 +197,8 @@
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<excludes>
- <exclude>TestCircle.java</exclude>
- <exclude>TestSquare.java</exclude>
+ <exclude>**/TestCircle.java</exclude>
+ <exclude>**/TestSquare.java</exclude>
</excludes>
</configuration>
</plugin>
@@ -212,33 +207,16 @@
...
</project>
+---+
-
- The above example will exclude TestCircle.java and TestSquare.java from the
unit testing of surefire plugin.
-
- * Excluding test using wildcards.
-+---+
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <configuration>
- <excludes>
- <exclude>**/Test*.java</exclude>
- </excludes>
- </configuration>
- </plugin>
- </plugins>
- </build>
- ...
-</project>
-+---+
+* Running a single test
- The above example will exclude all its subfolders and java files that starts
with "Test".
+ During development, you may run a single test class repeatedly. To run this
through Maven, you must use the <<<test>>> parameter.
+ For example:
- There are other parameters that you can configure like testFailureIgnore,
reportsDirectory, test , etc.
++---+
+mvn -Dtest=TestCircle test
++---+
+
+ There are other parameters that you can configure like testFailureIgnore,
reportsDirectory, and so on.
For full documentation, click {{{index.html}here}}.
Modified: maven/plugins/trunk/maven-surefire-plugin/src/site/site.xml
URL:
http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-surefire-plugin/src/site/site.xml?rev=398656&r1=398655&r2=398656&view=diff
==============================================================================
--- maven/plugins/trunk/maven-surefire-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-surefire-plugin/src/site/site.xml Mon May 1
11:07:17 2006
@@ -35,6 +35,7 @@
<menu name="Overview">
<item name="Introduction" href="introduction.html"/>
<item name="How to Use" href="howto.html"/>
+ <item name="Using Test NG" href="testng.html"/>
</menu>
${reports}
</body>
