View Javadoc
1   package org.apache.maven.surefire.providerapi;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.lang.reflect.InvocationTargetException;
23  import java.util.Iterator;
24  import org.apache.maven.surefire.report.ReporterException;
25  import org.apache.maven.surefire.suite.RunResult;
26  import org.apache.maven.surefire.testset.TestSetFailedException;
27  
28  /**
29   * Interface to be implemented by all Surefire providers.
30   * <p/>
31   * NOTE: This class is part of the proposed public api for surefire providers for 2.7. It may
32   * still be subject to changes, even for minor revisions.
33   * <p/>
34   * The api covers this interface and all the types reachable from it. And nothing else.
35   * <p/>
36   * <p/>
37   * Called in one of three ways:
38   * Forkmode = never: getSuites is not called, invoke is called with null parameter
39   * Forkmode = once: getSuites is not called, invoke is called with null parameter
40   * Forkmode anything else: getSuites is called, invoke is called on new provider instance for each item in getSuites
41   * response.
42   *
43   * @author Kristian Rosenvold
44   */
45  public interface SurefireProvider
46  {
47      /**
48       * Determines the number of forks.
49       * <p/>
50       * Called when forkmode is different from "never" or "always", allows the provider to define
51       * how to behave for the fork.
52       *
53       * @return An iterator that will trigger one fork per item
54       */
55      Iterator getSuites();
56  
57      /**
58       * Runs a forked test
59       *
60       * @param forkTestSet An item from the iterator in #getSuites. Will be null for forkmode never or always.
61       *                    When this is non-null, the forked process will run only that test
62       *                    and probably not scan the classpath
63       * @return A result of the invocation
64       * @throws org.apache.maven.surefire.report.ReporterException
65       *          When reporting fails
66       * @throws org.apache.maven.surefire.testset.TestSetFailedException
67       *          When testset fails
68       */
69      @SuppressWarnings( "checkstyle:redundantthrows" )
70      RunResult invoke( Object forkTestSet )
71          throws TestSetFailedException, ReporterException, InvocationTargetException;
72  
73      /**
74       * Makes an attempt at cancelling the current run, giving the provider a chance to notify
75       * reporting that the remaining tests have been cancelled due to timeout.
76       * <p/>
77       * If the provider thinks it can terminate properly it is the responsibility of
78       * the invoke method to return a RunResult with a booter code of failure.
79       * <p/>
80       * It is up to the provider to find out how to implement this method properly.
81       * A provider may also choose to not do anything at all in this method,
82       * which means surefire will kill the forked process soon afterwards anyway.
83       * <p/>
84       * Will be called on a different thread than the one calling invoke.
85       */
86      // Todo: Need to think a lot closer about how/if this works and if there is a use case for it.
87      // Killing a process is slightly non-deterministic
88      // And it
89      void cancel();
90  }