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