Home | History | Annotate | Download | only in result 
      1 /*
      2  * Copyright (C) 2018 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.tradefed.metrics.proto.MetricMeasurement.Metric;
     19 import com.android.tradefed.util.proto.TfMetricProtoUtil;
     20 
     21 import java.util.HashMap;
     22 import java.util.Map;
     23 
     24 /**
     25  * Receives event notifications during instrumentation test runs.
     26  *
     27  * <p>Patterned after org.junit.runner.notification.RunListener
     28  *
     29  * <p>The sequence of calls will be:
     30  *
     31  * <ul>
     32  *   <li> testRunStarted
     33  *   <li> testStarted
     34  *   <li> [testFailed]
     35  *   <li> [testAssumptionFailure]
     36  *   <li> [testIgnored]
     37  *   <li> testEnded
     38  *   <li> ....
     39  *   <li> [testRunFailed]
     40  *   <li> testRunEnded
     41  * </ul>
     42  */
     43 public interface ITestLifeCycleReceiver {
     44 
     45     /**
     46      * Reports the start of a test run.
     47      *
     48      * @param runName the test run name
     49      * @param testCount total number of tests in test run
     50      */
     51     public default void testRunStarted(String runName, int testCount) {}
     52 
     53     /**
     54      * Reports test run failed to complete due to a fatal error.
     55      *
     56      * @param errorMessage {@link String} describing reason for run failure.
     57      */
     58     public default void testRunFailed(String errorMessage) {}
     59 
     60     /**
     61      * Reports end of test run.
     62      *
     63      * @param elapsedTimeMillis device reported elapsed time, in milliseconds
     64      * @param runMetrics key-value pairs reported at the end of a test run
     65      */
     66     public default void testRunEnded(long elapsedTimeMillis, Map<String, String> runMetrics) {
     67         testRunEnded(elapsedTimeMillis, TfMetricProtoUtil.upgradeConvert(runMetrics));
     68     }
     69 
     70     /**
     71      * Reports end of test run. FIXME: We cannot have two Map<> interfaces with different type, so
     72      * we have to use HashMap here.
     73      *
     74      * @param elapsedTimeMillis device reported elapsed time, in milliseconds
     75      * @param runMetrics key-value pairs reported at the end of a test run with {@link Metric}.
     76      */
     77     public default void testRunEnded(long elapsedTimeMillis, HashMap<String, Metric> runMetrics) {}
     78 
     79     /**
     80      * Reports test run stopped before completion due to a user request.
     81      *
     82      * <p>TODO: currently unused, consider removing
     83      *
     84      * @param elapsedTime device reported elapsed time, in milliseconds
     85      */
     86     public default void testRunStopped(long elapsedTime) {}
     87 
     88     /**
     89      * Reports the start of an individual test case. Older interface, should use {@link
     90      * #testStarted(TestDescription)} whenever possible.
     91      *
     92      * @param test identifies the test
     93      */
     94     public default void testStarted(TestDescription test) {}
     95 
     96     /**
     97      * Alternative to {@link #testStarted(TestDescription)} where we also specify when the test was
     98      * started, combined with {@link #testEnded(TestDescription, long, Map)} for accurate measure.
     99      *
    100      * @param test identifies the test
    101      * @param startTime the time the test started, measured via {@link System#currentTimeMillis()}
    102      */
    103     default void testStarted(TestDescription test, long startTime) {
    104         testStarted(test);
    105     }
    106 
    107     /**
    108      * Reports the failure of a individual test case.
    109      *
    110      * <p>Will be called between testStarted and testEnded.
    111      *
    112      * @param test identifies the test
    113      * @param trace stack trace of failure
    114      */
    115     public default void testFailed(TestDescription test, String trace) {}
    116 
    117     /**
    118      * Called when an atomic test flags that it assumes a condition that is false
    119      *
    120      * @param test identifies the test
    121      * @param trace stack trace of failure
    122      */
    123     public default void testAssumptionFailure(TestDescription test, String trace) {}
    124 
    125     /**
    126      * Called when a test will not be run, generally because a test method is annotated with
    127      * org.junit.Ignore.
    128      *
    129      * @param test identifies the test
    130      */
    131     public default void testIgnored(TestDescription test) {}
    132 
    133     /**
    134      * Reports the execution end of an individual test case.
    135      *
    136      * <p>If {@link #testFailed} was not invoked, this test passed. Also returns any key/value
    137      * metrics which may have been emitted during the test case's execution.
    138      *
    139      * @param test identifies the test
    140      * @param testMetrics a {@link Map} of the metrics emitted
    141      */
    142     public default void testEnded(TestDescription test, Map<String, String> testMetrics) {
    143         testEnded(test, TfMetricProtoUtil.upgradeConvert(testMetrics));
    144     }
    145 
    146     /**
    147      * Reports the execution end of an individual test case.
    148      *
    149      * <p>If {@link #testFailed} was not invoked, this test passed. Also returns any key/value
    150      * metrics which may have been emitted during the test case's execution.
    151      *
    152      * @param test identifies the test
    153      * @param testMetrics a {@link Map} of the metrics emitted
    154      */
    155     public default void testEnded(TestDescription test, HashMap<String, Metric> testMetrics) {}
    156 
    157     /**
    158      * Alternative to {@link #testEnded(TestDescription, Map)} where we can specify the end time
    159      * directly. Combine with {@link #testStarted(TestDescription, long)} for accurate measure.
    160      *
    161      * @param test identifies the test
    162      * @param endTime the time the test ended, measured via {@link System#currentTimeMillis()}
    163      * @param testMetrics a {@link Map} of the metrics emitted
    164      */
    165     public default void testEnded(
    166             TestDescription test, long endTime, Map<String, String> testMetrics) {
    167         testEnded(test, endTime, TfMetricProtoUtil.upgradeConvert(testMetrics));
    168     }
    169 
    170     /**
    171      * Alternative to {@link #testEnded(TestDescription, Map)} where we can specify the end time
    172      * directly. Combine with {@link #testStarted(TestDescription, long)} for accurate measure.
    173      *
    174      * @param test identifies the test
    175      * @param endTime the time the test ended, measured via {@link System#currentTimeMillis()}
    176      * @param testMetrics a {@link Map} of the metrics emitted
    177      */
    178     public default void testEnded(
    179             TestDescription test, long endTime, HashMap<String, Metric> testMetrics) {
    180         testEnded(test, testMetrics);
    181     }
    182 }
    183