1 /* 2 * Copyright (C) 2017 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.invoker; 17 18 import com.android.tradefed.build.BuildRetrievalError; 19 import com.android.tradefed.build.IBuildInfo; 20 import com.android.tradefed.config.IConfiguration; 21 import com.android.tradefed.device.DeviceNotAvailableException; 22 import com.android.tradefed.device.ITestDevice; 23 import com.android.tradefed.invoker.TestInvocation.Stage; 24 import com.android.tradefed.invoker.shard.IShardHelper; 25 import com.android.tradefed.log.ITestLogger; 26 import com.android.tradefed.result.ITestInvocationListener; 27 import com.android.tradefed.targetprep.BuildError; 28 import com.android.tradefed.targetprep.TargetSetupError; 29 30 /** 31 * Interface describing the actions that will be done as part of an invocation. The invocation 32 * {@link TestInvocation} itself ensure the order of the calls. 33 */ 34 public interface IInvocationExecution { 35 36 /** 37 * Execute the build_provider step of the invocation. 38 * 39 * @param context the {@link IInvocationContext} of the invocation. 40 * @param config the {@link IConfiguration} of this test run. 41 * @param rescheduler the {@link IRescheduler}, for rescheduling portions of the invocation for 42 * execution on another resource(s) 43 * @param listener the {@link ITestInvocation} to report build download failures. 44 * @return True if we successfully downloaded the build, false otherwise. 45 * @throws BuildRetrievalError 46 * @throws DeviceNotAvailableException 47 */ fetchBuild( IInvocationContext context, IConfiguration config, IRescheduler rescheduler, ITestInvocationListener listener)48 public default boolean fetchBuild( 49 IInvocationContext context, 50 IConfiguration config, 51 IRescheduler rescheduler, 52 ITestInvocationListener listener) 53 throws BuildRetrievalError, DeviceNotAvailableException { 54 return false; 55 } 56 57 /** 58 * Execute the build_provider clean up step. Associated with the build fetching. 59 * 60 * @param context the {@link IInvocationContext} of the invocation. 61 * @param config the {@link IConfiguration} of this test run. 62 */ cleanUpBuilds(IInvocationContext context, IConfiguration config)63 public default void cleanUpBuilds(IInvocationContext context, IConfiguration config) {} 64 65 /** 66 * Execute the target_preparer and multi_target_preparer setUp step. Does all the devices setup 67 * required for the test to run. 68 * 69 * @param context the {@link IInvocationContext} of the invocation. 70 * @param config the {@link IConfiguration} of this test run. 71 * @param listener the {@link ITestInvocation} to report setup failures. 72 * @throws TargetSetupError 73 * @throws BuildError 74 * @throws DeviceNotAvailableException 75 */ doSetup( IInvocationContext context, IConfiguration config, final ITestInvocationListener listener)76 public default void doSetup( 77 IInvocationContext context, 78 IConfiguration config, 79 final ITestInvocationListener listener) 80 throws TargetSetupError, BuildError, DeviceNotAvailableException {} 81 82 /** 83 * Invoke the {@link ITestDevice#preInvocationSetup(IBuildInfo)} for each device part of the 84 * invocation. 85 * 86 * @param context the {@link IInvocationContext} of the invocation. 87 * @param config the {@link IConfiguration} of this test run. 88 * @param logger the {@link ITestLogger} to report logs. 89 * @throws DeviceNotAvailableException 90 * @throws TargetSetupError 91 */ runDevicePreInvocationSetup( IInvocationContext context, IConfiguration config, ITestLogger logger)92 public default void runDevicePreInvocationSetup( 93 IInvocationContext context, IConfiguration config, ITestLogger logger) 94 throws DeviceNotAvailableException, TargetSetupError {} 95 96 /** 97 * Invoke the {@link ITestDevice#postInvocationTearDown()} for each device part of the 98 * invocation. 99 * 100 * @param context the {@link IInvocationContext} of the invocation. 101 * @param config the {@link IConfiguration} of this test run. 102 */ runDevicePostInvocationTearDown( IInvocationContext context, IConfiguration config)103 public default void runDevicePostInvocationTearDown( 104 IInvocationContext context, IConfiguration config) {} 105 106 /** 107 * Execute the target_preparer and multi_target_preparer teardown step. Does the devices tear 108 * down associated with the setup. 109 * 110 * @param context the {@link IInvocationContext} of the invocation. 111 * @param config the {@link IConfiguration} of this test run. 112 * @param logger the {@link ITestLogger} to report logs. 113 * @param exception the original exception thrown by the test running. 114 * @throws Throwable 115 */ doTeardown( IInvocationContext context, IConfiguration config, ITestLogger logger, Throwable exception)116 public default void doTeardown( 117 IInvocationContext context, 118 IConfiguration config, 119 ITestLogger logger, 120 Throwable exception) 121 throws Throwable {} 122 123 /** 124 * Execute the target_preparer and multi_target_preparer cleanUp step. Does the devices clean 125 * up. 126 * 127 * @param context the {@link IInvocationContext} of the invocation. 128 * @param config the {@link IConfiguration} of this test run. 129 * @param exception the original exception thrown by the test running. 130 */ doCleanUp( IInvocationContext context, IConfiguration config, Throwable exception)131 public default void doCleanUp( 132 IInvocationContext context, IConfiguration config, Throwable exception) {} 133 134 /** 135 * Attempt to shard the configuration into sub-configurations, to be re-scheduled to run on 136 * multiple resources in parallel. 137 * 138 * <p>If a shard count is greater than 1, it will simply create configs for each shard by 139 * setting shard indices and reschedule them. If a shard count is not set,it would fallback to 140 * {@link IShardHelper#shardConfig}. 141 * 142 * @param config the current {@link IConfiguration}. 143 * @param context the {@link IInvocationContext} holding the info of the tests. 144 * @param rescheduler the {@link IRescheduler} 145 * @return true if test was sharded. Otherwise return <code>false</code> 146 */ shardConfig( IConfiguration config, IInvocationContext context, IRescheduler rescheduler)147 public default boolean shardConfig( 148 IConfiguration config, IInvocationContext context, IRescheduler rescheduler) { 149 return false; 150 } 151 152 /** 153 * Runs the test. 154 * 155 * @param context the {@link IInvocationContext} to run tests on 156 * @param config the {@link IConfiguration} to run 157 * @param listener the {@link ITestInvocationListener} of test results 158 * @throws Throwable 159 */ runTests( IInvocationContext context, IConfiguration config, ITestInvocationListener listener)160 public default void runTests( 161 IInvocationContext context, IConfiguration config, ITestInvocationListener listener) 162 throws Throwable {} 163 164 /** 165 * Report a failure for the invocation. 166 * 167 * @param exception The exception that should be reported. 168 * @param listener The invocation listener. 169 * @param config The configuration currently running. 170 * @param context The {@link IInvocationContext} of the invocation. 171 * @return True if the configuration should be rescheduled, False otherwise. 172 */ resetBuildAndReschedule( Throwable exception, ITestInvocationListener listener, IConfiguration config, IInvocationContext context)173 public boolean resetBuildAndReschedule( 174 Throwable exception, 175 ITestInvocationListener listener, 176 IConfiguration config, 177 IInvocationContext context); 178 179 /** 180 * Report some device logs at different stage of the invocation. For example: logcat. 181 * 182 * @param device The device to report logs from. 183 * @param listener The logger for the logs. 184 * @param stage The stage of the invocation we are at. 185 */ reportLogs(ITestDevice device, ITestInvocationListener listener, Stage stage)186 public void reportLogs(ITestDevice device, ITestInvocationListener listener, Stage stage); 187 } 188