1page.title=Testing from Eclipse with ADT 2parent.title=Testing 3parent.link=index.html 4@jd:body 5<div id="qv-wrapper"> 6 <div id="qv"> 7 <h2>In this document</h2> 8 <ol> 9 <li><a href="#CreateTestProjectEclipse">Creating a Test Project</a></li> 10 <li><a href="#CreateTestAppEclipse">Creating a Test Package</a></li> 11 <li><a href="#RunTestEclipse">Running Tests</a></li> 12 </ol> 13 </div> 14</div> 15<p> 16 This topic explains how create and run tests of Android applications in Eclipse with ADT. 17 Before you read this topic, you should read about how to create an Android application with the 18 basic processes for creating and running applications with ADT, as described in 19 <a href="{@docRoot}tools/projects/projects-eclipse.html">Managing Projects from 20Eclipse</a> 21 and <a href="{@docRoot}tools/building/building-eclipse.html">Building and Running 22from Eclipse</a>. 23 You may also want to read 24 <a href="{@docRoot}tools/testing/testing_android.html">Testing Fundamentals</a>, 25 which provides an overview of the Android testing framework. 26</p> 27<p> 28 ADT provides several features that help you set up and manage your testing environment 29 effectively: 30</p> 31 <ul> 32 <li> 33 It lets you quickly create a test project and link it to the application under test. 34 When it creates the test project, it automatically inserts the necessary 35 <code><instrumentation></code> element in the test package's manifest file. 36 </li> 37 <li> 38 It lets you quickly import the classes of the application under test, so that your 39 tests can inspect them. 40 </li> 41 <li> 42 It lets you create run configurations for your test package and include in 43 them flags that are passed to the Android testing framework. 44 </li> 45 <li> 46 It lets you run your test package without leaving Eclipse. ADT builds both the 47 application under test and the test package automatically, installs them if 48 necessary to your device or emulator, runs the test package, and displays the 49 results in a separate window in Eclipse. 50 </li> 51 </ul> 52<p> 53 If you are not developing in Eclipse or you want to learn how to create and run tests from the 54 command line, see 55 <a href="{@docRoot}tools/testing/testing_otheride.html">Testing from Other IDEs</a>. 56</p> 57<h2 id="CreateTestProjectEclipse">Creating a Test Project</h2> 58<p> 59 To set up a test environment for your Android application, you must first create a separate 60 project that holds the test code. The new project follows the directory structure 61 used for any Android application. It includes the same types of content and files, such as 62 source code, resources, a manifest file, and so forth. The test package you 63 create is connected to the application under test by an 64 <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"> 65 <code><instrumentation></code></a> element in its manifest file. 66</p> 67<p> 68 The <em>New Android Test Project</em> dialog makes it easy for you to generate a 69 new test project that has the proper structure, including the 70 <code><instrumentation></code> element in the manifest file. You can use the New 71 Android Test Project dialog to generate the test project at any time. The dialog appears 72 just after you create a new Android main application project, but you can also run it to 73 create a test project for a project that you created previously. 74</p> 75<p> 76 To create a test project in Eclipse with ADT: 77</p> 78<ol> 79 <li> 80 In Eclipse, select <strong>File > New > Other</strong>. This opens the <em>Select a 81 Wizard</em> dialog. 82 </li> 83 <li> 84 In the dialog, in the <em>Wizards</em> drop-down list, find the entry for Android, then 85 click the toggle to the left. Select <strong>Android Test Project</strong>, then at the 86 bottom of the dialog click <strong>Next</strong>. The <em>New Android Test Project</em> 87 wizard appears. 88 </li> 89 <li> 90 Next to <em>Test Project Name</em>, enter a name for the project. You may use any name, 91 but you may want to associate the name with the project name for the application under test. 92 One way to do this is to take the application's project name, append the string "Test" to 93 it, and then use this as the test package project name. 94 <p> 95 The name becomes part of the suggested project path, but you can change this in the 96 next step. 97 </p> 98 </li> 99 <li> 100 In the <em>Content</em> panel, examine the suggested path to the project. 101 If <em>Use default location</em> is set, then the wizard will suggest a path that is 102 a concatenation of the workspace path and the project name you entered. For example, 103 if your workspace path is <code>/usr/local/workspace</code> and your project name is 104 <code>MyTestApp</code>, then the wizard will suggest 105 <code>/usr/local/workspace/MyTestApp</code>. To enter your own 106 choice for a path, unselect <em>Use default location</em>, then enter or browse to the 107 path where you want your project. 108 <p> 109 To learn more about choosing the location of test projects, please read 110 <a href="{@docRoot}tools/testing/testing_android.html#TestProjectPaths"> 111 Testing Fundamentals</a>. 112 </p> 113 </li> 114 <li> 115 In the Test Target panel, set An Existing Android Project, click Browse, then select your 116 Android application from the list. You now see that the wizard has completed the Test 117 Target Package, Application Name, and Package Name fields for you (the latter two are in 118 the Properties panel). 119 </li> 120 <li> 121 In the Build Target panel, select the Android SDK platform that the application under test 122 uses. 123 </li> 124 <li> 125 Click Finish to complete the wizard. If Finish is disabled, look for error messages at the 126 top of the wizard dialog, and then fix any problems. 127 </li> 128</ol> 129<h2 id="CreateTestAppEclipse">Creating a Test Package</h2> 130<p> 131 Once you have created a test project, you populate it with a test package. This package does not 132 require an Activity, although you can define one if you wish. Although your test package can 133 combine Activity classes, test case classes, or ordinary classes, your main test case 134 should extend one of the Android test case classes or JUnit classes, because these provide the 135 best testing features. 136</p> 137<p> 138 Test packages do not need to have an Android GUI. When you run the package in 139 Eclipse with ADT, its results appear in the JUnit view. Running tests and seeing the results is 140 described in more detail in the section <a href="#RunTestEclipse">Running Tests</a>. 141</p> 142 143<p> 144 To create a test package, start with one of Android's test case classes defined in 145 {@link android.test android.test}. These extend the JUnit 146 {@link junit.framework.TestCase TestCase} class. The Android test classes for Activity objects 147 also provide instrumentation for testing an Activity. To learn more about test case 148 classes, please read the topic <a href="{@docRoot}tools/testing/testing_android.html"> 149 Testing Fundamentals</a>. 150</p> 151<p> 152 Before you create your test package, you choose the Java package identifier you want to use 153 for your test case classes and the Android package name you want to use. To learn more 154 about this, please read 155 <a href="{@docRoot}tools/testing/testing_android.html#PackageNames"> 156 Testing Fundamentals</a>. 157</p> 158<p> 159 To add a test case class to your project: 160</p> 161<ol> 162 <li> 163 In the <em>Project Explorer</em> tab, open your test project, then open the <em>src</em> 164 folder. 165 </li> 166 <li> 167 Find the Java package identifier set by the projection creation wizard. If you haven't 168 added classes yet, this node won't have any children, and its icon will not be filled in. 169 If you want to change the identifier value, right-click the identifier and select 170 <strong>Refactor</strong> > <strong>Rename</strong>, then enter the new name. 171 </li> 172 <li> 173 When you are ready, right-click the Java package identifier again and select 174 <strong>New</strong> > <strong>Class</strong>. This displays the <em>New Java Class</em> 175 dialog, with the <em>Source folder</em> and <em>Package</em> values already set. 176 </li> 177 <li> 178 In the <em>Name</em> field, enter a name for the test case class. One way to choose a 179 class name is to append the string "Test" to the class of the component you are testing. 180 For example, if you are testing the class MyAppActivity, your test case class 181 name would be MyAppActivityTest. Leave the modifiers set to <em>public</em>. 182 </li> 183 <li> 184 In the <em>Superclass</em> field, enter the name of the Android test case class you 185 are extending. You can also browse the available classes. 186 </li> 187 <li> 188 In <em>Which method stubs would you like to create?</em>, unset all the options, then 189 click <strong>Finish</strong>. You will set up the constructor manually. 190 </li> 191 <li> 192 Your new class appears in a new Java editor pane. 193 </li> 194</ol> 195<p> 196 You now have to ensure that the constructor is set up correctly. Create a constructor for your 197 class that has no arguments; this is required by JUnit. As the first statement in this 198 constructor, add a call to the base class' constructor. Each base test case class has its 199 own constructor signature. Refer to the class documentation in the documentation for 200 {@link android.test} for more information. 201</p> 202<p> 203 To control your test environment, you will want to override the <code>setUp()</code> and 204 <code>tearDown()</code> methods: 205</p> 206<ul> 207 <li> 208 <code>setUp()</code>: This method is invoked before any of the test methods in the class. 209 Use it to set up the environment for the test (the test fixture. You can use 210 <code>setUp()</code> to instantiate a new Intent with the action <code>ACTION_MAIN</code>. 211 You can then use this intent to start the Activity under test. 212 </li> 213 <li> 214 <code>tearDown()</code>: This method is invoked after all the test methods in the class. Use 215 it to do garbage collection and to reset the test fixture. 216 </li> 217</ul> 218<p> 219 Another useful convention is to add the method <code>testPreconditions()</code> to your test 220 class. Use this method to test that the application under test is initialized correctly. If this 221 test fails, you know that the initial conditions were in error. When this happens, further 222 test results are suspect, regardless of whether or not the tests succeeded. 223</p> 224<p> 225 The Resources tab contains an 226 <a href="{@docRoot}tools/testing/activity_test.html">Activity Testing</a> 227 tutorial with more information about creating test classes and methods. 228</p> 229<h2 id="RunTestEclipse">Running Tests</h2> 230 <div class="sidebox-wrapper"> 231 <div class="sidebox"> 232 <h2>Running tests from the command line</h2> 233 <p> 234 If you've created your tests in Eclipse, you can still run your tests and test 235 suites by using command-line tools included with the Android SDK. You may want 236 to do this, for example, if you have a large number of tests to run, if you 237 have a large test case, or if you want a fine level of control over which 238 tests are run at a particular time. 239 </p> 240 <p> 241 To run tests created in Eclipse with ADT with command-line tools, you must first 242 install additional files into the test project using the <code>android</code> 243 tool's "create test-project" option. To see how to do this, read 244 <a href="{@docRoot}tools/testing/testing_otheride.html#CreateProject"> 245 Testing in Other IDEs</a>. 246 </p> 247 </div> 248 </div> 249<p> 250 When you run a test package in Eclipse with ADT, the output appears in the Eclipse JUnit view. 251 You can run the entire test package or one test case class. To do run tests, Eclipse runs the 252 <code>adb</code> command for running a test package, and displays the output, so there is no 253 difference between running tests inside Eclipse and running them from the command line. 254</p> 255<p> 256 As with any other package, to run a test package in Eclipse with ADT you must either attach a 257 device to your computer or use the Android emulator. If you use the emulator, you must have an 258 Android Virtual Device (AVD) that uses the same target as the test package. 259</p> 260<p> 261 To run a test in Eclipse, you have two choices:</p> 262<ul> 263 <li> 264 Run a test just as you run an application, by selecting 265 <strong>Run As... > Android JUnit Test</strong> from the project's context menu or 266 from the main menu's <strong>Run</strong> item. 267 </li> 268 <li> 269 Create an Eclipse run configuration for your test project. This is useful if you want 270 multiple test suites, each consisting of selected tests from the project. To run 271 a test suite, you run the test configuration. 272 <p> 273 Creating and running test configurations is described in the next section. 274 </p> 275 </li> 276</ul> 277<p> 278 To create and run a test suite using a run configuration: 279</p> 280<ol> 281 <li> 282 In the Package Explorer, select the test project, then from the main menu, select 283 <strong>Run > Run Configurations...</strong>. The Run Configurations dialog appears. 284 </li> 285 <li> 286 In the left-hand pane, find the Android JUnit Test entry. In the right-hand pane, click the 287 Test tab. The Name: text box shows the name of your project. The Test class: dropdown box 288 shows one of the test classes in your project. 289 </li> 290 <li> 291 To run one test class, click Run a single test, then enter your project name in the 292 Project: text box and the class name in the Test class: text box. 293 <p> 294 To run all the test classes, click Run all tests in the selected project or package, 295 then enter the project or package name in the text box. 296 </p> 297 </li> 298 <li> 299 Now click the Target tab. 300 <ul> 301 <li> 302 Optional: If you are using the emulator, click Automatic, then in the Android 303 Virtual Device (AVD) selection table, select an existing AVD. 304 </li> 305 <li> 306 In the Emulator Launch Parameters pane, set the Android emulator flags you want to 307 use. These are documented in the topic 308 <a href="{@docRoot}tools/help/emulator.html#startup-options"> 309 Android Emulator</a>. 310 </li> 311 </ul> 312 </li> 313 <li> 314 Click the Common tab. In the Save As pane, click Local to save this run configuration 315 locally, or click Shared to save it to another project. 316 </li> 317 <li> 318 Optional: Add the configuration to the Run toolbar and the <strong>Favorites</strong> 319 menu: in the Display in Favorites pane click the checkbox next to Run. 320 </li> 321 <li> 322 Optional: To add this configuration to the <strong>Debug</strong> menu and toolbar, click 323 the checkbox next to Debug. 324 </li> 325 <li> 326 To save your settings, click Close.<br/> 327 <p class="note"><strong>Note:</strong> 328 Although you can run the test immediately by clicking Run, you should save the test 329 first and then run it by selecting it from the Eclipse standard toolbar. 330 </p> 331 </li> 332 <li> 333 On the Eclipse standard toolbar, click the down arrow next to the green Run arrow. This 334 displays a menu of saved Run and Debug configurations. 335 </li> 336 <li> 337 Select the test run configuration you just created. The test starts. 338 </li> 339</ol> 340<p> 341 The progress of your test appears in the Console view as a series of messages. Each message is 342 preceded by a timestamp and the <code>.apk</code> filename to which it applies. For example, 343 this message appears when you run a test to the emulator, and the emulator is not yet started: 344</p> 345<div class="sidebox-wrapper"> 346 <div class="sidebox"> 347 <h2>Message Examples</h2> 348 <p> 349 The examples shown in this section come from the 350 <a href="{@docRoot}resources/samples/SpinnerTest/index.html">SpinnerTest</a> 351 sample test package, which tests the 352 <a href="{@docRoot}resources/samples/Spinner/index.html">Spinner</a> 353 sample application. This test package is also featured in the 354 <a href="{@docRoot}tools/testing/activity_test.html">Activity Testing</a> 355 tutorial. 356 </p> 357 </div> 358</div> 359<pre> 360 [<em>yyyy-mm-dd hh:mm:ss</em> - <em>testfile</em>] Waiting for HOME ('android.process.acore') to be launched... 361</pre> 362<p> 363 In the following description of these messages, <code><em>devicename</em></code> is the name of 364 the device or emulator you are using to run the test, and <code><em>port</em></code> is the 365 port number for the device. The name and port number are in the format used by the 366 <code><a href="{@docRoot}tools/help/adb.html#devicestatus">adb devices</a></code> 367 command. Also, <code><em>testfile</em></code> is the <code>.apk</code> filename of the test 368 package you are running, and <em>appfile</em> is the filename of the application under test. 369</p> 370<ul> 371 <li> 372 If you are using an emulator and you have not yet started it, then Eclipse 373 first starts the emulator. When this is complete, you see 374 the message: 375 <p> 376 <code>HOME is up on device '<em>devicename</em>-<em>port</em>'</code> 377 </p> 378 </li> 379 <li> 380 If you have not already installed your test package, then you see 381 the message: 382 <p> 383 <code>Uploading <em>testfile</em> onto device '<em>devicename</em>-<em>port</em>' 384 </code> 385 </p> 386 <p> 387 then the message <code>Installing <em>testfile</em></code>. 388 </p> 389 <p> 390 and finally the message <code>Success!</code> 391 </p> 392 </li> 393</ul> 394<p> 395 The following lines are an example of this message sequence: 396</p> 397<code> 398[2010-07-01 12:44:40 - MyTest] HOME is up on device 'emulator-5554'<br> 399[2010-07-01 12:44:40 - MyTest] Uploading MyTest.apk onto device 'emulator-5554'<br> 400[2010-07-01 12:44:40 - MyTest] Installing MyTest.apk...<br> 401[2010-07-01 12:44:49 - MyTest] Success!<br> 402</code> 403<br> 404<ul> 405 <li> 406 Next, if you have not yet installed the application under test to the device or 407 emulator, you see the message 408 <p> 409 <code>Project dependency found, installing: <em>appfile</em></code> 410 </p> 411 <p> 412 then the message <code>Uploading <em>appfile</em></code> onto device 413 '<em>devicename</em>-<em>port</em>' 414 </p> 415 <p> 416 then the message <code>Installing <em>appfile</em></code> 417 </p> 418 <p> 419 and finally the message <code>Success!</code> 420 </p> 421 </li> 422</ul> 423<p> 424 The following lines are an example of this message sequence: 425</p> 426<code> 427[2010-07-01 12:44:49 - MyTest] Project dependency found, installing: MyApp<br> 428[2010-07-01 12:44:49 - MyApp] Uploading MyApp.apk onto device 'emulator-5554'<br> 429[2010-07-01 12:44:49 - MyApp] Installing MyApp.apk...<br> 430[2010-07-01 12:44:54 - MyApp] Success!<br> 431</code> 432<br> 433<ul> 434 <li> 435 Next, you see the message 436 <code>Launching instrumentation <em>instrumentation_class</em> on device 437 <em>devicename</em>-<em>port</em></code> 438 <p> 439 <code>instrumentation_class</code> is the fully-qualified class name of the 440 instrumentation test runner you have specified (usually 441 {@link android.test.InstrumentationTestRunner}. 442 </p> 443 </li> 444 <li> 445 Next, as {@link android.test.InstrumentationTestRunner} builds a list of tests to run, 446 you see the message 447 <p> 448 <code>Collecting test information</code> 449 </p> 450 <p> 451 followed by 452 </p> 453 <p> 454 <code>Sending test information to Eclipse</code> 455 </p> 456 </li> 457 <li> 458 Finally, you see the message <code>Running tests</code>, which indicates that your tests 459 are running. At this point, you should start seeing the test results in the JUnit view. 460 When the tests are finished, you see the console message <code>Test run complete</code>. 461 This indicates that your tests are finished. 462 </li> 463</ul> 464<p> 465 The following lines are an example of this message sequence: 466</p> 467<code> 468[2010-01-01 12:45:02 - MyTest] Launching instrumentation android.test.InstrumentationTestRunner on device emulator-5554<br> 469[2010-01-01 12:45:02 - MyTest] Collecting test information<br> 470[2010-01-01 12:45:02 - MyTest] Sending test information to Eclipse<br> 471[2010-01-01 12:45:02 - MyTest] Running tests...<br> 472[2010-01-01 12:45:22 - MyTest] Test run complete<br> 473</code> 474<br> 475<p> 476 The test results appear in the JUnit view. This is divided into an upper summary pane, 477 and a lower stack trace pane. 478</p> 479<p> 480 The upper pane contains test information. In the pane's header, you see the following 481 information: 482</p> 483<ul> 484 <li> 485 Total time elapsed for the test package (labeled Finished after <em>x</em> seconds). 486 </li> 487 <li> 488 Number of runs (Runs:) - the number of tests in the entire test class. 489 </li> 490 <li> 491 Number of errors (Errors:) - the number of program errors and exceptions encountered 492 during the test run. 493 </li> 494 <li> 495 Number of failures (Failures:) - the number of test failures encountered during the test 496 run. This is the number of assertion failures. A test can fail even if the program does 497 not encounter an error. 498 </li> 499 <li> 500 A progress bar. The progress bar extends from left to right as the tests run. If all the 501 tests succeed, the bar remains green. If a test fails, the bar turns from green to red. 502 </li> 503</ul> 504<p> 505 The body of the upper pane contains the details of the test run. For each test case class 506 that was run, you see a line with the class name. To look at the results for the individual 507 test methods in that class, you click the left arrow to expand the line. You now see a 508 line for each test method in the class, and to its right the time it took to run. 509 If you double-click the method name, Eclipse opens the test class source in an editor view 510 pane and moves the focus to the first line of the test method. 511</p> 512<p> 513 The results of a successful test are shown in figure 1. 514</p> 515<a href="{@docRoot}images/testing/eclipse_test_results.png"> 516 <img src="{@docRoot}images/testing/eclipse_test_results.png" 517 alt="Messages for a successful test" height="327px" id="TestResults"/> 518</a> 519<p class="img-caption"> 520 <strong>Figure 1.</strong> Messages for a successful test. 521</p> 522<p> 523 The lower pane is for stack traces. If you highlight a failed test in the upper pane, the 524 lower pane contains a stack trace for the test. If a line corresponds to a point in your 525 test code, you can double-click it to display the code in an editor view pane, with the 526 line highlighted. For a successful test, the lower pane is empty. 527</p> 528<p>The results of a failed test are shown in figure 2.</p> 529<a href="{@docRoot}images/testing/eclipse_test_run_failure.png"> 530 <img src="{@docRoot}images/testing/eclipse_test_run_failure.png" 531 alt="" height="372px" id="TestRun"/> 532</a> 533<p class="img-caption"> 534 <strong>Figure 2.</strong> Messages for a test failure. 535</p> 536
