sdk/ddms/libs/ddmlib/src/com/android/ddmlib/testrunner/IRemoteAndroidTestRunner.java

   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
  17 package com.android.ddmlib.testrunner;
  18
  19 import com.android.ddmlib.IDevice;
  20 import com.android.ddmlib.AdbCommandRejectedException;
  21 import com.android.ddmlib.ShellCommandUnresponsiveException;
  22 import com.android.ddmlib.TimeoutException;
  23
  24 import java.io.IOException;
  25 import java.util.Collection;
  26
  27 /**
  28  * Interface for running a Android test command remotely and reporting result to a listener.
  29  */
  30 public interface IRemoteAndroidTestRunner {
  31
  32     public static enum TestSize {
  33         /** Run tests annotated with SmallTest */
  34         SMALL("small"),
  35         /** Run tests annotated with MediumTest */
  36         MEDIUM("medium"),
  37         /** Run tests annotated with LargeTest */
  38         LARGE("large");
  39
  40         private String mRunnerValue;
  41
  42         /**
  43          * Create a {@link TestSize}.
  44          *
  45          * @param runnerValue the {@link String} value that represents the size that is passed to
  46          * device. Defined on device in android.test.InstrumentationTestRunner.
  47          */
  48         TestSize(String runnerValue) {
  49             mRunnerValue = runnerValue;
  50         }
  51
  52         String getRunnerValue() {
  53             return mRunnerValue;
  54         }
  55
  56         /**
  57          * Return the {@link TestSize} corresponding to the given Android platform defined value.
  58          *
  59          * @throws IllegalArgumentException if {@link TestSize} cannot be found.
  60          */
  61         public static TestSize getTestSize(String value) {
  62             // build the error message in the success case too, to avoid two for loops
  63             StringBuilder msgBuilder = new StringBuilder("Unknown TestSize ");
  64             msgBuilder.append(value);
  65             msgBuilder.append(", Must be one of ");
  66             for (TestSize size : values()) {
  67                 if (size.getRunnerValue().equals(value)) {
  68                     return size;
  69                 }
  70                 msgBuilder.append(size.getRunnerValue());
  71                 msgBuilder.append(", ");
  72             }
  73             throw new IllegalArgumentException(msgBuilder.toString());
  74         }
  75     }
  76
  77     /**
  78      * Returns the application package name.
  79      */
  80     public String getPackageName();
  81
  82     /**
  83      * Returns the runnerName.
  84      */
  85     public String getRunnerName();
  86
  87     /**
  88      * Sets to run only tests in this class
  89      * Must be called before 'run'.
  90      *
  91      * @param className fully qualified class name (eg x.y.z)
  92      */
  93     public void setClassName(String className);
  94
  95     /**
  96      * Sets to run only tests in the provided classes
  97      * Must be called before 'run'.
  98      * <p>
  99      * If providing more than one class, requires a InstrumentationTestRunner that supports
 100      * the multiple class argument syntax.
 101      *
 102      * @param classNames array of fully qualified class names (eg x.y.z)
 103      */
 104     public void setClassNames(String[] classNames);
 105
 106     /**
 107      * Sets to run only specified test method
 108      * Must be called before 'run'.
 109      *
 110      * @param className fully qualified class name (eg x.y.z)
 111      * @param testName method name
 112      */
 113     public void setMethodName(String className, String testName);
 114
 115     /**
 116      * Sets to run all tests in specified package
 117      * Must be called before 'run'.
 118      *
 119      * @param packageName fully qualified package name (eg x.y.z)
 120      */
 121     public void setTestPackageName(String packageName);
 122
 123     /**
 124      * Sets to run only tests of given size.
 125      * Must be called before 'run'.
 126      *
 127      * @param size the {@link TestSize} to run.
 128      */
 129     public void setTestSize(TestSize size);
 130
 131     /**
 132      * Adds a argument to include in instrumentation command.
 133      * <p/>
 134      * Must be called before 'run'. If an argument with given name has already been provided, it's
 135      * value will be overridden.
 136      *
 137      * @param name the name of the instrumentation bundle argument
 138      * @param value the value of the argument
 139      */
 140     public void addInstrumentationArg(String name, String value);
 141
 142     /**
 143      * Removes a previously added argument.
 144      *
 145      * @param name the name of the instrumentation bundle argument to remove
 146      */
 147     public void removeInstrumentationArg(String name);
 148
 149     /**
 150      * Adds a boolean argument to include in instrumentation command.
 151      * <p/>
 152      * @see RemoteAndroidTestRunner#addInstrumentationArg
 153      *
 154      * @param name the name of the instrumentation bundle argument
 155      * @param value the value of the argument
 156      */
 157     public void addBooleanArg(String name, boolean value);
 158
 159     /**
 160      * Sets this test run to log only mode - skips test execution.
 161      */
 162     public void setLogOnly(boolean logOnly);
 163
 164     /**
 165      * Sets this debug mode of this test run. If true, the Android test runner will wait for a
 166      * debugger to attach before proceeding with test execution.
 167      */
 168     public void setDebug(boolean debug);
 169
 170     /**
 171      * Sets this code coverage mode of this test run.
 172      */
 173     public void setCoverage(boolean coverage);
 174
 175     /**
 176      * Sets the maximum time allowed between output of the shell command running the tests on
 177      * the devices.
 178      * <p/>
 179      * This allows setting a timeout in case the tests can become stuck and never finish. This is
 180      * different from the normal timeout on the connection.
 181      * <p/>
 182      * By default no timeout will be specified.
 183      *
 184      * @see {@link IDevice#executeShellCommand(String, com.android.ddmlib.IShellOutputReceiver, int)}
 185      */
 186     public void setMaxtimeToOutputResponse(int maxTimeToOutputResponse);
 187
 188     /**
 189      * Execute this test run.
 190      * <p/>
 191      * Convenience method for {@link #run(Collection)}.
 192      *
 193      * @param listeners listens for test results
 194      * @throws TimeoutException in case of a timeout on the connection.
 195      * @throws AdbCommandRejectedException if adb rejects the command
 196      * @throws ShellCommandUnresponsiveException if the device did not output any test result for
 197      * a period longer than the max time to output.
 198      * @throws IOException if connection to device was lost.
 199      *
 200      * @see #setMaxtimeToOutputResponse(int)
 201      */
 202     public void run(ITestRunListener... listeners)
 203             throws TimeoutException, AdbCommandRejectedException, ShellCommandUnresponsiveException,
 204             IOException;
 205
 206     /**
 207      * Execute this test run.
 208      *
 209      * @param listeners collection of listeners for test results
 210      * @throws TimeoutException in case of a timeout on the connection.
 211      * @throws AdbCommandRejectedException if adb rejects the command
 212      * @throws ShellCommandUnresponsiveException if the device did not output any test result for
 213      * a period longer than the max time to output.
 214      * @throws IOException if connection to device was lost.
 215      *
 216      * @see #setMaxtimeToOutputResponse(int)
 217      */
 218     public void run(Collection<ITestRunListener> listeners)
 219             throws TimeoutException, AdbCommandRejectedException, ShellCommandUnresponsiveException,
 220             IOException;
 221
 222     /**
 223      * Requests cancellation of this test run.
 224      */
 225     public void cancel();
 226
 227 }