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