frameworks/base/core/java/android/test/InstrumentationTestCase.java

   1 /*
   2  * Copyright (C) 2007 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 android.test;
  18
  19 import android.app.Activity;
  20 import android.app.Instrumentation;
  21 import android.content.Intent;
  22 import android.os.Bundle;
  23 import android.util.Log;
  24 import android.view.KeyEvent;
  25
  26 import java.lang.reflect.Field;
  27 import java.lang.reflect.InvocationTargetException;
  28 import java.lang.reflect.Method;
  29 import java.lang.reflect.Modifier;
  30
  31 import junit.framework.TestCase;
  32
  33 /**
  34  * A test case that has access to {@link Instrumentation}.
  35  */
  36 public class InstrumentationTestCase extends TestCase {
  37
  38     private Instrumentation mInstrumentation;
  39
  40     /**
  41      * Injects instrumentation into this test case. This method is
  42      * called by the test runner during test setup.
  43      *
  44      * @param instrumentation the instrumentation to use with this instance
  45      */
  46     public void injectInstrumentation(Instrumentation instrumentation) {
  47         mInstrumentation = instrumentation;
  48     }
  49
  50     /**
  51      * Injects instrumentation into this test case. This method is
  52      * called by the test runner during test setup.
  53      *
  54      * @param instrumentation the instrumentation to use with this instance
  55      *
  56      * @deprecated Incorrect spelling,
  57      * use {@link #injectInstrumentation(android.app.Instrumentation) instead.
  58      */
  59     @Deprecated
  60     public void injectInsrumentation(Instrumentation instrumentation) {
  61         injectInstrumentation(instrumentation);
  62     }
  63
  64     /**
  65      * Inheritors can access the instrumentation using this.
  66      * @return instrumentation
  67      */
  68     public Instrumentation getInstrumentation() {
  69         return mInstrumentation;
  70     }
  71
  72     /**
  73      * Utility method for launching an activity.
  74      *
  75      * <p>The {@link Intent} used to launch the Activity is:
  76      *  action = {@link Intent#ACTION_MAIN}
  77      *  extras = null, unless a custom bundle is provided here
  78      * All other fields are null or empty.
  79      *
  80      * <p><b>NOTE:</b> The parameter <i>pkg</i> must refer to the package identifier of the
  81      * package hosting the activity to be launched, which is specified in the AndroidManifest.xml
  82      * file.  This is not necessarily the same as the java package name.
  83      *
  84      * @param pkg The package hosting the activity to be launched.
  85      * @param activityCls The activity class to launch.
  86      * @param extras Optional extra stuff to pass to the activity.
  87      * @return The activity, or null if non launched.
  88      */
  89     public final <T extends Activity> T launchActivity(
  90             String pkg,
  91             Class<T> activityCls,
  92             Bundle extras) {
  93         Intent intent = new Intent(Intent.ACTION_MAIN);
  94         if (extras != null) {
  95             intent.putExtras(extras);
  96         }
  97         return launchActivityWithIntent(pkg, activityCls, intent);
  98     }
  99
 100     /**
 101      * Utility method for launching an activity with a specific Intent.
 102      *
 103      * <p><b>NOTE:</b> The parameter <i>pkg</i> must refer to the package identifier of the
 104      * package hosting the activity to be launched, which is specified in the AndroidManifest.xml
 105      * file.  This is not necessarily the same as the java package name.
 106      *
 107      * @param pkg The package hosting the activity to be launched.
 108      * @param activityCls The activity class to launch.
 109      * @param intent The intent to launch with
 110      * @return The activity, or null if non launched.
 111      */
 112     @SuppressWarnings("unchecked")
 113     public final <T extends Activity> T launchActivityWithIntent(
 114             String pkg,
 115             Class<T> activityCls,
 116             Intent intent) {
 117         intent.setClassName(pkg, activityCls.getName());
 118         intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
 119         T activity = (T) getInstrumentation().startActivitySync(intent);
 120         getInstrumentation().waitForIdleSync();
 121         return activity;
 122     }
 123
 124     /**
 125      * Helper for running portions of a test on the UI thread.
 126      *
 127      * Note, in most cases it is simpler to annotate the test method with
 128      * {@link android.test.UiThreadTest}, which will run the entire test method on the UI thread.
 129      * Use this method if you need to switch in and out of the UI thread to perform your test.
 130      *
 131      * @param r runnable containing test code in the {@link Runnable#run()} method
 132      */
 133     public void runTestOnUiThread(final Runnable r) throws Throwable {
 134         final Throwable[] exceptions = new Throwable[1];
 135         getInstrumentation().runOnMainSync(new Runnable() {
 136             public void run() {
 137                 try {
 138                     r.run();
 139                 } catch (Throwable throwable) {
 140                     exceptions[0] = throwable;
 141                 }
 142             }
 143         });
 144         if (exceptions[0] != null) {
 145             throw exceptions[0];
 146         }
 147     }
 148
 149     /**
 150      * Runs the current unit test. If the unit test is annotated with
 151      * {@link android.test.UiThreadTest}, the test is run on the UI thread.
 152      */
 153     @Override
 154     protected void runTest() throws Throwable {
 155         String fName = getName();
 156         assertNotNull(fName);
 157         Method method = null;
 158         try {
 159             // use getMethod to get all public inherited
 160             // methods. getDeclaredMethods returns all
 161             // methods of this class but excludes the
 162             // inherited ones.
 163             method = getClass().getMethod(fName, (Class[]) null);
 164         } catch (NoSuchMethodException e) {
 165             fail("Method \""+fName+"\" not found");
 166         }
 167
 168         if (!Modifier.isPublic(method.getModifiers())) {
 169             fail("Method \""+fName+"\" should be public");
 170         }
 171
 172         int runCount = 1;
 173         if (method.isAnnotationPresent(FlakyTest.class)) {
 174             runCount = method.getAnnotation(FlakyTest.class).tolerance();
 175         }
 176
 177         if (method.isAnnotationPresent(UiThreadTest.class)) {
 178             final int tolerance = runCount;
 179             final Method testMethod = method;
 180             final Throwable[] exceptions = new Throwable[1];
 181             getInstrumentation().runOnMainSync(new Runnable() {
 182                 public void run() {
 183                     try {
 184                         runMethod(testMethod, tolerance);
 185                     } catch (Throwable throwable) {
 186                         exceptions[0] = throwable;
 187                     }
 188                 }
 189             });
 190             if (exceptions[0] != null) {
 191                 throw exceptions[0];
 192             }
 193         } else {
 194             runMethod(method, runCount);
 195         }
 196     }
 197
 198     private void runMethod(Method runMethod, int tolerance) throws Throwable {
 199         Throwable exception = null;
 200
 201         int runCount = 0;
 202         do {
 203             try {
 204                 runMethod.invoke(this, (Object[]) null);
 205                 exception = null;
 206             } catch (InvocationTargetException e) {
 207                 e.fillInStackTrace();
 208                 exception = e.getTargetException();
 209             } catch (IllegalAccessException e) {
 210                 e.fillInStackTrace();
 211                 exception = e;
 212             } finally {
 213                 runCount++;
 214             }
 215         } while ((runCount < tolerance) && (exception != null));
 216
 217         if (exception != null) {
 218             throw exception;
 219         }
 220     }
 221
 222     /**
 223      * Sends a series of key events through instrumentation and waits for idle. The sequence
 224      * of keys is a string containing the key names as specified in KeyEvent, without the
 225      * KEYCODE_ prefix. For instance: sendKeys("DPAD_LEFT A B C DPAD_CENTER"). Each key can
 226      * be repeated by using the N* prefix. For instance, to send two KEYCODE_DPAD_LEFT, use
 227      * the following: sendKeys("2*DPAD_LEFT").
 228      *
 229      * @param keysSequence The sequence of keys.
 230      */
 231     public void sendKeys(String keysSequence) {
 232         final String[] keys = keysSequence.split(" ");
 233         final int count = keys.length;
 234
 235         final Instrumentation instrumentation = getInstrumentation();
 236
 237         for (int i = 0; i < count; i++) {
 238             String key = keys[i];
 239             int repeater = key.indexOf('*');
 240
 241             int keyCount;
 242             try {
 243                 keyCount = repeater == -1 ? 1 : Integer.parseInt(key.substring(0, repeater));
 244             } catch (NumberFormatException e) {
 245                 Log.w("ActivityTestCase", "Invalid repeat count: " + key);
 246                 continue;
 247             }
 248
 249             if (repeater != -1) {
 250                 key = key.substring(repeater + 1);
 251             }
 252
 253             for (int j = 0; j < keyCount; j++) {
 254                 try {
 255                     final Field keyCodeField = KeyEvent.class.getField("KEYCODE_" + key);
 256                     final int keyCode = keyCodeField.getInt(null);
 257                     try {
 258                         instrumentation.sendKeyDownUpSync(keyCode);
 259                     } catch (SecurityException e) {
 260                         // Ignore security exceptions that are now thrown
 261                         // when trying to send to another app, to retain
 262                         // compatibility with existing tests.
 263                     }
 264                 } catch (NoSuchFieldException e) {
 265                     Log.w("ActivityTestCase", "Unknown keycode: KEYCODE_" + key);
 266                     break;
 267                 } catch (IllegalAccessException e) {
 268                     Log.w("ActivityTestCase", "Unknown keycode: KEYCODE_" + key);
 269                     break;
 270                 }
 271             }
 272         }
 273
 274         instrumentation.waitForIdleSync();
 275     }
 276
 277     /**
 278      * Sends a series of key events through instrumentation and waits for idle. For instance:
 279      * sendKeys(KEYCODE_DPAD_LEFT, KEYCODE_DPAD_CENTER).
 280      *
 281      * @param keys The series of key codes to send through instrumentation.
 282      */
 283     public void sendKeys(int... keys) {
 284         final int count = keys.length;
 285         final Instrumentation instrumentation = getInstrumentation();
 286
 287         for (int i = 0; i < count; i++) {
 288             try {
 289                 instrumentation.sendKeyDownUpSync(keys[i]);
 290             } catch (SecurityException e) {
 291                 // Ignore security exceptions that are now thrown
 292                 // when trying to send to another app, to retain
 293                 // compatibility with existing tests.
 294             }
 295         }
 296
 297         instrumentation.waitForIdleSync();
 298     }
 299
 300     /**
 301      * Sends a series of key events through instrumentation and waits for idle. Each key code
 302      * must be preceded by the number of times the key code must be sent. For instance:
 303      * sendRepeatedKeys(1, KEYCODE_DPAD_CENTER, 2, KEYCODE_DPAD_LEFT).
 304      *
 305      * @param keys The series of key repeats and codes to send through instrumentation.
 306      */
 307     public void sendRepeatedKeys(int... keys) {
 308         final int count = keys.length;
 309         if ((count & 0x1) == 0x1) {
 310             throw new IllegalArgumentException("The size of the keys array must "
 311                     + "be a multiple of 2");
 312         }
 313
 314         final Instrumentation instrumentation = getInstrumentation();
 315
 316         for (int i = 0; i < count; i += 2) {
 317             final int keyCount = keys[i];
 318             final int keyCode = keys[i + 1];
 319             for (int j = 0; j < keyCount; j++) {
 320                 try {
 321                     instrumentation.sendKeyDownUpSync(keyCode);
 322                 } catch (SecurityException e) {
 323                     // Ignore security exceptions that are now thrown
 324                     // when trying to send to another app, to retain
 325                     // compatibility with existing tests.
 326                 }
 327             }
 328         }
 329
 330         instrumentation.waitForIdleSync();
 331     }
 332
 333     /**
 334      * Make sure all resources are cleaned up and garbage collected before moving on to the next
 335      * test. Subclasses that override this method should make sure they call super.tearDown()
 336      * at the end of the overriding method.
 337      *
 338      * @throws Exception
 339      */
 340     @Override
 341     protected void tearDown() throws Exception {
 342         Runtime.getRuntime().gc();
 343         Runtime.getRuntime().runFinalization();
 344         Runtime.getRuntime().gc();
 345         super.tearDown();
 346     }
 347 }