Author: krosenvold
Date: Thu Dec 9 22:07:33 2010
New Revision: 1044143
URL: http://svn.apache.org/viewvc?rev=1044143&view=rev
Log:
[SUREFIRE-292] Documentation for surefire API and providers
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/api.apt
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/providers.apt.vm
maven/surefire/trunk/maven-surefire-plugin/src/site/site.xml
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/providerapi/ProviderParameters.java
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/report/ReporterConfiguration.java
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/DirectoryScannerParameters.java
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/TestRequest.java
Modified: maven/surefire/trunk/maven-surefire-plugin/src/site/apt/api.apt
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/api.apt?rev=1044143&r1=1044142&r2=1044143&view=diff
==============================================================================
--- maven/surefire/trunk/maven-surefire-plugin/src/site/apt/api.apt (original)
+++ maven/surefire/trunk/maven-surefire-plugin/src/site/apt/api.apt Thu Dec 9
22:07:33 2010
@@ -34,18 +34,26 @@ Maven Surefire Provider API
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.
+ 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
- A provider contains a META-INF/services file entry named
org.apache.maven.surefire.providerapi.SurefireProvider
+ There are three things any provider must fulfill:
+
+ * 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.
- The actual provider class contains a one-arg constructor that accepts an
instance of
+ * 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.
\ No newline at end of file
+ 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.
Modified:
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/providers.apt.vm
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/providers.apt.vm?rev=1044143&r1=1044142&r2=1044143&view=diff
==============================================================================
---
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/providers.apt.vm
(original)
+++
maven/surefire/trunk/maven-surefire-plugin/src/site/apt/examples/providers.apt.vm
Thu Dec 9 22:07:33 2010
@@ -10,12 +10,13 @@ Configuring providers
* Selecting a provider
-Surefire normally automatically selects which test-framework provider to use
based on the version of
-TestNG/JUnit present in your project's classpath. In some cases it may be
desirable to manually
-override such a selection. This can be done by adding the required provider as
a dependency to
-the surefire-plugin.
+ Surefire normally automatically selects which test-framework provider to use
based on the version of
+ TestNG/JUnit present in your project's classpath. In some cases it may be
desirable to manually
+ override such a selection. This can be done by adding the required provider
as a dependency to
+ the surefire-plugin.
+
+ The following example shows how to force the junit 4.7 provider:
-The following example shows how to force the junit 4.7 provider:
+---+
[...]
<plugin>
@@ -33,6 +34,6 @@ The following example shows how to force
[...]
+---+
-The providers supplied with surefire are surefire-junit3, surefire-junit4,
surefire-junit47 and surefire-testng.
-Please note that forcing a provider still requires that the test framework is
properly set up on your project classpath.
+ The providers supplied with surefire are surefire-junit3, surefire-junit4,
surefire-junit47 and surefire-testng.
+ Please note that forcing a provider still requires that the test framework
is properly set up on your project classpath.
Modified: maven/surefire/trunk/maven-surefire-plugin/src/site/site.xml
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/maven-surefire-plugin/src/site/site.xml?rev=1044143&r1=1044142&r2=1044143&view=diff
==============================================================================
--- maven/surefire/trunk/maven-surefire-plugin/src/site/site.xml (original)
+++ maven/surefire/trunk/maven-surefire-plugin/src/site/site.xml Thu Dec 9
22:07:33 2010
@@ -27,6 +27,7 @@
<item name="Introduction" href="index.html"/>
<item name="Goals" href="plugin-info.html"/>
<item name="Usage" href="usage.html"/>
+ <item name="API" href="api.html"/>
<item name="FAQ" href="faq.html"/>
</menu>
<menu name="Examples">
Modified:
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/providerapi/ProviderParameters.java
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/providerapi/ProviderParameters.java?rev=1044143&r1=1044142&r2=1044143&view=diff
==============================================================================
---
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/providerapi/ProviderParameters.java
(original)
+++
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/providerapi/ProviderParameters.java
Thu Dec 9 22:07:33 2010
@@ -18,13 +18,14 @@ public interface ProviderParameters
{
/**
* Provides a directory scanner that enforces the includes/excludes
parameters that were passed to surefire.
+ * See #getDirectoryScannerParameters for details
* @return The directory scanner
*/
DirectoryScanner getDirectoryScanner();
/**
* Provides features for creating reporting objects
- * @return A reportermanager factory that allows the creation of one or
more ReporterManagers
+ * @return A ReporterManagerFactory that allows the creation of one or
more ReporterManagers
*/
ReporterManagerFactory getReporterManagerFactory();
Modified:
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/report/ReporterConfiguration.java
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/report/ReporterConfiguration.java?rev=1044143&r1=1044142&r2=1044143&view=diff
==============================================================================
---
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/report/ReporterConfiguration.java
(original)
+++
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/report/ReporterConfiguration.java
Thu Dec 9 22:07:33 2010
@@ -43,16 +43,29 @@ public class ReporterConfiguration
this.trimStackTrace = trimStackTrace;
}
+ /**
+ * The directory where reports will be created, normally
${project.build.directory}/surefire-reports
+ * @return A file pointing at the specified directory
+ */
public File getReportsDirectory()
{
return reportsDirectory;
}
+ /**
+ * Indicates if reporting should trim the stack traces.
+ * @return true if stacktraces should be trimmed in reporting
+ */
public Boolean isTrimStackTrace()
{
return trimStackTrace;
}
+ /**
+ * A list of classnames representing runnable reports for this test-run.
+ * @return A list of strings, each string is a classname of a class
+ * implementing the org.apache.maven.surefire.report.Reporter interface
+ */
public List getReports()
{
return reports;
Modified:
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/DirectoryScannerParameters.java
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/DirectoryScannerParameters.java?rev=1044143&r1=1044142&r2=1044143&view=diff
==============================================================================
---
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/DirectoryScannerParameters.java
(original)
+++
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/DirectoryScannerParameters.java
Thu Dec 9 22:07:33 2010
@@ -44,21 +44,37 @@ public class DirectoryScannerParameters
this.failIfNoTests = failIfNoTests;
}
+ /**
+ * Returns the directory of the compiled classes, normally
${project.build.testOutputDirectory}
+ * @return A directory that can be scanned for .class files
+ */
public File getTestClassesDirectory()
{
return testClassesDirectory;
}
+ /**
+ * The includes pattern list, as specified on the plugin includes
parameter.
+ * @return A list of patterns. May contain both source file designators
and .class extensions.
+ */
public List getIncludes()
{
return includes;
}
+ /**
+ * The excludes pattern list, as specified on the plugin includes
parameter.
+ * @return A list of patterns. May contain both source file designators
and .class extensions.
+ */
public List getExcludes()
{
return excludes;
}
+ /**
+ * Indicates if lack of runable tests should fail the entire build
+ * @return true if no tests should fail the build
+ */
public Boolean isFailIfNoTests()
{
return failIfNoTests;
Modified:
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/TestRequest.java
URL:
http://svn.apache.org/viewvc/maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/TestRequest.java?rev=1044143&r1=1044142&r2=1044143&view=diff
==============================================================================
---
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/TestRequest.java
(original)
+++
maven/surefire/trunk/surefire-api/src/main/java/org/apache/maven/surefire/testset/TestRequest.java
Thu Dec 9 22:07:33 2010
@@ -43,16 +43,28 @@ public class TestRequest
this.requestedTest = requestedTest;
}
+ /**
+ * Represents suitexmlfiles that define the test-run request
+ * @return A list of java.io.File objects.
+ */
public List getSuiteXmlFiles()
{
return suiteXmlFiles;
}
+ /**
+ * Test source directory, normally ${project.build.testSourceDirectory}
+ * @return A file pointing to test sources
+ */
public File getTestSourceDirectory()
{
return testSourceDirectory;
}
+ /**
+ * A specific test request issued with -Dtest= from the command line.
+ * @return The string specified at the command line
+ */
public String getRequestedTest()
{
return requestedTest;
