Home | History | Annotate | Download | only in result 
      1 /*
      2  * Copyright (C) 2010 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 package com.android.tradefed.result;
     17 
     18 import com.android.ddmlib.testrunner.ITestRunListener;
     19 import com.android.ddmlib.testrunner.TestIdentifier;
     20 import com.android.tradefed.command.ICommandScheduler;
     21 import com.android.tradefed.invoker.IInvocationContext;
     22 import com.android.tradefed.log.ITestLogger;
     23 import com.android.tradefed.testtype.suite.ITestSuite;
     24 
     25 import java.util.Map;
     26 
     27 /**
     28  * Listener for test results from the test invocation.
     29  * <p/>
     30  * A test invocation can itself include multiple test runs, so the sequence of calls will be
     31  * <ul>
     32  * <li>invocationStarted(BuildInfo)</li>
     33  * <li>testRunStarted</li>
     34  * <li>testStarted</li>
     35  * <li>[testFailed]</li>
     36  * <li>testEnded</li>
     37  * <li>...</li>
     38  * <li>testRunEnded</li>
     39  * <li>...</li>
     40  * <li>testRunStarted</li>
     41  * <li>...</li>
     42  * <li>testRunEnded</li>
     43  * <li>[invocationFailed]</li>
     44  * <li>[testLog+]</li>
     45  * <li>invocationEnded</li>
     46  * <li>getSummary</li>
     47  * </ul>
     48  * <p/>
     49  * Note that this is re-using the {@link com.android.ddmlib.testrunner.ITestRunListener}
     50  * because it's a generic interface. The results being reported are not necessarily device specific.
     51  */
     52 public interface ITestInvocationListener extends ITestRunListener, ITestLogger {
     53 
     54     /**
     55      * Reports the start of the test invocation.
     56      *
     57      * <p>Will be automatically called by the TradeFederation framework. Reporters need to override
     58      * this method to support multiple devices reporting.
     59      *
     60      * @param context information about the invocation
     61      */
     62     public default void invocationStarted(IInvocationContext context) {}
     63 
     64     /**
     65      * Reports that the invocation has terminated, whether successfully or due to some error
     66      * condition.
     67      * <p/>
     68      * Will be automatically called by the TradeFederation framework.
     69      *
     70      * @param elapsedTime the elapsed time of the invocation in ms
     71      */
     72     default public void invocationEnded(long elapsedTime) { }
     73 
     74     /**
     75      * Reports an incomplete invocation due to some error condition.
     76      * <p/>
     77      * Will be automatically called by the TradeFederation framework.
     78      *
     79      * @param cause the {@link Throwable} cause of the failure
     80      */
     81     default public void invocationFailed(Throwable cause) { }
     82 
     83     /**
     84      * Allows the InvocationListener to return a summary.
     85      *
     86      * @return A {@link TestSummary} summarizing the run, or null
     87      */
     88     default public TestSummary getSummary() { return null; }
     89 
     90     /**
     91      * Called on {@link ICommandScheduler#shutdown()}, gives the invocation the opportunity to do
     92      * something before terminating.
     93      */
     94     default public void invocationInterrupted() {
     95         // do nothing in default implementation.
     96     }
     97 
     98     /**
     99      * Reports the beginning of a module running. This callback is associated with {@link
    100      * #testModuleEnded()} and is optional in the sequence. It is only used during a run that uses
    101      * modules: {@link ITestSuite} based runners.
    102      *
    103      * @param moduleContext the {@link IInvocationContext} of the module.
    104      */
    105     public default void testModuleStarted(IInvocationContext moduleContext) {}
    106 
    107     /** Reports the end of a module run. */
    108     public default void testModuleEnded() {}
    109 
    110     /**
    111      * {@inheritDoc}
    112      */
    113     @Override
    114     default public void testEnded(TestIdentifier test, Map<String, String> testMetrics) { }
    115 
    116     /** {@inheritDoc} */
    117     @Override
    118     public default void testEnded(
    119             TestIdentifier test, long endTime, Map<String, String> testMetrics) {
    120         testEnded(test, testMetrics);
    121     }
    122 
    123     /** {@inheritDoc} */
    124     @Override
    125     public default void testFailed(TestIdentifier test, String trace) {}
    126 
    127     /**
    128      * {@inheritDoc}
    129      */
    130     @Override
    131     default public void testAssumptionFailure(TestIdentifier test, String trace) { }
    132 
    133     /**
    134      * {@inheritDoc}
    135      */
    136     @Override
    137     default public void testIgnored(TestIdentifier test) { }
    138 
    139     /**
    140      * {@inheritDoc}
    141      */
    142     @Override
    143     default public void testRunEnded(long elapsedTimeMillis, Map<String, String> runMetrics) { }
    144 
    145     /**
    146      * {@inheritDoc}
    147      */
    148     @Override
    149     default public void testRunFailed(String errorMessage) { }
    150 
    151     /**
    152      * {@inheritDoc}
    153      */
    154     @Override
    155     default public void testRunStarted(String runName, int testCount) { }
    156 
    157     /**
    158      * {@inheritDoc}
    159      */
    160     @Override
    161     default public void testRunStopped(long elapsedTime) { }
    162 
    163     /**
    164      * {@inheritDoc}
    165      */
    166     @Override
    167     default public void testStarted(TestIdentifier test) { }
    168 
    169     /** {@inheritDoc} */
    170     @Override
    171     default void testStarted(TestIdentifier test, long startTime) {
    172         testStarted(test);
    173     }
    174 }
    175