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 testInfo the {@link TestInformation} 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( TestInformation testInfo, IConfiguration config, IRescheduler rescheduler, ITestInvocationListener listener)48 public default boolean fetchBuild( 49 TestInformation testInfo, 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 testInfo the {@link TestInformation} of the invocation. 70 * @param config the {@link IConfiguration} of this test run. 71 * @param logger the {@link ITestLogger} to report setup failures logs. 72 * @throws TargetSetupError 73 * @throws BuildError 74 * @throws DeviceNotAvailableException 75 */ doSetup( TestInformation testInfo, IConfiguration config, final ITestLogger logger)76 public default void doSetup( 77 TestInformation testInfo, IConfiguration config, final ITestLogger logger) 78 throws TargetSetupError, BuildError, DeviceNotAvailableException {} 79 80 /** 81 * Invoke the {@link ITestDevice#preInvocationSetup(IBuildInfo)} for each device part of the 82 * invocation. 83 * 84 * @param context the {@link IInvocationContext} of the invocation. 85 * @param config the {@link IConfiguration} of this test run. 86 * @param logger the {@link ITestLogger} to report logs. 87 * @throws DeviceNotAvailableException 88 * @throws TargetSetupError 89 */ runDevicePreInvocationSetup( IInvocationContext context, IConfiguration config, ITestLogger logger)90 public default void runDevicePreInvocationSetup( 91 IInvocationContext context, IConfiguration config, ITestLogger logger) 92 throws DeviceNotAvailableException, TargetSetupError {} 93 94 /** 95 * Invoke the {@link ITestDevice#postInvocationTearDown(Throwable)} for each device part of the 96 * invocation. 97 * 98 * @param context the {@link IInvocationContext} of the invocation. 99 * @param config the {@link IConfiguration} of this test run. 100 * @param exception the original exception thrown by the test running if any. 101 */ runDevicePostInvocationTearDown( IInvocationContext context, IConfiguration config, Throwable exception)102 public default void runDevicePostInvocationTearDown( 103 IInvocationContext context, IConfiguration config, Throwable exception) {} 104 105 /** 106 * Execute the target_preparer and multi_target_preparer teardown step. Does the devices tear 107 * down associated with the setup. 108 * 109 * @param testInfo the {@link TestInformation} of the invocation. 110 * @param config the {@link IConfiguration} of this test run. 111 * @param logger the {@link ITestLogger} to report logs. 112 * @param exception the original exception thrown by the test running. 113 * @throws Throwable 114 */ doTeardown( TestInformation testInfo, IConfiguration config, ITestLogger logger, Throwable exception)115 public default void doTeardown( 116 TestInformation testInfo, 117 IConfiguration config, 118 ITestLogger logger, 119 Throwable exception) 120 throws Throwable {} 121 122 /** 123 * Execute the target_preparer and multi_target_preparer cleanUp step. Does the devices clean 124 * up. 125 * 126 * @param context the {@link IInvocationContext} of the invocation. 127 * @param config the {@link IConfiguration} of this test run. 128 * @param exception the original exception thrown by the test running. 129 */ doCleanUp( IInvocationContext context, IConfiguration config, Throwable exception)130 public default void doCleanUp( 131 IInvocationContext context, IConfiguration config, Throwable exception) {} 132 133 /** 134 * Attempt to shard the configuration into sub-configurations, to be re-scheduled to run on 135 * multiple resources in parallel. 136 * 137 * <p>If a shard count is greater than 1, it will simply create configs for each shard by 138 * setting shard indices and reschedule them. If a shard count is not set,it would fallback to 139 * {@link IShardHelper#shardConfig}. 140 * 141 * @param config the current {@link IConfiguration}. 142 * @param testInfo the {@link TestInformation} holding the info of the tests. 143 * @param rescheduler the {@link IRescheduler}. 144 * @param logger {@link ITestLogger} used to log file during sharding. 145 * @return true if test was sharded. Otherwise return <code>false</code> 146 */ shardConfig( IConfiguration config, TestInformation testInfo, IRescheduler rescheduler, ITestLogger logger)147 public default boolean shardConfig( 148 IConfiguration config, 149 TestInformation testInfo, 150 IRescheduler rescheduler, 151 ITestLogger logger) { 152 return false; 153 } 154 155 /** 156 * Runs the test. 157 * 158 * @param info the {@link TestInformation} to run tests with. 159 * @param config the {@link IConfiguration} to run 160 * @param listener the {@link ITestInvocationListener} of test results 161 * @throws Throwable 162 */ runTests( TestInformation info, IConfiguration config, ITestInvocationListener listener)163 public default void runTests( 164 TestInformation info, IConfiguration config, ITestInvocationListener listener) 165 throws Throwable {} 166 167 /** 168 * Report some device logs at different stage of the invocation. For example: logcat. 169 * 170 * @param device The device to report logs from. 171 * @param logger The logger for the logs. 172 * @param stage The stage of the invocation we are at. 173 */ reportLogs(ITestDevice device, ITestLogger logger, Stage stage)174 public void reportLogs(ITestDevice device, ITestLogger logger, Stage stage); 175 } 176