2 * Copyright (C) 2007 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
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;
26 import java.lang.reflect.Field;
27 import java.lang.reflect.InvocationTargetException;
28 import java.lang.reflect.Method;
29 import java.lang.reflect.Modifier;
31 import junit.framework.TestCase;
34 * A test case that has access to {@link Instrumentation}.
36 public class InstrumentationTestCase extends TestCase {
38 private Instrumentation mInstrumentation;
41 * Injects instrumentation into this test case. This method is
42 * called by the test runner during test setup.
44 * @param instrumentation the instrumentation to use with this instance
46 public void injectInstrumentation(Instrumentation instrumentation) {
47 mInstrumentation = instrumentation;
51 * Injects instrumentation into this test case. This method is
52 * called by the test runner during test setup.
54 * @param instrumentation the instrumentation to use with this instance
56 * @deprecated Incorrect spelling,
57 * use {@link #injectInstrumentation(android.app.Instrumentation) instead.
60 public void injectInsrumentation(Instrumentation instrumentation) {
61 injectInstrumentation(instrumentation);
65 * Inheritors can access the instrumentation using this.
66 * @return instrumentation
68 public Instrumentation getInstrumentation() {
69 return mInstrumentation;
73 * Utility method for launching an activity.
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.
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.
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.
89 public final <T extends Activity> T launchActivity(
93 Intent intent = new Intent(Intent.ACTION_MAIN);
95 intent.putExtras(extras);
97 return launchActivityWithIntent(pkg, activityCls, intent);
101 * Utility method for launching an activity with a specific Intent.
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.
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.
112 @SuppressWarnings("unchecked")
113 public final <T extends Activity> T launchActivityWithIntent(
115 Class<T> activityCls,
117 intent.setClassName(pkg, activityCls.getName());
118 intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
119 T activity = (T) getInstrumentation().startActivitySync(intent);
120 getInstrumentation().waitForIdleSync();
125 * Helper for running portions of a test on the UI thread.
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.
131 * @param r runnable containing test code in the {@link Runnable#run()} method
133 public void runTestOnUiThread(final Runnable r) throws Throwable {
134 final Throwable[] exceptions = new Throwable[1];
135 getInstrumentation().runOnMainSync(new Runnable() {
139 } catch (Throwable throwable) {
140 exceptions[0] = throwable;
144 if (exceptions[0] != null) {
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.
154 protected void runTest() throws Throwable {
155 String fName = getName();
156 assertNotNull(fName);
157 Method method = null;
159 // use getMethod to get all public inherited
160 // methods. getDeclaredMethods returns all
161 // methods of this class but excludes the
163 method = getClass().getMethod(fName, (Class[]) null);
164 } catch (NoSuchMethodException e) {
165 fail("Method \""+fName+"\" not found");
168 if (!Modifier.isPublic(method.getModifiers())) {
169 fail("Method \""+fName+"\" should be public");
173 if (method.isAnnotationPresent(FlakyTest.class)) {
174 runCount = method.getAnnotation(FlakyTest.class).tolerance();
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() {
184 runMethod(testMethod, tolerance);
185 } catch (Throwable throwable) {
186 exceptions[0] = throwable;
190 if (exceptions[0] != null) {
194 runMethod(method, runCount);
198 private void runMethod(Method runMethod, int tolerance) throws Throwable {
199 Throwable exception = null;
204 runMethod.invoke(this, (Object[]) null);
206 } catch (InvocationTargetException e) {
207 e.fillInStackTrace();
208 exception = e.getTargetException();
209 } catch (IllegalAccessException e) {
210 e.fillInStackTrace();
215 } while ((runCount < tolerance) && (exception != null));
217 if (exception != null) {
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").
229 * @param keysSequence The sequence of keys.
231 public void sendKeys(String keysSequence) {
232 final String[] keys = keysSequence.split(" ");
233 final int count = keys.length;
235 final Instrumentation instrumentation = getInstrumentation();
237 for (int i = 0; i < count; i++) {
238 String key = keys[i];
239 int repeater = key.indexOf('*');
243 keyCount = repeater == -1 ? 1 : Integer.parseInt(key.substring(0, repeater));
244 } catch (NumberFormatException e) {
245 Log.w("ActivityTestCase", "Invalid repeat count: " + key);
249 if (repeater != -1) {
250 key = key.substring(repeater + 1);
253 for (int j = 0; j < keyCount; j++) {
255 final Field keyCodeField = KeyEvent.class.getField("KEYCODE_" + key);
256 final int keyCode = keyCodeField.getInt(null);
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.
264 } catch (NoSuchFieldException e) {
265 Log.w("ActivityTestCase", "Unknown keycode: KEYCODE_" + key);
267 } catch (IllegalAccessException e) {
268 Log.w("ActivityTestCase", "Unknown keycode: KEYCODE_" + key);
274 instrumentation.waitForIdleSync();
278 * Sends a series of key events through instrumentation and waits for idle. For instance:
279 * sendKeys(KEYCODE_DPAD_LEFT, KEYCODE_DPAD_CENTER).
281 * @param keys The series of key codes to send through instrumentation.
283 public void sendKeys(int... keys) {
284 final int count = keys.length;
285 final Instrumentation instrumentation = getInstrumentation();
287 for (int i = 0; i < count; i++) {
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.
297 instrumentation.waitForIdleSync();
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).
305 * @param keys The series of key repeats and codes to send through instrumentation.
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");
314 final Instrumentation instrumentation = getInstrumentation();
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++) {
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.
330 instrumentation.waitForIdleSync();
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.
341 protected void tearDown() throws Exception {
342 Runtime.getRuntime().gc();
343 Runtime.getRuntime().runFinalization();
344 Runtime.getRuntime().gc();