1 page.title=Instrumentation Framework 2 pdk.version=1.0 3 doc.type=porting 4 @jd:body 5 6 <a name="toc"/> 7 <div style="padding:10px"> 8 <a href="#androidInstrumentationFrameworkIntro">Introduction</a><br/> 9 <a href="#androidInstrumentationFrameworkamCommand">Understanding the am Command</a><br/> 10 <a href="#androidInstrumentationFrameworkWritingRunning">Writing and Running Test Cases</a><br/> 11 <a href="#androidInstrumentationFrameworkTestCase">Exploring a Test Case</a><br/> 12 <a href="#androidInstrumentationFrameworkTroubleshooting">Troubleshooting</a><br/></div> 13 14 <a name="androidInstrumentationFrameworkIntro"></a><h2>Introduction</h2> 15 16 <p>This document describes how to use the Instrumentation Framework to write test cases. You should have a working knowledge of the following:</p> 17 <ul> 18 <li> Android Application Framework </li> 19 <li> Using <code>adb</code>, <code>am</code> and various logging functionality </li> 20 <li> A brief understanding of the application of interest, that is, he names of the classes which handle the intents etc. </li> 21 <li> Junit testing. </li> 22 </ul> 23 <p> 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. </p> 24 25 26 <a name="androidInstrumentationFrameworkamCommand"></a><h2>Understanding the am Command</h2> 27 28 <p><code>am</code> is used to start and instrument activities using the adb shell command, as shown in the snippet below:</p> 29 <pre class="prettify"> 30 > adb shell am 31 usage: am [start|instrument] 32 am start [-a <ACTION>] [-d <DATA_URI>] [-t <MIME_TYPE>] 33 [-c <CATEGORY> [-c <CATEGORY>] ...] 34 [-e <EXTRA_KEY> <EXTRA_VALUE> [-e <EXTRA_KEY> <EXTRA_VALUE> ...] 35 [-n <COMPONENT>] [-D] [<URI>] 36 am instrument [-e <ARG_NAME> <ARG_VALUE>] [-p <PROF_FILE>] 37 [-w] <COMPONENT> 38 For example, to start the Contacts application you can use 39 > adb shell am start -n com.google.android.contacts/.ContactsActivity 40 </pre> 41 42 43 <a name="androidInstrumentationFrameworkWritingRunning"></a><h2>Writing and Running Test Cases</h2> 44 45 <p>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 <code>tests/Contacts</code> directory. </p> 46 <ul> 47 <li> There should be a Makefile and an Android Manifest file. </li> 48 <li> Tests are located in <code>tests/Contacts/src/com/google/android/contactstests</code>. </li> 49 <li> The Instrumentation Test Runner is located at <code>tests/Contacts/src/com/google/android/contactstests/functional/ContactsInstrumentationTestRunner.java</code>.</li> 50 </ul> 51 <p>Suppose you have a makefile with <code>Contactstests</code> as the target. </p> 52 <ul> 53 <li> <code>make Contactstests</code>: Compiles the test cases. </li> 54 <li> <code>adb install Contactstests.apk</code>: Installs the apk on the device. </li> 55 <li> Use the adb shell <code>am</code> command to run them. </li> 56 </ul> 57 <p> For options and other details, please see <a href="instrumentation_testing.html" target="_top">Instrumentation Testing</a>.</p> 58 59 60 <a name="androidInstrumentationFrameworkTestCase"></a><h2>Exploring a Test Case</h2> 61 62 <p> The test case described in this section adds and tests a new Contact. Note that you can send intents, register intent receivers, etc. </p> 63 <p><code>Instrumentation.java</code> has helper functions that send key events and string, for example: </p> 64 <ul> 65 <li><code>getInstrumentation()</code>: Returns the handle to the instrumentation </li> 66 <li><code>sendCharacterSync</code>: Sends a character. </li> 67 <li><code>sendStringSync</code>: Sends a string to an input box. </li> 68 <li><code>sendKeyDownUpSync</code>: Sends a specific keyevent. </li> 69 <li><code>sendTrackballEventSync</code>: Send a trackball event.</li> 70 </ul> 71 <p> You can find the test case below at <code>device/tests/Contacts.</code></p> 72 <pre class="prettify"> 73 private void addNewContact(String name, int star, int phoneType, String number, String label, 74 String email, int emailType){ 75 ContentValues values = new ContentValues(); 76 Uri phoneUri = null; 77 Uri emailUri = null; 78 79 values.put(Contacts.People.NAME, name); 80 values.put(Contacts.People.STARRED, star); 81 82 //Add Phone Numbers 83 Uri uri = mActivity.getContentResolver().insert(Contacts.People.CONTENT_URI, values); 84 phoneUri = Uri.withAppendedPath(uri, Contacts.People.Phones.CONTENT_DIRECTORY); 85 86 values.clear(); 87 values.put(Contacts.Phones.TYPE, phoneType); 88 values.put(Contacts.Phones.NUMBER, number); 89 values.put(Contacts.Phones.LABEL, label); 90 mActivity.getContentResolver().insert(phoneUri, values); 91 92 //Add Email 93 emailUri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY); 94 95 values.clear(); 96 values.put(ContactMethods.KIND, Contacts.KIND_EMAIL); 97 values.put(ContactMethods.DATA, email); 98 values.put(ContactMethods.LABEL, ""); 99 values.put(ContactMethods.TYPE, emailType); 100 mActivity.getContentResolver().insert(emailUri, values); 101 } 102 103 104 public void testAddSaveSingleContact(){ 105 int previousCount = mActivity.getListView().getCount(); 106 String message; 107 108 addNewContact(INPUT_NAME_1 + "1", "5435754532", "1" + INPUT_EMAIL_1, CONFIRM_OPTION); 109 110 message = "Added 1 to initial length=" + previousCount + ", but resulted with a count=" + 111 mActivity.getListView().getCount(); 112 assertEquals(message, ++previousCount, mActivity.getListView().getCount()); 113 114 // Check Content; Name; Num; Starred 115 assertEquals(INPUT_NAME_1 + "1", getTextFromView(0, android.R.id.text1)); 116 assertEquals("5435754532", getTextFromView(0, android.R.id.text2)); 117 118 //Check email is saved 119 //cursor = returnEmailCursorAtId("1"); 120 Uri uri = Uri.parse("content://contacts/people/1"); 121 uri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY); 122 Cursor cursor = mActivity.getContentResolver().query(uri, CONTACTS_COLUMNS, null, null, null); 123 assertTrue("returnEmailCursorAtId: Moving cursor to first row has failed", cursor.first()); 124 125 int dataIndex = cursor.getColumnIndexOrThrow("data"); 126 assertEquals("1" + INPUT_EMAIL_1, cursor.getString(dataIndex)); 127 cursor.deactivate(); 128 } 129 </pre> 130 131 132 <a name="androidInstrumentationFrameworkTroubleshooting"></a><h2>Troubleshooting</h2> 133 134 <p>If you run your test cases and nothing appears to happen, have a look at <code>adb logcat</code>. The following is a common problem:</p> 135 <pre class="prettify"> 136 I/dalvikvm( 688): threadid=11: attached from native, name=Binder Thread #1 137 I/dalvikvm( 688): threadid=13: attached from native, name=Binder Thread #2 138 W/ActivityManager( 469): Unable to find instrumentation info for: ComponentInfo{com.google.android.browser_instrumentation/com.google.android.browser_instrumentation.BrowserWebkitLayoutInstrumentation} 139 D/AndroidRuntime( 688): Shutting down VM 140 E/AndroidRuntime( 688): ERROR: thread attach failed 141 </pre> 142 <p>It's possible that the instrumentation apk isn't installed on your device or that the package name is incorrect in the Manifest file. </p> 143 144
