maven-surefire-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From krosenv...@apache.org
Subject svn commit: r1044143 - in /maven/surefire/trunk: maven-surefire-plugin/src/site/ maven-surefire-plugin/src/site/apt/ maven-surefire-plugin/src/site/apt/examples/ surefire-api/src/main/java/org/apache/maven/surefire/providerapi/ surefire-api/src/main/ja...
Date Thu, 09 Dec 2010 22:07:34 GMT
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;



Mime
View raw message