1 page.title=Testing In Eclipse, with ADT 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>In this document</h2> 7 <ol> 8 <li><a href="#CreateTestProjectEclipse">Creating a Test Project</a></li> 9 <li><a href="#CreateTestAppEclipse">Creating a Test Application</a></li> 10 <li><a href="#RunTestEclipse">Running Tests</a></li> 11 </ol> 12 </div> 13 </div> 14 <p> 15 This topic explains how create and run tests of Android applications in Eclipse with ADT. 16 17 with the basic processes for creating and running applications with ADT, as described in 18 <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>. 19 20 Before you read this topic, you should read about how to create a Android application with the 21 basic processes for creating and running applications with ADT, as described in 22 <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>. 23 You may also want to read 24 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</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 application'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 application 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 application without leaving Eclipse. ADT builds both the 47 application under test and the test application automatically, installs them if 48 necessary to your device or emulator, runs the test application, 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}guide/developing/testing/testing_otheride.html">Testing in 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 application 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 application 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 <strong>New Android Test Project</strong> 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 Android 71 Test Project dialog to generate the test project at any time. The dialog appears just after you 72 create a new Android main application project, but you can also run it to create a test project 73 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 81 opens the Select a Wizard dialog. 82 </li> 83 <li> 84 In the dialog, in the Wizards drop-down list, 85 find the entry for Android, then click the toggle to the left. Select 86 Android Test Project, then at the bottom 87 of the dialog click Next. The New Android Test Project wizard appears. 88 </li> 89 <li> 90 Enter a project name. You may use any name, but you may want to 91 associate the name with the project name for your Application. One 92 way to do this is to take the Application's project name, append the 93 string "Test" to it, and then use this as the test case project name. 94 </li> 95 <li> 96 In the Test Target panel, set 97 An Existing Android Project, click 98 Browse, then select your Android application from 99 the list. You now see that the wizard has completed the Test 100 Target Package, Application Name, and 101 Package Name fields for you (the latter two are in 102 the Properties panel). 103 </li> 104 <li> 105 In the Build Target panel, select the Android SDK 106 platform that you will use to test your application. Make this the same as the 107 build target of the application under test. 108 </li> 109 <li> 110 Click Finish to complete the wizard. If 111 Finish is disabled, look 112 for error messages at the top of the wizard dialog, and then fix 113 any problems. 114 </li> 115 </ol> 116 <p> 117 118 </p> 119 <h2 id="CreateTestAppEclipse">Creating a Test Application</h2> 120 <p> 121 Once you have created a test project, you populate it with a test 122 Android application. This application does not require an {@link android.app.Activity Activity}, 123 although you can define one if you wish. Although your test application can 124 combine Activities, Android test class extensions, JUnit extensions, or 125 ordinary classes, you should extend one of the Android test classes or JUnit classes, 126 because these provide the best testing features. 127 </p> 128 <p> 129 Test applications do not have an Android GUI. Instead, when you run the application in 130 Eclipse with ADT, its results appear in the JUnit view. If you run 131 your tests with {@link android.test.InstrumentationTestRunner InstrumentationTestRunner} (or a related test runner), 132 then it will run all the methods in each class. You can modify this behavior 133 by using the {@link junit.framework.TestSuite TestSuite} class. 134 </p> 135 136 <p> 137 To create a test application, start with one of Android's test classes in the Java package {@link android.test android.test}. 138 These extend the JUnit {@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test classes 139 also provide instrumentation for testing. 140 </p> 141 <p> 142 For test classes that extend {@link junit.framework.TestCase TestCase}, you probably want to override 143 the <code>setUp()</code> and <code>tearDown()</code> methods: 144 </p> 145 <ul> 146 <li> 147 <code>setUp()</code>: This method is invoked before any of the test methods in the class. 148 Use it to set up the environment for the test. You can use <code>setUp()</code> 149 to instantiate a new <code>Intent</code> object with the action <code>ACTION_MAIN</code>. You can 150 then use this intent to start the Activity under test. 151 <p class="note"><strong>Note:</strong> If you override this method, call 152 <code>super.setUp()</code> as the first statement in your code. 153 </p> 154 </li> 155 <li> 156 <code>tearDown()</code>: This method is invoked after all the test methods in the class. Use 157 it to do garbage collection and re-setting before moving on to the next set of tests. 158 <p class="note"><strong>Note:</strong> If you override this method, you must call 159 <code>super.tearDown()</code> as the <em>last</em> statement in your code.</p> 160 </li> 161 </ul> 162 <p> 163 Another useful convention is to add the method <code>testPreConditions()</code> to your test 164 class. Use this method to test that the application under test is initialized correctly. If this 165 test fails, you know that that the initial conditions were in error. When this happens, further test 166 results are suspect, regardless of whether or not the tests succeeded. 167 </p> 168 <p> 169 The Resources tab contains an <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> 170 tutorial with more information about creating test classes and methods. 171 </p> 172 <h2 id="RunTestEclipse">Running Tests</h2> 173 <div class="sidebox-wrapper"> 174 <div class="sidebox"> 175 <h2>Running tests from the command line</h2> 176 <p> 177 If you've created your tests in Eclipse, you can still run your tests and test 178 suites by using command-line tools included with the Android SDK. You may want to 179 do this, for example, if you have a large number of tests to run, if you have a 180 large test case, or if you want a fine level of control over which tests are run at 181 a particular time. 182 </p> 183 <p> 184 To run tests created in Eclipse with ADT with command-line tools, you must first 185 install additional files into the test project using the <code>android</code> tool's 186 "create test-project" option. To see how to do this, read the section 187 <a href="{@docRoot}guide/developing/testing/testing_otheride.html#CreateProject"> 188 Creating a test project</a> in the topic 189 <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other 190 IDEs</a>. 191 </p> 192 </div> 193 </div> 194 <p> 195 When you run a test application in Eclipse with ADT, the output appears in 196 an Eclipse view panel. You can run the entire test application, one class, or one 197 method of a class. To do this, Eclipse runs the <code>adb</code> command for running a test application, and 198 displays the output, so there is no difference between running tests inside Eclipse and running them from the command line. 199 </p> 200 <p> 201 As with any other application, to run a test application in Eclipse with ADT you must either attach a device to your 202 computer or use the Android emulator. If you use the emulator, you must have an Android Virtual Device (AVD) that uses 203 the same target 204 </p> 205 <p> 206 To run a test in Eclipse, you have two choices:</p> 207 <ol> 208 <li> 209 Run a test just as you run an application, by selecting 210 <strong>Run As... > Android JUnit Test</strong> from the project's context menu or 211 from the main menu's <strong>Run</strong> item. 212 </li> 213 <li> 214 Create an Eclipse run configuration for your test project. This is useful if you want multiple test suites, each consisting of selected tests from the project. To run 215 a test suite, you run the test configuration. 216 <p> 217 Creating and running test configurations is described in the next section. 218 </p> 219 </li> 220 </ol> 221 <p>To create and run a test suite using a run configuration:</p> 222 <ol> 223 <li> 224 In the Package Explorer, select the test 225 project, then from the main menu, select 226 <strong>Run > Run Configurations...</strong>. The 227 Run Configurations dialog appears. 228 </li> 229 <li> 230 In the left-hand pane, find the 231 Android JUnit Test entry. 232 In the right-hand pane, click the Test tab. 233 The Name: text box 234 shows the name of your project. The 235 Test class: dropdown box shows one your project's classes 236 test classes in your project. 237 </li> 238 <li> 239 To run one test class, click Run a single test, then enter your project 240 name in the Project: text box and the class name in the 241 Test class: text box. 242 <p> 243 To run all the test classes, 244 click Run all tests in the selected project or package, 245 then enter the project or package name in the text box. 246 </p> 247 </li> 248 <li> 249 Now click the Target tab. 250 <ul> 251 <li> 252 Optional: If you are using the emulator, click 253 Automatic, then in the Android Virtual Device (AVD) 254 selection table, select an existing AVD. 255 </li> 256 <li> 257 In the Emulator Launch Parameters pane, set the 258 Android emulator flags you want to use. These are documented in the topic 259 <a href="{@docRoot}guide/developing/tools/emulator.html#startup-options">Emulator Startup Options</a>. 260 </li> 261 </ul> 262 <li> 263 Click the Common tab. In the 264 Save As pane, click Local to save 265 this run configuration locally, or click Shared to 266 save it to another project. 267 </li> 268 <li> 269 Optional: Add the configuration to the Run toolbar and the <strong>Favorites</strong> 270 menu: in the Display in Favorites pane 271 click the checkbox next to Run. 272 </li> 273 <li> 274 Optional: To add this configuration to the <strong>Debug</strong> menu and toolbar, click 275 the checkbox next to Debug. 276 </li> 277 <li> 278 To save your settings, click Close.<br/> 279 <p class="note"><strong>Note:</strong> Although you can run the test immediately by 280 clicking Run, you should save the test first and then 281 run it by selecting it from the Eclipse standard toolbar.</p> 282 </li> 283 <li> 284 On the Eclipse standard toolbar, click the down arrow next to the 285 green Run arrow. This displays a menu of saved Run and Debug 286 configurations. 287 </li> 288 <li> 289 Select the test run configuration you just created. 290 </li> 291 <li> 292 The progress of your test appears in the Console view. 293 You should see the following messages, among others: 294 <ul> 295 <li> 296 <code>Performing Android.test.InstrumentationTestRunner JUnit launch</code><br> 297 The class name that proceeds "JUnit" depends on the Android instrumentation 298 class you have chosen. 299 </li> 300 <li> 301 If you are using an emulator and you have not yet started it, then you will see 302 the message: 303 <p> 304 <code>Automatic Target Mode: launching new emulator with compatible 305 AVD <em>avdname</em></code><br>(where <em>avdname</em> is the name of 306 the AVD you are using.) 307 </p> 308 </li> 309 <li> 310 If you have not already installed your test application, then you will see 311 the message: 312 <p> 313 <code>Uploading <em>testclass</em>.apk onto device '<em>device-id</em>'</code><br> 314 where <em>testclass</em> is the name of your unit test class and <em>device-id</em> 315 is the name and port for your test device or emulator, followed by the message <code>Installing <em>testclass</em>.apk</code> 316 </p> 317 </li> 318 <li> 319 <code>Launching instrumentation Android.test.InstrumentationTestRunner on device <em>device-id</em></code>.<br> 320 This indicates that Android's Instrumentation system is now testing your code. Again, the 321 instrumentation class name depends on the Android instrumentation class you have chosen. 322 </li> 323 <li> 324 <code>Test run complete</code>.<br> When you see this, your unit tests have finished. 325 </li> 326 </ul> 327 </ol> 328 <p> 329 The test results appear in the JUnit view. This is divided into an upper summary pane, 330 and a lower stack trace pane. 331 </p> 332 <p> 333 The upper pane contains test information. In the pane's header, you see the following 334 information: 335 </p> 336 <ul> 337 <li> 338 Total time elapsed for the test application (labeled Finished after <em>x</em> seconds). 339 </li> 340 <li> 341 Number of runs (Runs:) - the number of tests in the entire test class. 342 </li> 343 <li> 344 Number of errors (Errors:) - the number of program errors and exceptions encountered 345 during the test run. 346 </li> 347 <li> 348 Number of failures (Failures:) - the number of test failures encountered during the test 349 run. This is the number of assertion failures. A test can fail even if the program does 350 not encounter an error. 351 </li> 352 <li> 353 A progress bar. The progress bar extends from left to right as the tests run. If all the 354 tests succeed, the bar remains green. If a test fails, the bar turns from green to red. 355 </li> 356 </ul> 357 <p> 358 The body of the upper pane contains the details of the test run. For each test case class 359 that was run, you see a line with the class name. To look at the results for the individual 360 test methods in that class, you click the left arrow to expand the line. You now see a 361 line for each test method in the class, and to its right the time it took to run. 362 If you double-click the method name, Eclipse opens the test class source in an editor view 363 pane and moves the focus to the first line of the test method. 364 </p> 365 <p> 366 The lower pane is for stack traces. If you highlight a failed test in the upper pane, the 367 lower pane contains a stack trace for the test. If a line corresponds to a point in your 368 test code, you can double-click it to display the code in an editor view pane, with the 369 line highlighted. For a successful test, the lower pane is empty. 370 </p> 371
