------
  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
~~ 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


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.

  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.

* Requirements for a provider

  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
  <<<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.

  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

    Prior to 2.11, the provider would do

+---+
    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;

+---+
    TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
    return providerParameters.getRunOrderCalculator().orderTestClasses(  scanned );
+---+

** API changes for 2.12.2:

   Prior to this version, the provider would do

+---+
    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.

+---+
    scanResult = booterParameters.getScanResult();
    final TestsToRun testsToRun = scanResult.applyFilter(testChecker, testClassLoader );
+---+