Android Platform Development Kit


This document describes how to use the Instrumentation Framework to write test cases. You should have a working knowledge of the following:

  • Android Application Framework
  • Using adb, am and various logging functionality
  • A brief understanding of the application of interest, that is, he names of the classes which handle the intents etc.
  • Junit testing.

Each Android application runs in its own process. Instrumentation kills the application process and restarts the process with Instrumentation. Instrumentation gives a handle to the application context used to poke around the application to validate test assertions, allowing you to write test cases to test applications at a much lower level than UI screen shot tests. Note that Instrumentation cannot catch UI bugs.

Understanding the am Command

am is used to start and instrument activities using the adb shell command, as shown in the snippet below:

> adb shell am
usage: am [start|instrument]
       am start [-a <ACTION>] [-d <DATA_URI>] [-t <MIME_TYPE>]
                [-c <CATEGORY> [-c <CATEGORY>] ...]
                [-e <EXTRA_KEY> <EXTRA_VALUE> [-e <EXTRA_KEY> <EXTRA_VALUE> ...]
                [-n <COMPONENT>] [-D] [<URI>]
       am instrument [-e <ARG_NAME> <ARG_VALUE>] [-p <PROF_FILE>]
                [-w] <COMPONENT>
For example, to start the Contacts application you can use
> adb shell am start -n

Writing and Running Test Cases

Each instrumentation test case is similar to an Android application with the distinction that it starts another application. For example, have a look in the tests/Contacts directory.

  • There should be a Makefile and an Android Manifest file.
  • Tests are located in tests/Contacts/src/com/google/android/contactstests.
  • The Instrumentation Test Runner is located at tests/Contacts/src/com/google/android/contactstests/functional/

Suppose you have a makefile with Contactstests as the target.

  • make Contactstests: Compiles the test cases.
  • adb install Contactstests.apk: Installs the apk on the device.
  • Use the adb shell am command to run them.

For options and other details, please see Instrumentation Testing.

Exploring a Test Case

The test case described in this section adds and tests a new Contact. Note that you can send intents, register intent receivers, etc. has helper functions that send key events and string, for example:

  • getInstrumentation(): Returns the handle to the instrumentation
  • sendCharacterSync: Sends a character.
  • sendStringSync: Sends a string to an input box.
  • sendKeyDownUpSync: Sends a specific keyevent.
  • sendTrackballEventSync: Send a trackball event.

You can find the test case below at device/tests/Contacts.

private void addNewContact(String name, int star, int phoneType, String number, String label,
		String email, int emailType){
	ContentValues values = new ContentValues();
	Uri phoneUri = null;
	Uri emailUri = null;

	values.put(Contacts.People.NAME, name);
	values.put(Contacts.People.STARRED, star);

	//Add Phone Numbers
	Uri uri = mActivity.getContentResolver().insert(Contacts.People.CONTENT_URI, values);
	phoneUri = Uri.withAppendedPath(uri, Contacts.People.Phones.CONTENT_DIRECTORY);

	values.put(Contacts.Phones.TYPE, phoneType);
	values.put(Contacts.Phones.NUMBER, number);
	values.put(Contacts.Phones.LABEL, label);
	mActivity.getContentResolver().insert(phoneUri, values);

	//Add Email
	emailUri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY);

	values.put(ContactMethods.KIND, Contacts.KIND_EMAIL);
	values.put(ContactMethods.DATA, email);
	values.put(ContactMethods.LABEL, "");
	values.put(ContactMethods.TYPE, emailType);
	mActivity.getContentResolver().insert(emailUri, values);

 public void testAddSaveSingleContact(){
	int previousCount = mActivity.getListView().getCount();
	String message;

	addNewContact(INPUT_NAME_1 + "1", "5435754532", "1" + INPUT_EMAIL_1, CONFIRM_OPTION);

	message = "Added 1 to initial length=" + previousCount + ", but resulted with a count=" +
	assertEquals(message, ++previousCount, mActivity.getListView().getCount());

	// Check Content; Name; Num; Starred
	assertEquals(INPUT_NAME_1 + "1", getTextFromView(0,;
	assertEquals("5435754532", getTextFromView(0,;

	//Check email is saved
	//cursor = returnEmailCursorAtId("1");
	Uri uri = Uri.parse("content://contacts/people/1");
	uri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY);
	Cursor cursor = mActivity.getContentResolver().query(uri, CONTACTS_COLUMNS, null, null, null);
	assertTrue("returnEmailCursorAtId: Moving cursor to first row has failed", cursor.first());

	int dataIndex = cursor.getColumnIndexOrThrow("data");
	assertEquals("1" + INPUT_EMAIL_1, cursor.getString(dataIndex));


If you run your test cases and nothing appears to happen, have a look at adb logcat. The following is a common problem:

I/dalvikvm(  688): threadid=11: attached from native, name=Binder Thread #1
I/dalvikvm(  688): threadid=13: attached from native, name=Binder Thread #2
W/ActivityManager(  469): Unable to find instrumentation info for: ComponentInfo{}
D/AndroidRuntime(  688): Shutting down VM
E/AndroidRuntime(  688): ERROR: thread attach failed

It's possible that the instrumentation apk isn't installed on your device or that the package name is incorrect in the Manifest file.

v0.3 - 9 June 2008