1 page.title=Activity Testing 2 parent.title=Tutorials 3 parent.link=../../browser.html?tag=tutorial 4 @jd:body 5 <div id="qv-wrapper"> 6 <div id="qv"> 7 <h2>In this document</h2> 8 <ol> 9 <li> 10 <a href="#Prerequisites">Prerequisites</a> 11 </li> 12 <li> 13 <a href="#DownloadCode">Installing the Tutorial Sample Code</a> 14 </li> 15 <li> 16 <a href="#SetupEmulator">Setting Up the Emulator</a> 17 </li> 18 <li> 19 <a href="#SetupProjects">Setting Up the Projects</a> 20 </li> 21 <li> 22 <a href="#CreateTestCaseClass">Creating the Test Case Class</a> 23 <ol> 24 <li> 25 <a href="#AddTestCaseClass">Adding the test case class file</a> 26 </li> 27 <li> 28 <a href="#AddConstructor">Adding the test case constructor</a> 29 </li> 30 <li> 31 <a href="#AddSetupMethod">Adding the setup method</a> 32 </li> 33 <li> 34 <a href="#AddPreConditionsTest">Adding an initial conditions test</a> 35 </li> 36 <li> 37 <a href="#AddUITest">Adding a UI test</a> 38 </li> 39 <li> 40 <a href="#StateManagementTests">Adding state management tests</a> 41 </li> 42 </ol> 43 </li> 44 <li> 45 <a href="#RunTests">Running the Tests and Seeing the Results</a> 46 </li> 47 <li> 48 <a href="#TestFailure">Forcing Some Tests to Fail</a> 49 </li> 50 <li> 51 <a href="#NextSteps">Next Steps</a> 52 </li> 53 </ol> 54 <h2 id="#Appendix">Appendix</h2> 55 <ol> 56 <li> 57 <a href="#InstallCompletedTestApp">Installing the Completed Test Application Java File</a> 58 </li> 59 <li> 60 <a href="#EditorCommandLine">For Users Not Developing In Eclipse</a> 61 </li> 62 </ol> 63 <h2>Related Tutorials</h2> 64 <ol> 65 <li> 66 <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, Testing</a> 67 </li> 68 </ol> 69 <h2>See Also</h2> 70 <ol> 71 <li> 72 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> 73 </li> 74 <li> 75 {@link android.test.ActivityInstrumentationTestCase2} 76 </li> 77 <li> 78 {@link junit.framework.Assert} 79 </li> 80 <li> 81 {@link android.test.InstrumentationTestRunner} 82 </li> 83 </ol> 84 </div> 85 </div> 86 <p> 87 Android includes powerful tools for testing applications. The tools extend JUnit with additional features, provide convenience classes for mock Android system objects, and use 88 instrumentation to give you control over your main application while you are testing it. The entire Android testing environment is discussed in the document 89 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a>. 90 </p> 91 <p> 92 This tutorial demonstrates the Android testing tools by presenting a simple Android application and then leading you step-by-step through the creation of a test application for it. 93 The test application demonstrates these key points: 94 </p> 95 <ul> 96 <li> 97 An Android test is itself an Android application that is linked to the application under test by entries in its <code>AndroidManifest.xml</code> file. 98 </li> 99 <li> 100 Instead of Android components, an Android test application contains one or more test cases. Each of these is a separate class definition. 101 </li> 102 <li> 103 Android test case classes extend the JUnit {@link junit.framework.TestCase} class. 104 </li> 105 <li> 106 Android test case classes for activities extend JUnit and also connect you to the application under test with instrumentation. You can send keystroke or touch events directly to the UI. 107 </li> 108 <li> 109 You choose an Android test case class based on the type of component (application, activity, content provider, or service) you are testing. 110 </li> 111 <li> 112 Additional test tools in Eclipse/ADT provide integrated support for creating test applications, running them, and viewing the results. 113 </li> 114 </ul> 115 <p> 116 The test application contains methods that perform the following tests: 117 </p> 118 <ul> 119 <li> 120 Initial conditions test. Tests that the application under test initializes correctly. This is also a unit test of the application's 121 {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method. Testing initial conditions also provides a confidence measure for subsequent tests. 122 </li> 123 <li> 124 UI test. Tests that the main UI operation works correctly. This test demonstrates the instrumentation features available in activity testing. 125 It shows that you can automate UI tests by sending key events from the test application to the main application. 126 </li> 127 <li> 128 State management tests. Test the application's code for saving state. This test demonstrates the instrumentation features of the test runner, which 129 are available for testing any component. 130 </li> 131 </ul> 132 <h2 id="Prerequisites">Prerequisites</h2> 133 <p> 134 The instructions and code in this tutorial depend on the following: 135 </p> 136 <ul> 137 <li> 138 Basic knowledge of Android programming. If you haven't yet written an Android application, do the 139 <a href="{@docRoot}resources/tutorials/hello-world.html">Hello, World</a> tutorial. If you 140 want to learn more about Spinner, the application under test, then you might want to visit the 141 <a href="{@docRoot}resources/tutorials/views/hello-spinner.html">Hello Views > Spinner</a> example. 142 </li> 143 <li> 144 Some familiarity with the Android testing framework and concepts. If you haven't explored 145 Android testing yet, start by reading the Developer Guide topic <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> 146 or following the <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> 147 Hello, Testing</a> tutorial. 148 </li> 149 <li> 150 Eclipse with ADT. This tutorial describes how to set up and run a test application using 151 Eclipse with ADT. If you haven't yet installed Eclipse and the ADT plugin, 152 follow the steps in <a href="{@docRoot}sdk/installing.html">Installing the SDK</a> 153 to install them before continuing. If you are not developing in Eclipse, you will 154 find instructions for setting up and running the test application in the 155 <a href="#EditorCommandLine">appendix</a> of this document. 156 </li> 157 <li> 158 Android 1.5 platform (API Level 3) or higher. You must have the Android 1.5 platform 159 (API Level 3) or higher installed in your SDK, because this tutorial uses APIs that 160 were introduced in that version. 161 <p> 162 If you are not sure which platforms are installed in your SDK, 163 open the Android SDK and AVD Manager and check in the 164 <strong>Installed Packages</strong> panel. 165 If aren't sure how to download a platform into your SDK, 166 read <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. 167 </p> 168 </li> 169 </ul> 170 <h2 id="DownloadCode">Installing the Tutorial Sample Code</h2> 171 <p> 172 During this tutorial, you will be working with sample code that is provided as part 173 of the downloadable Samples component of the SDK. Specifically, you will be working 174 with a pair of related sample applications — an application under test and a test 175 application: 176 </p> 177 <ul> 178 <li> 179 Spinner is the application under test. This tutorial focuses on the 180 common situation of writing tests for an application that already exists, so the main 181 application is provided to you. 182 </li> 183 <li> 184 SpinnerTest is the test application. In the tutorial, you create this application 185 step-by-step. If you want to run quickly through the tutorial, 186 you can install the completed SpinnerTest application first, and then follow the 187 text. You may get more from the tutorial, however, if you create the test application 188 as you go. The instructions for installing the completed test application are in the 189 section <a href="#InstallCompletedTestApp">Installing the Completed Test Application Java File</a>. 190 </li> 191 </ul> 192 <p> 193 The sample applications are provided in the SDK component named 194 "Samples for SDK API 8" and in later versions of the Samples. 195 </p> 196 <p> 197 To get started with the tutorial, first use the Android SDK and AVD manager to install an 198 appropriate version of the Samples: 199 </p> 200 <ol> 201 <li> 202 In Eclipse, select <strong>Window</strong> > <strong>Android SDK and AVD Manager</strong>. 203 </li> 204 <li> 205 Open the <strong>Installed Packages</strong> panel and check whether 206 "Samples for SDK API 8" (or higher version) is listed. 207 If so, skip to the next section, 208 <a href="#SetupProjects">Setting Up the Projects</a>, to get started with the tutorial. 209 Otherwise, continue with the next step. 210 </li> 211 <li> 212 Open the <strong>Available Packages</strong> panel. 213 </li> 214 <li> 215 Select the "Samples for SDK API 8" component and click <strong>Install Selected</strong>. 216 </li> 217 <li> 218 Verify and accept the component and then click <strong>Install Accepted</strong>. 219 The Samples component will now be installed into your SDK. 220 </li> 221 </ol> 222 <p> 223 When the installation is complete, the applications in the 224 Samples component are stored at this location on your computer: 225 </p> 226 <p style="margin-left:2em"> 227 <code><<em>sdk</em>>/samples/android-8/</code> 228 </p> 229 <p> 230 For general information about the Samples, see 231 <a href="{@docRoot}resources/samples/get.html">Getting the Samples</a> 232 </p> 233 <p class="note"> 234 <strong>Note:</strong> Although the sample code for this tutorial is provided in the 235 "Samples for SDK API 8" component, that does not imply that you need to build or 236 run the application against the corresponding platform (Android 2.2). 237 The API level referenced in the Samples component name indicates only the origin branch from 238 which the samples were built. 239 </p> 240 <h2 id="SetupEmulator">Setting Up the Emulator</h2> 241 <p> 242 In this tutorial, you will use the Android emulator to run applications. The emulator needs 243 an Android Virtual Device (AVD) with an API level equal to or higher than the one you set for the projects in the previous step. 244 To find out how to check this and create the right AVD if necessary, 245 see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Creating an AVD</a>. 246 </p> 247 <p> 248 As a test of the AVD and emulator, run the SpinnerActivity application in Eclipse with ADT. When it starts, 249 click the large downward-pointing arrow to the right of the spinner text. You see the spinner expand and display the title "Select a planet" at the top. 250 Click one of the other planets. The spinner closes, and your selection appears below it on the screen. 251 </p> 252 <h2 id="SetupProjects">Setting Up the Projects</h2> 253 <p> 254 When you are ready to get started with the tutorial, begin by setting up Eclipse projects for 255 both Spinner (the application under test) and SpinnerTest (the test application). 256 </p> 257 <p> 258 You'll be using the Spinner application as-is, without modification, so you'll be loading it 259 into Eclipse as a new Android project from existing source. In the process, you'll be 260 creating a new test project associated with Spinner that will contain the SpinnerTest 261 application. The SpinnerTest application will be completely new and you'll be 262 using the code examples in this tutorial to add test classes and tests to it. 263 </p> 264 <p> 265 To install the Spinner app in a new Android project from existing source, following these steps: 266 </p> 267 <ol> 268 <li> 269 In Eclipse, select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong> > <strong>Android</strong> > <strong>Android Project</strong>, 270 then click Next. The <strong>New Android Project</strong> dialog appears. 271 </li> 272 <li> 273 In the <em>Project name</em> text box, enter "SpinnerActivity". The <em>Properties</em> area is filled in automatically. 274 </li> 275 <li> 276 In the <em>Contents</em> area, set "Create project from existing source". 277 </li> 278 <li> 279 For <em>Location</em>, click <strong>Browse</strong>, navigate to the directory <code><SDK_path>/samples/android-8/Spinner</code>, 280 then click Open. The directory name <code><SDK_path>/samples/android-8/Spinner</code> now appears in the <em>Location</em> text box. 281 </li> 282 <li> 283 In the <em>Build Target</em> area, set a API level of 3 or higher. If you are already developing with a particular target, and it is API level 3 or higher, then use that target. 284 </li> 285 <li> 286 In the <em>Properties</em> area, in the <em>Min SDK Version:</em>, enter "3". 287 </li> 288 <li> 289 You should now see these values: 290 <ul> 291 <li><em>Project Name:</em> "SpinnerActivity"</li> 292 <li><em>Create project from existing source:</em> set</li> 293 <li><em>Location:</em> "<code><SDK_path>/samples/android-8/Spinner</code>"</li> 294 <li><em>Build Target:</em> "API level of 3 or higher" (<em>Target Name</em> "Android 1.5 or higher")</li> 295 <li><em>Package name:</em> (disabled, set to "<code>com.android.example.spinner</code>")</li> 296 <li><em>Create Activity:</em> (disabled, set to ".SpinnerActivity")</li> 297 <li><em>Min SDK Version:</em> "3"</li> 298 </ul> 299 <p> 300 The following screenshot summarizes these values: 301 </p> 302 <a href="{@docRoot}images/testing/eclipse_new_android_project_complete_callouts.png"> 303 <img src="{@docRoot}images/testing/eclipse_new_android_project_complete_callouts.png" alt="New Android Project dialog with filled-in values" style="height:230px"/> 304 </a> 305 306 </li> 307 </ol> 308 <p> 309 To create a new test project for the SpinnerTest application, follow these steps: 310 </p> 311 <ol> 312 <li> 313 Click Next. The <strong>New Android Test Project</strong> dialog appears. 314 </li> 315 <li> 316 Set "Create a Test Project". 317 </li> 318 <li> 319 Leave the other values unchanged. The result should be: 320 <ul> 321 <li><em>Create a Test Project:</em> checked</li> 322 <li><em>Test Project Name:</em> "SpinnerActivityTest"</li> 323 <li><em>Use default location:</em> checked (this should contain the directory name "<code>workspace/SpinnerActivityTest</code>").</li> 324 <li><em>Build Target:</em> Use the same API level you used in the previous step.</li> 325 <li><em>Application name:</em> "SpinnerActivityTest"</li> 326 <li><em>Package name:</em> "<code>com.android.example.spinner.test</code>"</li> 327 <li><em>Min SDK Version:</em> "3"</li> 328 </ul> 329 <p> 330 The following screenshot summarizes these values: 331 </p> 332 <a href="{@docRoot}images/testing/eclipse_new_android_testproject_complete_callouts.png"> 333 <img src="{@docRoot}images/testing/eclipse_new_android_testproject_complete_callouts.png" alt="New Android Test Project dialog with filled-in values" style="height:230px"/> 334 </a> 335 </li> 336 <li> 337 Click Finish. Entries for SpinnerActivity and SpinnerActivityTest should appear in the 338 <strong>Package Explorer</strong>. 339 <p class="note"> 340 <strong>Note:</strong> If you set <em>Build Target</em> to an API level higher than "3", you will see the warning 341 "The API level for the selected SDK target does not match the Min SDK version". You do not need to change the API level or the Min SDK version. 342 The message tells you that you are building the projects with one particular API level, but specifying that a lower API level is required. This may 343 occur if you have chosen not to install the optional earlier API levels. 344 </p> 345 <p> 346 If you see errors listed in the <strong>Problems</strong> pane at the bottom of the Eclipse window, or if a red error marker appears next to 347 the entry for SpinnerActivity in the Package Explorer, highlight the SpinnerActivity entry and then select 348 <strong>Project</strong> > <strong>Clean</strong>. This should fix any errors. 349 </p> 350 </li> 351 </ol> 352 <p> 353 You now have the application under test in the SpinnerActivity project, 354 and an empty test project in SpinnerActivityTest. You may 355 notice that the two projects are in different directories, but Eclipse with 356 ADT handles this automatically. You should have no problem in either building or running them. 357 </p> 358 <p> 359 Notice that Eclipse and ADT have already done some initial setup for your test application. 360 Expand the SpinnerActivityTest project, and notice that it already has an 361 Android manifest file <code>AndroidManifest.xml</code>. 362 Eclipse with ADT created this when you added the test project. 363 Also, the test application is already set up to use instrumentation. You can see this 364 by examining <code>AndroidManifest.xml</code>. 365 Open it, then at the bottom of the center pane click <strong>AndroidManifest.xml</strong> 366 to display the XML contents: 367 </p> 368 <pre> 369 <?xml version="1.0" encoding="utf-8"?> 370 <manifest xmlns:android="http://schemas.android.com/apk/res/android" 371 package="com.android.example.spinner.test" 372 android:versionCode="1" 373 android:versionName="1.0"> 374 <uses-sdk android:minSdkVersion="3" /> 375 <instrumentation 376 android:targetPackage="com.android.example.spinner" 377 android:name="android.test.InstrumentationTestRunner" /> 378 <application android:icon="@drawable/icon" android:label="@string/app_name"> 379 <uses-library android:name="android.test.runner" /> 380 ... 381 </application> 382 </manifest> 383 </pre> 384 <p> 385 Notice the <code><instrumentation></code> element. The attribute 386 <code>android:targetPackage="com.android.example.spinner"</code> tells Android that the 387 application under test is defined in the Android package 388 <code>com.android.example.spinner</code>. Android now knows to use that 389 package's <code>AndroidManifest.xml</code> file to launch the application under test. 390 The <code><instrumentation></code> element also contains the attribute 391 <code>android:name="android.test.InstrumentationTestRunner"</code>, which tells Android 392 instrumentation to run the test application with Android's instrumentation-enabled test runner. 393 </p> 394 <h2 id="CreateTestCaseClass">Creating the Test Case Class</h2> 395 396 <p> 397 You now have a test project SpinnerActivityTest, and the basic structure of a test 398 application also called SpinnerActivityTest. The basic structure includes all the files and 399 directories you need to build and run a test application, except for the class that 400 contains your tests (the test case class). 401 </p> 402 <p> 403 The next step is to define the test case class. In this tutorial, you'll be creating a 404 test case class that includes: 405 </p> 406 <ul> 407 <li> 408 Test setup. This use of the JUnit {@link junit.framework.TestCase#setUp() setUp()} 409 method demonstrates some of the tasks you might perform before running an Android test. 410 </li> 411 <li> 412 Testing initial conditions. This test demonstrates a good testing technique. 413 It also demonstrates that with Android instrumentation you can look at the application 414 under test <em>before</em> the main activity starts. The test checks that the application's 415 important objects have been initialized. 416 If the test fails, you then know that any other tests against the application are 417 unreliable, since the application was running in an incorrect state. 418 <p class="note"> 419 <strong>Note:</strong> The purpose of testing initial conditions is not the same as 420 using <code>setUp()</code>. The JUnit {@link junit.framework.TestCase#setUp()} runs once 421 before <strong>each test method</strong>, and its purpose is to create a clean test 422 environment. The initial conditions test runs once, and its purpose is to verify that the 423 application under test is ready to be tested. 424 </p> 425 </li> 426 <li> 427 Testing the UI. This test shows how to control the main application's UI 428 with instrumentation, a powerful automation feature of Android testing. 429 </li> 430 <li> 431 Testing state management. This test shows some techniques for testing how 432 well the application maintains state in the Android environment. Remember that to 433 provide a satisfactory user experience, your application must never lose its current state, 434 even if it's interrupted by a phone call or destroyed because of memory constraints. 435 The Android activity lifecycle provides ways to maintain state, and the 436 <code>SpinnerActivity</code> application uses them. The test shows the techniques for 437 verifying that they work. 438 </li> 439 </ul> 440 <p> 441 Android tests are contained in a special type of Android application that contains one or more test class definitions. Each of these contains 442 one or more test methods that do the actual tests. In this tutorial, you will first add a test case class, and then add tests to it. 443 </p> 444 <p> 445 You first choose an Android test case class to extend. You choose from the base test case classes according to the Android component you are testing and the types of tests you are doing. 446 In this tutorial, the application under test has a single simple activity, so the test case class will be for an Activity component. Android offers several, but the one that tests in 447 the most realistic environment is {@link android.test.ActivityInstrumentationTestCase2}, so you will use it as the base class. Like all activity test case classes, 448 <code>ActivityInstrumentationTestCase2</code> offers convenience methods for interacting directly with the UI of the application under test. 449 </p> 450 <h3 id="AddTestCaseClass">Adding the test case class file</h3> 451 <p> 452 To add <code>ActivityInstrumentationTestCase2</code> as the base test case class, follow these steps: 453 </p> 454 <ol> 455 <li> 456 In the Package Explorer, expand the test project SpinnerActivityTest if it is not open already. 457 </li> 458 <li> 459 Within SpinnerActivityTest, expand the <code>src/</code> folder and then the package marker for 460 <code>com.android.example.spinner.test</code>. Right-click on the package name and select <strong>New</strong> > <strong>Class</strong>:<br/> 461 <a href="{@docRoot}images/testing/spinner_create_test_class_callouts.png"> 462 <img alt="Menu for creating a new class in the test application" src="{@docRoot}images/testing/spinner_create_test_class_callouts.png" style="height:230px"/> 463 </a> 464 <p> 465 The <strong>New Java Class</strong> wizard appears: 466 </p> 467 <a href="{@docRoot}images/testing/spinnertest_new_class_callouts.png"> 468 <img alt="New Java Class wizard dialog" src="{@docRoot}images/testing/spinnertest_new_class_callouts.png" style="height:230px"/> 469 </a> 470 </li> 471 <li> 472 In the wizard, enter the following: 473 <ul> 474 <li> 475 <em>Name:</em> "SpinnerActivityTest". This becomes the name of your test class. 476 </li> 477 <li> 478 <em>Superclass:</em> "<code>android.test.ActivityInstrumentationTestCase2<SpinnerActivity></code>". The superclass is parameterized, so 479 you have to provide it your main application's class name. 480 </li> 481 </ul> 482 <p> 483 Do not change any of the other settings. Click Finish. 484 </p> 485 </li> 486 <li> 487 You now have a new file <code>SpinnerActivityTest.java</code> in the project. 488 </li> 489 <li> 490 To resolve the reference to SpinnerActivity, add the following import: 491 <pre> 492 import com.android.example.spinner.SpinnerActivity; 493 </pre> 494 </li> 495 </ol> 496 <h3 id="AddConstructor">Adding the test case constructor</h3> 497 <p> 498 To ensure that the test application is instantiated correctly, you must set up a constructor that the test 499 runner will call when it instantiates your test class. This constructor has no parameters, and its sole 500 purpose is to pass information to the superclass's default constructor. To set up this constructor, enter the 501 following code in the class: 502 </p> 503 <pre> 504 public SpinnerActivityTest() { 505 super("com.android.example.spinner", SpinnerActivity.class); 506 } // end of SpinnerActivityTest constructor definition 507 </pre> 508 <p> 509 This calls the superclass constructor with the Android package name (<code>com.android.example.spinner</code>)and main activity's class 510 (<code>SpinnerActivity.class</code>) for the application under test. Android uses this information to find the application and activity to test. 511 </p> 512 <p> 513 You are now ready to add tests, by adding test methods to the class. 514 </p> 515 <h3 id="AddSetupMethod">Adding the setup method</h3> 516 <p> 517 The <code>setUp()</code> method is invoked before every test. You use it to initialize variables and clean up from previous tests. You can also use 518 the JUnit {@link junit.framework.TestCase#tearDown() tearDown()} method, which runs <strong>after</strong> every test method. The tutorial does not use it. 519 </p> 520 <p> 521 The method you are going to add does the following: 522 </p> 523 <ul> 524 <li> 525 <code>super.setUp()</code>. Invokes the superclass constructor for <code>setUp()</code>, which is required by JUnit. 526 </li> 527 <li> 528 Calls {@link android.test.ActivityInstrumentationTestCase2#setActivityInitialTouchMode(boolean) setActivityInitialTouchMode(false)}. 529 This turns off <strong>touch mode</strong> in the device or emulator. If any of your test methods send key events to the application, 530 you must turn off touch mode <em>before</em> you start any activities; otherwise, the call is ignored. 531 </li> 532 <li> 533 Stores references to system objects. Retrieves and stores a reference to the activity under test, the <code>Spinner</code> 534 widget used by the activity, the <code>SpinnerAdapter</code> that backs the widget, and the string value of the selection that is 535 set when the application is first installed. These objects are used in the state management test. The methods invoked are: 536 <ul> 537 <li> 538 {@link android.test.ActivityInstrumentationTestCase2#getActivity()}. Gets a reference to the activity under test (<code>SpinnerActivity</code>). 539 This call also starts the activity if it is not already running. 540 </li> 541 <li> 542 {@link android.app.Activity#findViewById(int)}. Gets a reference to the <code>Spinner</code> widget of the application under test. 543 </li> 544 <li> 545 {@link android.widget.AbsSpinner#getAdapter()}. Gets a reference to the adapter (an array of strings) backing the spinner. 546 </li> 547 </ul> 548 </li> 549 </ul> 550 <p> 551 Add this code to the definition of <code>SpinnerActivityTest</code>, after the constructor definition: 552 </p> 553 <pre> 554 @Override 555 protected void setUp() throws Exception { 556 super.setUp(); 557 558 setActivityInitialTouchMode(false); 559 560 mActivity = getActivity(); 561 562 mSpinner = 563 (Spinner) mActivity.findViewById( 564 com.android.example.spinner.R.id.Spinner01 565 ); 566 567 mPlanetData = mSpinner.getAdapter(); 568 569 } // end of setUp() method definition 570 </pre> 571 <p> 572 Add these members to the test case class: 573 </p> 574 <pre> 575 private SpinnerActivity mActivity; 576 private Spinner mSpinner; 577 private SpinnerAdapter mPlanetData; 578 </pre> 579 <p> 580 Add these imports: 581 </p> 582 <pre> 583 import android.widget.Spinner; 584 import android.widget.SpinnerAdapter; 585 </pre> 586 <p> 587 You now have the the complete <code>setUp()</code> method. 588 </p> 589 <h3 id="AddPreConditionsTest">Adding an initial conditions test</h3> 590 <p> 591 The initial conditions test verifies that the application under test is initialized correctly. It is an illustration of the types of tests you can run, so it is not comprehensive. 592 It verifies the following: 593 </p> 594 <ul> 595 <li> 596 The item select listener is initialized. This listener is called when a selection is made from the spinner. 597 </li> 598 <li> 599 The adapter that provides values to the spinner is initialized. 600 </li> 601 <li> 602 The adapter contains the right number of entries. 603 </li> 604 </ul> 605 <p> 606 The actual initialization of the application under test is done in <code>setUp()</code>, which the test runner calls automatically before every test. The verifications are 607 done with JUnit {@link junit.framework.Assert} calls. As a useful convention, the method name is <code>testPreConditions()</code>: 608 </p> 609 <pre> 610 public void testPreConditions() { 611 assertTrue(mSpinner.getOnItemSelectedListener() != null); 612 assertTrue(mPlanetData != null); 613 assertEquals(mPlanetData.getCount(),ADAPTER_COUNT); 614 } // end of testPreConditions() method definition 615 </pre> 616 <p> 617 Add this member: 618 </p> 619 <pre> 620 public static final int ADAPTER_COUNT = 9; 621 </pre> 622 <h3 id="AddUITest">Adding a UI test</h3> 623 <p> 624 Now create a UI test that selects an item from the <code>Spinner</code> widget. The test sends key events to the UI with key events. 625 The test confirms that the selection matches the result you expect. 626 </p> 627 <p> 628 This test demonstrates the power of using instrumentation in Android testing. Only an instrumentation-based test class allows you to send key events (or touch events) 629 to the application under test. With instrumentation, you can test your UI without having to take screenshots, record the screen, or do human-controlled testing. 630 </p> 631 <p> 632 To work with the spinner, the test has to request focus for it and then set it to a known position. The test uses {@link android.view.View#requestFocus() requestFocus()} and 633 {@link android.widget.AbsSpinner#setSelection(int) setSelection()} to do this. Both of these methods interact with a View in the application under test, so you have to call them 634 in a special way. 635 </p> 636 <p> 637 Code in a test application that interacts with a View of the application under test must run in the main application's thread, also 638 known as the <em>UI thread</em>. To do this, you use the {@link android.app.Activity#runOnUiThread(java.lang.Runnable) Activity.runOnUiThread()} 639 method. You pass the code to <code>runOnUiThread()</code>in an anonymous {@link java.lang.Runnable Runnable} object. To set 640 the Java statements in the <code>Runnable</code> object, you override the object's {@link java.lang.Runnable#run()} method. 641 </p> 642 <p> 643 To send key events to the UI of the application under test, you use the <a href="{@docRoot}reference/android/test/InstrumentationTestCase.html#sendKeys(int...)">sendKeys</a>() method. 644 This method does not have to run on the UI thread, since Android uses instrumentation to pass the key events to the application under test. 645 </p> 646 <p> 647 The last part of the test compares the selection made by sending the key events to a pre-determined value. This tests that the spinner is working as intended. 648 </p> 649 <p> 650 The following sections show you how to add the code for this test. 651 </p> 652 <ol> 653 <li> 654 Get focus and set selection. Create a new method <code>public void testSpinnerUI()</code>. Add 655 code to to request focus for the spinner and set its position to default or initial position, "Earth". This code is run on the UI thread of 656 the application under test: 657 <pre> 658 public void testSpinnerUI() { 659 660 mActivity.runOnUiThread( 661 new Runnable() { 662 public void run() { 663 mSpinner.requestFocus(); 664 mSpinner.setSelection(INITIAL_POSITION); 665 } // end of run() method definition 666 } // end of anonymous Runnable object instantiation 667 ); // end of invocation of runOnUiThread 668 </pre> 669 <p> 670 Add the following member to the test case class. 671 </p> 672 <pre> 673 public static final int INITIAL_POSITION = 0; 674 </pre> 675 </li> 676 <li> 677 Make a selection. Send key events to the spinner to select one of the items. To do this, open the spinner by 678 "clicking" the center keypad button (sending a DPAD_CENTER key event) and then clicking (sending) the down arrow keypad button five times. Finally, 679 click the center keypad button again to highlight the desired item. Add the following code: 680 <pre> 681 this.sendKeys(KeyEvent.KEYCODE_DPAD_CENTER); 682 for (int i = 1; i <= TEST_POSITION; i++) { 683 this.sendKeys(KeyEvent.KEYCODE_DPAD_DOWN); 684 } // end of for loop 685 686 this.sendKeys(KeyEvent.KEYCODE_DPAD_CENTER); 687 </pre> 688 <p> 689 Add the following member to the test case class: 690 </p> 691 <pre> 692 public static final int TEST_POSITION = 5; 693 </pre> 694 <p> 695 This sets the final position of the spinner to "Saturn" (the spinner's backing adapter is 0-based). 696 </p> 697 </li> 698 <li> 699 Check the result. Query the current state of the spinner, and compare its current selection to the expected value. 700 Call the method {@link android.widget.AdapterView#getSelectedItemPosition() getSelectedItemPosition()} to find out the current selection position, and then 701 {@link android.widget.AdapterView#getItemAtPosition(int) getItemAtPosition()} to get the object corresponding to that position (casting it to a String). Assert that 702 this string value matches the expected value of "Saturn": 703 <pre> 704 mPos = mSpinner.getSelectedItemPosition(); 705 mSelection = (String)mSpinner.getItemAtPosition(mPos); 706 TextView resultView = 707 (TextView) mActivity.findViewById( 708 com.android.example.spinner.R.id.SpinnerResult 709 ); 710 711 String resultText = (String) resultView.getText(); 712 713 assertEquals(resultText,mSelection); 714 715 } // end of testSpinnerUI() method definition 716 </pre> 717 <p> 718 Add the following members to the test case class: 719 </p> 720 <pre> 721 private String mSelection; 722 private int mPos; 723 </pre> 724 <p> 725 Add the following imports to the test case class: 726 </p> 727 <pre> 728 import android.view.KeyEvent; 729 import android.widget.TextView; 730 </pre> 731 </li> 732 </ol> 733 <p> 734 Pause here to run the tests you have. The procedure for running a test application is different 735 from running a regular Android application. You run a test application as an Android JUnit 736 application. To see how to do this, see <a href="#RunTests">Running the Tests and Seeing the Results</a>. 737 </p> 738 <p> 739 Eventually, you will see the <code>SpinnerActivity</code> application start, and the test 740 application controlling it by sending it key events. You will also see a new 741 <strong>JUnit</strong> view in the Explorer pane, showing the results of the 742 test. The JUnit view is documented in a following section, 743 <a href="#RunTests">Running the Test and Seeing the Results</a>. 744 </p> 745 <h3 id="StateManagementTests">Adding state management tests</h3> 746 <p> 747 You now write two tests that verify that SpinnerActivity maintains its state when it is paused or terminated. 748 The state, in this case, is the current selection in the spinner. When users make a selection, 749 pause or terminate the application, and then resume or restart it, they should see 750 the same selection. 751 </p> 752 <p> 753 Maintaining state is an important feature of an application. Users may switch from the current 754 application temporarily to answer the phone, and then switch back. Android may decide to 755 terminate and restart an activity to change the screen orientation, or terminate an unused 756 activity to regain storage. In each case, users are best served by having the UI return to its 757 previous state (except where the logic of the application dictates otherwise). 758 </p> 759 <p> 760 SpinnerActivity manages its state in these ways: 761 </p> 762 <ul> 763 <li> 764 Activity is hidden. When the spinner screen (the activity) is running but hidden by some other screen, it 765 stores the spinner's position and value in a form that persists while the application is running. 766 </li> 767 <li> 768 Application is terminated. When the activity is terminated, it stores the spinner's position and value in 769 a permanent form. The activity can read the position and value when it restarts, and restore the spinner to its previous state. 770 </li> 771 <li> 772 Activity re-appears. When the user returns to the spinner screen, the previous selection is restored. 773 </li> 774 <li> 775 Application is restarted. When the user starts the application again, the previous selection is restored. 776 </li> 777 </ul> 778 <p class="note"> 779 <strong>Note:</strong> An application can manage its state in other ways as well, but these are 780 not covered in this tutorial. 781 </p> 782 <p> 783 When an activity is hidden, it is <strong>paused</strong>. When it re-appears, it 784 <strong>resumes</strong>. Recognizing that these are key points in an activity's life cycle, 785 the Activity class provides two callback methods {@link android.app.Activity#onPause()} and 786 {@link android.app.Activity#onResume()} for handling pauses and resumes. 787 SpinnerActivity uses them for code that saves and restores state. 788 </p> 789 <p> 790 <strong>Note:</strong> If you would like to learn more about the difference between losing 791 focus/pausing and killing an application, 792 read about the <a href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">activity 793 lifecycle</a>. 794 </p> 795 <p> 796 The first test verifies that the spinner selection is maintained after the entire application is shut down and then restarted. The test uses instrumentation to 797 set the spinner's variables outside of the UI. It then terminates the activity by calling {@link android.app.Activity#finish() Activity.finish()}, and restarts it 798 using the instrumentation method {@link android.test.ActivityInstrumentationTestCase2#getActivity()}. The test then asserts that the current spinner state matches 799 the test values. 800 </p> 801 <p> 802 The second test verifies that the spinner selection is maintained after the activity is paused and then resumed. The test uses instrumentation to 803 set the spinner's variables outside of the UI and then force calls to the <code>onPause()</code> and <code>onResume()</code> methods. The test then 804 asserts that the current spinner state matches the test values. 805 </p> 806 <p> 807 Notice that these tests make limited assumptions about the mechanism by which the activity manages state. The tests use the activity's getters and 808 setters to control the spinner. The first test also knows that hiding an activity calls <code>onPause()</code>, and bringing it back to the foreground 809 calls <code>onResume()</code>. Other than this, the tests treat the activity as a "black box". 810 </p> 811 <p> 812 To add the code for testing state management across shutdown and restart, follow these steps: 813 </p> 814 <ol> 815 <li> 816 Add the test method <code>testStateDestroy()</code>, then 817 set the spinner selection to a test value: 818 <pre> 819 public void testStateDestroy() { 820 mActivity.setSpinnerPosition(TEST_STATE_DESTROY_POSITION); 821 mActivity.setSpinnerSelection(TEST_STATE_DESTROY_SELECTION); 822 </pre> 823 </li> 824 <li> 825 Terminate the activity and restart it: 826 <pre> 827 mActivity.finish(); 828 mActivity = this.getActivity(); 829 </pre> 830 </li> 831 <li> 832 Get the current spinner settings from the activity: 833 <pre> 834 int currentPosition = mActivity.getSpinnerPosition(); 835 String currentSelection = mActivity.getSpinnerSelection(); 836 </pre> 837 </li> 838 <li> 839 Test the current settings against the test values: 840 <pre> 841 assertEquals(TEST_STATE_DESTROY_POSITION, currentPosition); 842 assertEquals(TEST_STATE_DESTROY_SELECTION, currentSelection); 843 } // end of testStateDestroy() method definition 844 </pre> 845 <p> 846 Add the following members to the test case class: 847 <pre> 848 public static final int TEST_STATE_DESTROY_POSITION = 2; 849 public static final String TEST_STATE_DESTROY_SELECTION = "Earth"; 850 </pre> 851 </li> 852 </ol> 853 <p> 854 To add the code for testing state management across a pause and resume, follow these steps: 855 </p> 856 <ol> 857 <li> 858 Add the test method <code>testStatePause()</code>: 859 <pre> 860 @UiThreadTest 861 public void testStatePause() { 862 </pre> 863 <p> 864 The <code>@UiThreadTest</code> annotation tells Android to build this method so that it runs 865 on the UI thread. This allows the method to change the state of the spinner widget in the 866 application under test. This use of <code>@UiThreadTest</code> shows that, if necessary, you 867 can run an entire method on the UI thread. 868 </p> 869 </li> 870 <li> 871 Set up instrumentation. Get the instrumentation object 872 that is controlling the application under test. This is used later to 873 invoke the <code>onPause()</code> and <code>onResume()</code> methods: 874 <pre> 875 Instrumentation mInstr = this.getInstrumentation(); 876 </pre> 877 </li> 878 <li> 879 Set the spinner selection to a test value: 880 <pre> 881 mActivity.setSpinnerPosition(TEST_STATE_PAUSE_POSITION); 882 mActivity.setSpinnerSelection(TEST_STATE_PAUSE_SELECTION); 883 </pre> 884 </li> 885 <li> 886 Use instrumentation to call the Activity's <code>onPause()</code>: 887 <pre> 888 mInstr.callActivityOnPause(mActivity); 889 </pre> 890 <p> 891 Under test, the activity is waiting for input. The invocation of 892 {@link android.app.Instrumentation#callActivityOnPause(android.app.Activity)} 893 performs a call directly to the activity's <code>onPause()</code> instead 894 of manipulating the activity's UI to force it into a paused state. 895 </p> 896 </li> 897 <li> 898 Force the spinner to a different selection: 899 <pre> 900 mActivity.setSpinnerPosition(0); 901 mActivity.setSpinnerSelection(""); 902 </pre> 903 <p> 904 This ensures that resuming the activity actually restores the 905 spinner's state rather than simply leaving it as it was. 906 </p> 907 </li> 908 <li> 909 Use instrumentation to call the Activity's <code>onResume()</code>: 910 <pre> 911 mInstr.callActivityOnResume(mActivity); 912 </pre> 913 <p> 914 Invoking {@link android.app.Instrumentation#callActivityOnResume(android.app.Activity)} 915 affects the activity in a way similar to <code>callActivityOnPause</code>. The 916 activity's <code>onResume()</code> method is invoked instead of manipulating the 917 activity's UI to force it to resume. 918 </p> 919 </li> 920 <li> 921 Get the current state of the spinner: 922 <pre> 923 int currentPosition = mActivity.getSpinnerPosition(); 924 String currentSelection = mActivity.getSpinnerSelection(); 925 </pre> 926 </li> 927 <li> 928 Test the current spinner state against the test values: 929 <pre> 930 assertEquals(TEST_STATE_PAUSE_POSITION,currentPosition); 931 assertEquals(TEST_STATE_PAUSE_SELECTION,currentSelection); 932 } // end of testStatePause() method definition 933 </pre> 934 <p> 935 Add the following members to the test case class: 936 </p> 937 <pre> 938 public static final int TEST_STATE_PAUSE_POSITION = 4; 939 public static final String TEST_STATE_PAUSE_SELECTION = "Jupiter"; 940 </pre> 941 </li> 942 <li> 943 Add the following imports: 944 <pre> 945 import android.app.Instrumentation; 946 import android.test.UiThreadTest; 947 </pre> 948 </li> 949 </ol> 950 <h2 id="RunTests">Running the Tests and Seeing the Results</h2> 951 <p> 952 The most simple way to run the <code>SpinnerActivityTest</code> test case is to run it directly from the Package Explorer. 953 </p> 954 <p> 955 To run the <code>SpinnerActivityTest</code> test, follow these steps: 956 </p> 957 <ol> 958 <li> 959 In the Package Explorer, right-click the project SpinnerActivityTest at the top level, and then 960 select <strong>Run As</strong> > <strong>Android JUnit Test</strong>:<br/> 961 <a href="{@docRoot}images/testing/spinnertest_runas_menu_callouts.png"> 962 <img alt="Menu to run a test as an Android JUnit test" src="{@docRoot}images/testing/spinnertest_runas_menu_callouts.png" style="height:230px"> 963 </a> 964 </li> 965 <li> 966 You will see the emulator start. When the unlock option is displayed (its appearance depends on the API level you specified for the AVD), 967 unlock the home screen. 968 </li> 969 <li> 970 The test application starts. You see a new tab for the <strong>JUnit</strong> view, next to the Package Explorer tab:<br/> 971 <a href="{@docRoot}images/testing/spinnertest_junit_panel.png"> 972 <img alt="The JUnit window" src="{@docRoot}images/testing/spinnertest_junit_panel.png" style="height:230px"> 973 </a> 974 </li> 975 </ol> 976 <p> 977 This view contains two sub-panes. The top pane summarizes the tests that were run, and the bottom pane shows failure traces for 978 highlighted tests. 979 </p> 980 <p> 981 At the conclusion of a successful test run, this is the view's appearance:<br/> 982 <a href="{@docRoot}images/testing/spinnertest_junit_success.png"> 983 <img src="{@docRoot}images/testing/spinnertest_junit_success.png" alt="JUnit test run success" style="height:230px"/> 984 </a> 985 </p> 986 <p> 987 The upper pane summarizes the test: 988 </p> 989 <ul> 990 <li> 991 Total time elapsed for the test application(labeled <em>Finished after <x> seconds</em>). 992 </li> 993 <li> 994 Number of runs (<em>Runs:</em>) - the number of tests in the entire test class. 995 </li> 996 <li> 997 Number of errors (<em>Errors:</em>) - the number of program errors and exceptions encountered during 998 the test run. 999 </li> 1000 <li> 1001 Number of failures (<em>Failures:</em>) - the number of test failures encountered during the test 1002 run. This is the number of assertion failures. A test can fail even if the program does not encounter an error. 1003 </li> 1004 <li> 1005 A progress bar. The progress bar extends from left to right as the tests run. 1006 <p> 1007 If all the tests succeed, the bar remains green. If a test fails, the bar turns from green to red. 1008 </p> 1009 </li> 1010 <li> 1011 A test method summary. Below the bar, you see a line for each class in the test application. To look at the results for the individual 1012 methods in a test, click the arrow at the left to expand the line. You see the name of each test method. To the 1013 right of the name, you see the time taken by the test. You can look at the test's code 1014 by double-clicking its name. 1015 </li> 1016 </ul> 1017 <p> 1018 The lower pane contains the failure trace. If all the tests are successful, this pane is empty. If some tests fail, 1019 then if you highlight a failed test in the upper pane, the lower view contains a stack trace for the test. This is 1020 demonstrated in the next section. 1021 </p> 1022 <p class="note"> 1023 <strong>Note:</strong> If you run the test application and nothing seems to happen, look for 1024 the JUnit view. If you do not see it, you may have run the test application 1025 as a regular Android application. 1026 Remember that you need to run it as an Android <strong>JUnit</strong> 1027 application. 1028 </p> 1029 <h2 id="TestFailure">Forcing Some Tests to Fail</h2> 1030 <p> 1031 A test is as useful when it fails as when it succeeds. This section shows what happens in Eclipse with ADT when a test fails. You 1032 can quickly see that a test class has failed, find the method or methods that failed, and then use a failure trace to find 1033 the exact problem. 1034 </p> 1035 <p> 1036 The example application SpinnerActivity that you downloaded passes all the tests in the test application SpinnerActivityTest. 1037 To force the test to fail, you must modify the example application. You change a line of setup code in the application under test. This 1038 causes the <code>testPreConditions()</code> and <code>testTextView()</code> test methods to fail. 1039 </p> 1040 <p> 1041 To force the tests to fail, follow these steps: 1042 </p> 1043 <ol> 1044 <li> 1045 In Eclipse with ADT, go to the SpinnerActivity project and open the file <code>SpinnerActivity.java</code>. 1046 </li> 1047 <li> 1048 At the top of <code>SpinnerActivity.java</code>, at the end of the <code>onCreate()</code> method, find the following line: 1049 <pre> 1050 // mySpinner.setOnItemSelectedListener(null); 1051 </pre> 1052 <p>Remove the forward slash characters at the beginning of the line to 1053 uncomment the line. This sets the listener callback to null: 1054 </p> 1055 <pre> 1056 mySpinner.setOnItemSelectedListener(null); 1057 </pre> 1058 </li> 1059 <li> 1060 The <code>testPreConditions()</code> method in <code>SpinnerActivityTest</code> contains the following test: 1061 <code>assertTrue(mSpinner.getOnItemSelectedListener() != null);</code>. This test asserts that the listener callback is <em>not</em> null. 1062 Since you have modified the application under test, this assertion now fails. 1063 </li> 1064 <li> 1065 Run the test, as described in the previous section <a href="#RunTests">Running the Tests and Seeing the Results</a>. 1066 </li> 1067 </ol> 1068 <p> 1069 The JUnit view is either created or updated with the results of the test. Now, however, the progress bar is red, 1070 the number of failures is 2, and small "x" icons appear in the list icons next to the testPreConditions and 1071 TestSpinnerUI tests. This indicates that the tests have failed. The display is similar to this:<br/> 1072 <a href="{@docRoot}images/testing/spinnertest_junit_panel_fail_callouts.png"> 1073 <img src="{@docRoot}images/testing/spinnertest_junit_panel_fail_callouts.png" alt="The JUnit Failure window" style="height:230px"/> 1074 </a> 1075 </p> 1076 <p> 1077 You now want to look at the failures to see exactly where they occurred. 1078 </p> 1079 <p> 1080 To examine the failures, follow these steps: 1081 </p> 1082 <ol> 1083 <li> 1084 Click the testPreconditions entry. In the lower pane entitled <strong>Failure Trace</strong>, 1085 you see a stack trace of the calls that led to the failure. This trace is similar to the following screenshot:<br/> 1086 <a href="{@docRoot}images/testing/spinnertest_junit_panel_failtrace_callouts.png"> 1087 <img src="{@docRoot}images/testing/spinnertest_junit_panel_failtrace_callouts.png" alt="The JUnit failure trace" style="height:230px"/> 1088 </a> 1089 </li> 1090 <li> 1091 The first line of the trace tells you the error. In this case, a JUnit assertion failed. To look at the 1092 assertion in the test code, double-click the next line (the first line of the trace). In the center pane 1093 a new tabbed window opens, containing the code for the test application <code>SpinnerActivityTest</code>. The failed assertion 1094 is highlighted in the middle of the window. 1095 </li> 1096 </ol> 1097 <p> 1098 The assertion failed because you modified the main application to set the <code>getOnItemSelectedListener</code> callback to <code>null</code>. 1099 </p> 1100 <p> 1101 You can look at the failure in <code>testTextView</code> if you want. Remember, though, that <code>testPreConditions</code> is meant to verify the 1102 initial setup of the application under test. If testPreConditions() fails, then succeeding tests can't be trusted. The best strategy to follow is to 1103 fix the problem and re-run all the tests. 1104 </p> 1105 <p> 1106 Remember to go back to <code>SpinnerActivity.java</code> and re-comment the line you uncommented in an earlier step. 1107 </p> 1108 <p> 1109 You have now completed the tutorial. 1110 </p> 1111 <h2 id="NextSteps">Next Steps</h2> 1112 <p> 1113 This example test application has shown you how to create a test project and link it to 1114 the application you want to test, how to choose and add a test case class, how to write 1115 UI and state management tests, and how to run the tests against the application under 1116 test. Now that you are familiar with the basics of testing Android applications, here 1117 are some suggested next steps: 1118 </p> 1119 <p> 1120 <strong>Learn more about testing on Android</strong> 1121 </p> 1122 <ul> 1123 <li> 1124 If you haven't done so already, read the 1125 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> 1126 document in the <em>Dev Guide</em>. It provides an overview of how testing on Android 1127 works. If you are just getting started with Android testing, reading that document will 1128 help you understand the tools available to you, so that you can develop effective 1129 tests. 1130 </li> 1131 </ul> 1132 <p> 1133 <strong>Review the main Android test case classes</strong> 1134 </p> 1135 <ul> 1136 <li> 1137 {@link android.test.ActivityInstrumentationTestCase2} 1138 </li> 1139 <li> 1140 {@link android.test.ActivityUnitTestCase} 1141 </li> 1142 <li> 1143 {@link android.test.ProviderTestCase2} 1144 </li> 1145 <li> 1146 {@link android.test.ServiceTestCase} 1147 </li> 1148 </ul> 1149 <p> 1150 <strong>Learn more about the assert and utility classes</strong> 1151 </p> 1152 <ul> 1153 <li> 1154 {@link junit.framework.Assert}, the JUnit Assert class. 1155 </li> 1156 <li> 1157 {@link android.test.MoreAsserts}, additional Android assert methods. 1158 </li> 1159 <li> 1160 {@link android.test.ViewAsserts}, useful assertion methods for testing Views. 1161 </li> 1162 <li> 1163 {@link android.test.TouchUtils}, utility methods for simulating touch events in an Activity. 1164 </li> 1165 </ul> 1166 <p> 1167 <strong>Learn about instrumentation and the instrumented test runner</strong> 1168 </p> 1169 <ul> 1170 <li> 1171 {@link android.app.Instrumentation}, the base instrumentation class. 1172 </li> 1173 <li> 1174 {@link android.test.InstrumentationTestCase}, the base instrumentation test case. 1175 </li> 1176 <li> 1177 {@link android.test.InstrumentationTestRunner}, the standard Android test runner. 1178 </li> 1179 </ul> 1180 <h2 id="Appendix">Appendix</h2> 1181 <h3 id="InstallCompletedTestApp">Installing the Completed Test Application Java File</h3> 1182 <p> 1183 The recommended approach to this tutorial is to follow the instructions step-by-step and 1184 write the test code as you go. However, if you want to do this tutorial quickly, 1185 you can install the entire Java file for the test application into the test project. 1186 </p> 1187 <p> 1188 To do this, you first create a test project with the necessary structure and files by using 1189 the automated tools in Eclipse. Then you exit Eclipse and copy the test application's Java file 1190 from the SpinnerTest sample project into your test project. The SpinnerTest sample project is 1191 part of the Samples component of the SDK. 1192 </p> 1193 <p> 1194 The result is a complete test application, ready to run against the Spinner sample application. 1195 </p> 1196 <p> 1197 To install the test application Java file, follow these steps: 1198 </p> 1199 <ol> 1200 <li> 1201 Set up the projects for the application under test and the test application, as described 1202 in the section section <a href="#SetupProjects">Setting Up the Projects</a>. 1203 </li> 1204 <li> 1205 Set up the emulator, as described in the section <a href="#SetupEmulator">Setting Up the Emulator</a>. 1206 </li> 1207 <li> 1208 Add the test case class, as described in the section <a href="#AddTestCaseClass">Adding the test case class file</a>. 1209 </li> 1210 <li> 1211 Close Eclipse with ADT. 1212 </li> 1213 <li> 1214 Copy the file <code><SDK_path>/samples/android-8/SpinnerTest/src/com/android/example/spinner/test/SpinnerActivityTest.java</code> 1215 to the directory <code>workspace/SpinnerActivityTest/src/com/android/example/spinner/test/</code>. 1216 </li> 1217 <li> 1218 Restart Eclipse with ADT. 1219 </li> 1220 <li> 1221 In Eclipse with ADT, re-build the project <code>SpinnerActivityTest</code> by selecting it in the Package Explorer, right-clicking, 1222 and selecting <em>Project</em> > <em>Clean</em>. 1223 </li> 1224 <li> 1225 The complete, working test application should now be in the <code>SpinnerActivityTest</code> project. 1226 </li> 1227 </ol> 1228 <p> 1229 You can now continue with the tutorial, starting at the section <a href="#AddConstructor">Adding the test case constructor</a> and 1230 following along in the text. 1231 </p> 1232 <h3 id="EditorCommandLine">For Users Not Developing In Eclipse</h3> 1233 <p> 1234 If you are not developing in Eclipse, you can still do this tutorial. Android provides tools for 1235 creating test applications using a code editor and command-line tools. You use the following tools: 1236 </p> 1237 <ul> 1238 <li> 1239 <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> - Installs and uninstalls applications and test applications to a device or the emulator. You 1240 also use this tool to run the test application from the command line. 1241 </li> 1242 <li> 1243 <a href="{@docRoot}guide/developing/tools/android.html">android</a> - Manages projects and test projects. This tool also manages AVDs and Android platforms. 1244 </li> 1245 </ul> 1246 <p> 1247 You use the <code>emulator</code> tool to run the emulator from the command line. 1248 </p> 1249 <p> 1250 Here are the general steps for doing this tutorial using an editor and the command line: 1251 </p> 1252 <ol> 1253 <li> 1254 As described in the section <a href="#DownloadCode">Installing the Tutorial Sample Code</a>, get the sample code. You will then 1255 have a directory <code><SDK_path>/samples/android-8</code>, containing (among others) the directories <code>Spinner</code> 1256 and <code>SpinnerTest</code>: 1257 <ul> 1258 <li> 1259 <code>Spinner</code> contains the main application, also known as the <strong>application under test</strong>. This tutorial focuses on the 1260 common situation of writing tests for an application that already exists, so the main application is provided to you. 1261 </li> 1262 <li> 1263 <code>SpinnerTest</code> contains all the code for the test application. If you want to run quickly through the tutorial, you can 1264 install the test code and then follow the text. You may get more from the tutorial, however, if you write the code as you go. The instructions 1265 for installing the test code are in the section <a href="#InstallCompletedTestApp">Appendix: Installing the Completed Test Application</a>. 1266 </li> 1267 </ul> 1268 </li> 1269 <li> 1270 Navigate to the directory <code><SDK_path>/samples/android-8</code>. 1271 </li> 1272 <li> 1273 Create a new Android application project using <code>android create project</code>: 1274 <pre> 1275 $ android create project -t <APItarget> -k com.android.example.spinner -a SpinnerActivity -n SpinnerActivity -p Spinner 1276 </pre> 1277 <p> 1278 The value of <code><APItarget></code> should be "3" (API level 3) or higher. If you are already developing with a particular API level, and it is 1279 higher than 3, then use that API level. 1280 </p> 1281 <p> 1282 This a new Android project <code>SpinnerActivity</code> in the existing <code>Spinner</code> directory. The existing source and 1283 resource files are not touched, but the <code>android</code> tool adds the necessary build files. 1284 </p> 1285 </li> 1286 <li> 1287 Create a new Android test project using <code>android create test-project</code>: 1288 <pre> 1289 $ android create test-project -m ../Spinner -n SpinnerActivityTest -p SpinnerActivityTest 1290 </pre> 1291 <p> 1292 This will create a new Android test project in the <em>new</em> directory <code>SpinnerActivityTest</code>. You do this 1293 so that the solution to the tutorial that is in <code>SpinnerTest</code> is left untouched. If you want to use the solution 1294 code instead of entering it as you read through the tutorial, refer to the section 1295 <a href="#InstallCompletedTestApp">Appendix: Installing the Completed Test Application</a>. 1296 </p> 1297 <p class="Note"> 1298 <strong>Note:</strong> Running <code>android create test-project</code> will automatically create 1299 the file <code>AndroidManifest.xml</code> with the correct <code><instrumentation></code> element. 1300 </p> 1301 </li> 1302 <li> 1303 Build the sample application. If you are building with Ant, then it is easiest to use the command <code>ant debug</code> to build a debug version, since the SDK comes 1304 with a debug signing key. The result will be the file <code>Spinner/bin/SpinnerActivity-debug.apk</code>. 1305 You can install this to your device or emulator. Attach your device or start the emulator if you haven't already, and run the command: 1306 <pre> 1307 $ adb install Spinner/bin/SpinnerActivity-debug.apk 1308 </pre> 1309 </li> 1310 <li> 1311 To create the test application, create a file <code>SpinnerActivityTest.java</code> in the directory 1312 <code>SpinnerActivityTest/src/com/android/example/spinner/test/</code>. 1313 </li> 1314 <li> 1315 Follow the tutorial, starting with the section <a href="#CreateTestCaseClass">Creating the Test Case Class</a>. When you are prompted to 1316 run the sample application, go the the Launcher screen in your device or emulator and select SpinnerActivity. 1317 When you are prompted to run the test application, return here to continue with the following instructions. 1318 </li> 1319 <li> 1320 Build the test application. If you are building with Ant, then it is easiest to use the command <code>ant debug</code> to build a 1321 debug version, since the SDK comes with a debug signing key. The result will be the Android file 1322 <code>SpinnerActivityTest/bin/SpinnerActivityTest-debug.apk</code>. You can install this to your device or emulator. 1323 Attach your device or start the emulator if you haven't already, and run the command: 1324 <pre> 1325 $ adb install SpinnerActivityTest/bin/SpinnerActivityTest-debug.apk 1326 </pre> 1327 </li> 1328 <li> 1329 In your device or emulator, check that both the main application <code>SpinnerActivity</code> and the test application 1330 <code>SpinnerActivityTest</code> are installed. 1331 </li> 1332 <li> 1333 To run the test application, enter the following at the command line: 1334 <pre> 1335 $ adb shell am instrument -w com.android.example.spinner.test/android.test.InstrumentationTestRunner 1336 </pre> 1337 </li> 1338 </ol> 1339 <p> 1340 The result of a successful test looks like this: 1341 </p> 1342 <pre> 1343 com.android.example.spinner.test.SpinnerActivityTest:.... 1344 Test results for InstrumentationTestRunner=.... 1345 Time: 10.098 1346 OK (4 tests) 1347 </pre> 1348 <p> 1349 If you force the test to fail, as described in the previous section <a href="#TestFailure">Forcing Some Tests to Fail</a>, then 1350 the output looks like this: 1351 </p> 1352 <pre> 1353 com.android.example.spinner.test.SpinnerActivityTest: 1354 Failure in testPreConditions: 1355 junit.framework.AssertionFailedError 1356 at com.android.example.spinner.test.SpinnerActivityTest.testPreConditions(SpinnerActivityTest.java:104) 1357 at java.lang.reflect.Method.invokeNative(Native Method) 1358 at android.test.InstrumentationTestCase.runMethod(InstrumentationTestCase.java:205) 1359 at android.test.InstrumentationTestCase.runTest(InstrumentationTestCase.java:195) 1360 at android.test.ActivityInstrumentationTestCase2.runTest(ActivityInstrumentationTestCase2.java:175) 1361 at android.test.AndroidTestRunner.runTest(AndroidTestRunner.java:169) 1362 at android.test.AndroidTestRunner.runTest(AndroidTestRunner.java:154) 1363 at android.test.InstrumentationTestRunner.onStart(InstrumentationTestRunner.java:430) 1364 at android.app.Instrumentation$InstrumentationThread.run(Instrumentation.java:1447) 1365 Failure in testSpinnerUI: 1366 junit.framework.ComparisonFailure: expected:<Result> but was:<Saturn> 1367 at com.android.example.spinner.test.SpinnerActivityTest.testSpinnerUI(SpinnerActivityTest.java:153) 1368 at java.lang.reflect.Method.invokeNative(Native Method) 1369 at android.test.InstrumentationTestCase.runMethod(InstrumentationTestCase.java:205) 1370 at android.test.InstrumentationTestCase.runTest(InstrumentationTestCase.java:195) 1371 at android.test.ActivityInstrumentationTestCase2.runTest(ActivityInstrumentationTestCase2.java:175) 1372 at android.test.AndroidTestRunner.runTest(AndroidTestRunner.java:169) 1373 at android.test.AndroidTestRunner.runTest(AndroidTestRunner.java:154) 1374 at android.test.InstrumentationTestRunner.onStart(InstrumentationTestRunner.java:430) 1375 at android.app.Instrumentation$InstrumentationThread.run(Instrumentation.java:1447) 1376 .. 1377 Test results for InstrumentationTestRunner=.F.F.. 1378 Time: 9.377 1379 FAILURES!!! 1380 Tests run: 4, Failures: 2, Errors: 0 1381 </pre> 1382
