1 page.title=Hello, 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="#CreateTestProject">Creating the Test Project</a> 11 </li> 12 <li> 13 <a href="#CreateTestClass">Creating the Test Case Class</a> 14 <ol> 15 <li> 16 <a href="#CreateTestCaseClassFile">Adding the test case class file</a> 17 </li> 18 <li> 19 <a href="#CreateConstructor">Adding the test case constructor</a> 20 </li> 21 <li> 22 <a href="#CreateSetUp">Adding a setup method</a> 23 </li> 24 <li> 25 <a href="#CreatePreConditions">Adding a preconditions test</a> 26 </li> 27 <li> 28 <a href="#CreateText">Adding a unit test</a> 29 </li> 30 <li> 31 <a href="#CompleteTest">The finished test case class</a> 32 </li> 33 </ol> 34 </li> 35 <li> 36 <a href="#RunTest">Running the Tests and Seeing the Results</a> 37 </li> 38 <li> 39 <a href="#NextSteps">Next Steps</a> 40 </li> 41 </ol> 42 <h2>Related Tutorials</h2> 43 <ol> 44 <li> 45 <a href="{@docRoot}resources/tutorials/hello-world.html">Hello, World</a> 46 </li> 47 <li> 48 <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> 49 </li> 50 </ol> 51 <h2>See Also</h2> 52 <ol> 53 <li> 54 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> 55 </li> 56 <li> 57 {@link android.test.ActivityInstrumentationTestCase2} 58 </li> 59 <li> 60 {@link android.test.InstrumentationTestRunner} 61 </li> 62 </ol> 63 64 </div> 65 </div> 66 <p> 67 Android offers a powerful but easy-to-use testing framework that is well integrated with the SDK tools. Because writing 68 tests is an important part of any development effort, this tutorial introduces the basics of testing and helps you get started testing quickly. 69 70 To keep things simple, this tutorial builds on the <a href="{@docRoot}resources/tutorials/hello-world.html">Hello World</a> tutorial, which you may have already completed. 71 It guides you through the process of setting up a test project, adding a test, and running the test against the Hello World application, all from inside the Eclipse environment. 72 Of course, when you are done with this tutorial, you will want to create a test project for your own app and add various types of tests to it. 73 </p> 74 <p> 75 If you'd like to read an overview of the test and instrumentation framework and the core test case classes available, look at 76 the <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> topic. 77 If you prefer a more advanced testing tutorial, try the 78 <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> tutorial. 79 </p> 80 <h2 id="Prerequisites">Prerequisites</h2> 81 <p> 82 This tutorial and its code depend on the Hello World tutorial. If you haven't completed that tutorial already, 83 do so now. You will learn the fundamentals of Android application development, and you will 84 have an Android application that is ready to be tested. The tutorial guides you through the 85 setup of an Android test project using the ADT Plugin for Eclipse and other SDK tools. 86 You will need an SDK development platform that is version 1.5 87 (API level 3) or higher. 88 </p> 89 <p> 90 If you aren't developing in Eclipse with ADT or you would like to run tests directly from the 91 command line, please see the topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a> 92 for instructions. 93 </p> 94 <h2 id="CreateTestProject">Creating the Test Project</h2> 95 <p> 96 In the Hello World tutorial you created Android application project called 97 HelloAndroid. A test of an Android application is also an Android 98 application, and you create it within an Eclipse project. The Eclipse with ADT 99 <strong>New Android Test Project</strong> dialog creates a new test project and the 100 framework of a new test application at the same time. 101 </p> 102 <p> 103 To create the test project and test application framework in Eclipse with ADT, follow these steps 104 </p> 105 <ol> 106 <li> 107 In Eclipse, select <strong>New</strong> > <strong>Project</strong> > <strong>Android</strong> > <strong>Android Test Project</strong>. 108 <p> 109 <a href="{@docRoot}images/testing/hwtest_new_test_project_menu.png"> 110 <img alt="New Android Test Project menu" src="{@docRoot}images/testing/hwtest_new_test_project_menu.png" style="height:230px"/> 111 </a> 112 </p> 113 <p> 114 The New Android Test Project dialog appears. 115 </p> 116 </li> 117 <li> 118 Set the following values: 119 <ul> 120 <li> 121 <em>Test Project Name:</em> "HelloAndroidTest" 122 </li> 123 <li> 124 <em>Test Target:</em> Set "An existing Android project", click Browse, and then 125 select "HelloAndroid" from the list of projects. 126 </li> 127 <li> 128 <em>Build Target:</em> Set a target whose platform is Android 1.5 or above. 129 </li> 130 <li> 131 <em>Application name:</em> "HelloAndroidTest" 132 </li> 133 <li> 134 <em>Package name:</em> "<code>com.example.helloandroid.test</code>" 135 </li> 136 </ul> 137 <p> 138 The dialog should now look like this: 139 </p> 140 <a href="{@docRoot}images/testing/hwtest_new_test_project_dialog_complete_callouts.png"> 141 <img alt="New Android Test Project dialog with entries" src="{@docRoot}images/testing/hwtest_new_test_project_dialog_complete_callouts.png" style="height:230px"/> 142 </a> 143 </li> 144 <li> 145 Click Finish. The new project appears in the Package Explorer. 146 </li> 147 </ol> 148 <h2 id="CreateTestClass">Creating the Test Case Class</h2> 149 <p> 150 You now have a test project HelloAndroidTest, and the basic structure of a test application 151 also called HelloAndroidTest. The basic structure includes all the files and directories you 152 need to build and run a test application, <em>except for</em> the class that contains 153 your tests (the <strong>test case class</strong>). 154 </p> 155 <p> 156 The next step is to define the test case class. In this tutorial, you define a test case class 157 that extends one of Android's test case classes designed for Activities. The class contains 158 definitions for four methods: 159 </p> 160 <ol> 161 <li> 162 <code>HelloAndroidTest</code>: This defines the constructor for the class. It is 163 required by the Android testing framework. 164 </li> 165 <li> 166 <code>setUp()</code>: This overrides the JUnit <code>setUp()</code> method. You use 167 it to initialize the environment before each test runs. 168 </li> 169 <li> 170 <code>testPreconditions()</code>: This defines a small test that ensures the Hello, Android 171 application starts up correctly. 172 </li> 173 <li> 174 <code>testText()</code>: This tests that what is displayed on the screen is the 175 same as what is contained in the application's string resources. It is an example of 176 a real unit test you would perform against an application's UI. 177 </li> 178 </ol> 179 <p> 180 The following sections contain the code for the test case class and its methods. 181 </p> 182 183 <h3 id="CreateTestCaseClassFile">Adding the test case class file</h3> 184 <p> 185 To add the Java file for the test case class, follow these steps 186 </p> 187 <ol> 188 <li> 189 In Eclipse, open the HelloAndroidTest project if it is not already open. 190 </li> 191 <li> 192 Within HelloAndroidTest, expand the <code>src/</code> folder and 193 then find the package icon for <code>com.example.helloandroid.test</code>. 194 Right-click on the package icon and select <strong>New</strong> > <strong>Class</strong>: 195 <p> 196 <a href="{@docRoot}images/testing/hwtest_create_test_class_menu_callouts.png"> 197 <img alt="Menu for creating a new class in the test application" src="{@docRoot}images/testing/hwtest_create_test_class_menu_callouts.png" style="height:230px"/> 198 </a> 199 </p> 200 <p> 201 The New Java Class dialog appears. 202 </p> 203 </li> 204 <li> 205 In the dialog, enter the following: 206 <ul> 207 <li> 208 <em>Name:</em> "HelloAndroidTest". This becomes the name of your test class. 209 </li> 210 <li> 211 <em>Superclass:</em> "<code>android.test.ActivityInstrumentationTestCase2<HelloAndroid></code>". 212 The superclass is parameterized by an Activity class name. 213 <p> 214 The dialog should now look like this: 215 </p> 216 <a href="{@docRoot}images/testing/hwtest_new_test_class_dialog_complete_callouts.png"> 217 <img alt="New Java Class dialog with entries" src="{@docRoot}images/testing/hwtest_new_test_class_dialog_complete_callouts.png" style="height:230px"/> 218 </a> 219 </li> 220 </ul> 221 <p> 222 Do not change any of the other settings. Click Finish. 223 </p> 224 </li> 225 <li> 226 You now have a new file <code>HelloAndroidTest.java</code> in the project. 227 This file contains the class <code>HelloAndroidTest</code>, 228 which extends the Activity test case class 229 <code>ActivityInstrumentationTestCase2<T></code>. You parameterize the 230 class with <code>HelloAndroid</code>, which is the class name of the activity under test. 231 </li> 232 <li> 233 Open <code>HelloAndroidTest.java</code>. It should look like this: 234 <pre class="prettyprint"> 235 package com.example.helloandroid.test; 236 237 import android.test.ActivityInstrumentationTestCase2; 238 239 public class HelloAndroidTest extends ActivityInstrumentationTestCase2<HelloAndroid> { 240 } 241 </pre> 242 </li> 243 <li> 244 The test case class depends on the <code>HelloAndroid</code> class, which is not 245 yet imported. To import the class, add the following line just before the current 246 <code>import</code> statement: 247 <pre class="prettyprint"> 248 import com.example.helloandroid.HelloAndroid; 249 </pre> 250 </li> 251 </ol> 252 <h3 id="CreateConstructor">Adding the test case constructor</h3> 253 <p> 254 The test case class constructor is used by the Android testing framework when you run the test. 255 It calls the super constructor with parameters that tell the framework what Android application 256 should be tested. 257 </p> 258 <p> 259 Add the following constructor method immediately after the class definition: 260 </p> 261 <pre class="prettyprint"> 262 public HelloAndroidTest() { 263 super("com.example.helloandroid", HelloAndroid.class); 264 } 265 </pre> 266 <p> 267 Save the file <code>HelloAndroidTest.java</code>. 268 </p> 269 <h3 id="CreateSetUp">Adding a setup method</h3> 270 <p> 271 The <code>setUp()</code> method overrides the JUnit {@link junit.framework.TestCase#setUp() setUp()} 272 method, which the Android testing framework calls prior to running each test method. You use 273 <code>setUp()</code> to initialize variables and prepare the test environment. For this 274 test case, the <code>setUp()</code> method starts the Hello, Android application, 275 retrieves the text being displayed on the screen, and retrieves the text string in the 276 resource file. 277 </p> 278 <p> 279 First, add the following code immediately after the constructor method: 280 </p> 281 <pre class="prettyprint"> 282 @Override 283 protected void setUp() throws Exception { 284 super.setUp(); 285 mActivity = this.getActivity(); 286 mView = (TextView) mActivity.findViewById(com.example.helloandroid.R.id.textview); 287 resourceString = mActivity.getString(com.example.helloandroid.R.string.hello); 288 } 289 </pre> 290 <p> 291 For this code to work, you must also add some class members and another import statement. To 292 add the class members, add the following code immediately after the class definition: 293 </p> 294 <pre class="prettyprint"> 295 private HelloAndroid mActivity; 296 private TextView mView; 297 private String resourceString; 298 </pre> 299 <p> 300 To add the import statement, add the following statement just after the import for 301 <code>android.test.ActivityInstrumentationTestCase2</code>: 302 </p> 303 <pre class="prettyprint"> 304 import android.widget.TextView; 305 </pre> 306 <h3 id="CreatePreConditions">Adding a preconditions test</h3> 307 <p> 308 A preconditions test checks the initial application conditions prior to executing other tests. 309 It's similar to <code>setUp()</code>, but with less overhead, since it only runs once. 310 </p> 311 <p> 312 Although a preconditions test can check for a variety of different conditions, 313 in this application it only needs to check whether the application under test is 314 initialized properly and the target TextView exists. 315 To do this, it calls the inherited 316 {@link junit.framework.Assert#assertNotNull(Object) assertNotNull()} 317 method, passing a reference to the TextView. 318 The test succeeds only if the object reference is not null. 319 </p> 320 <pre class="prettyprint"> 321 public void testPreconditions() { 322 assertNotNull(mView); 323 } 324 </pre> 325 <h3 id="CreateText">Adding a unit test</h3> 326 <p> 327 Now add a simple unit test to the test case class. 328 The method <code>testText()</code> will call a 329 {@link junit.framework.Assert JUnit Assert} 330 method to check whether the target TextView is displaying the expected text. 331 </p> 332 <p> 333 For this example, the test expects that the TextView is 334 displaying the string resource that was originally declared for it in HelloAndroid's 335 <code>main.xml</code> file, referred to by the resource ID <code>hello</code>. 336 The call to 337 {@link junit.framework.Assert#assertEquals(String, String) assertEquals(String,String)} 338 compares the expected value, read directly from the <code>hello</code>string resource, 339 to the text displayed by the TextView, obtained from the 340 TextView's <code>getText()</code> method. The test succeeds only if the strings match. 341 </p> 342 <p> 343 To add this test, add the following code 344 immediately after the <code>testPreconditions()</code> method: 345 </p> 346 <pre class="prettyprint"> 347 public void testText() { 348 assertEquals(resourceString,(String)mView.getText()); 349 } 350 </pre> 351 <h3 id="CompleteTest">The finished test case class</h3> 352 <p> 353 You have now finished writing the test. This is what the complete test case class 354 should look like: 355 </p> 356 <pre class="prettyprint"> 357 package com.example.helloandroid.test; 358 359 import com.example.helloandroid.HelloAndroid; 360 import android.test.ActivityInstrumentationTestCase2; 361 import android.widget.TextView; 362 363 public class HelloAndroidTest extends ActivityInstrumentationTestCase2<HelloAndroid> { 364 private HelloAndroid mActivity; // the activity under test 365 private TextView mView; // the activity's TextView (the only view) 366 private String resourceString; 367 368 public HelloAndroidTest() { 369 super("com.example.helloandroid", HelloAndroid.class); 370 } 371 @Override 372 protected void setUp() throws Exception { 373 super.setUp(); 374 mActivity = this.getActivity(); 375 mView = (TextView) mActivity.findViewById(com.example.helloandroid.R.id.textview); 376 resourceString = mActivity.getString(com.example.helloandroid.R.string.hello); 377 } 378 public void testPreconditions() { 379 assertNotNull(mView); 380 } 381 public void testText() { 382 assertEquals(resourceString,(String)mView.getText()); 383 } 384 } 385 </pre> 386 <h2 id="RunTest">Running the Tests and Seeing the Results</h2> 387 <p> 388 You can now run the tests you've created against the Hello, Android application. In Eclipse with 389 ADT, you run a test application as an <strong>Android JUnit test</strong> rather than a regular 390 Android application. 391 </p> 392 <p> 393 To run the test application as an Android JUnit test, in the Package Explorer right-click 394 the HelloAndroidTest project and select <strong>Run As</strong> > <strong>Android JUnit Test</strong> 395 </p> 396 <a href="{@docRoot}images/testing/hwtest_runas_menu_callouts.png"> 397 <img alt="Menu to run Hello, World as an Android JUnit test" 398 src="{@docRoot}images/testing/hwtest_runas_menu_callouts.png" style="height:230px"> 399 </a> 400 <p> 401 The ADT plugin then launches the test application and the application 402 under test on a the target emulator or device. When both applications are running, 403 the testing framework runs the tests and reports the results in the JUnit view of Eclipse, 404 which appears by default as a tab next to the Package Explorer. 405 </p> 406 <p> 407 As shown below, the JUnit view shows test results in two separate panes: 408 an upper pane summarizes the tests that were run and a lower pane reports the failure traces 409 for the tests. In this case, the tests in this example have run successfully, so there is no 410 failure reported in the view: 411 </p> 412 <a href="{@docRoot}images/testing/hwtest_junit_success.png"> 413 <img src="{@docRoot}images/testing/hwtest_junit_success.png" 414 alt="JUnit test run success" style="height:230px"/> 415 </a> 416 <p> 417 The upper pane summarizes the test: 418 </p> 419 <ul> 420 <li> 421 "Finished after <em>x</em> seconds": How long the test took to run. 422 </li> 423 <li> 424 "Runs": The number of tests run. 425 </li> 426 <li> 427 "Errors:": The number of program errors and exceptions encountered during 428 the test run. 429 </li> 430 <li> 431 "Failures:": The number of assertion failures encountered during the 432 test run. 433 </li> 434 <li> 435 A progress bar. The progress bar extends from left to right as the tests run. 436 <p> 437 If all the tests succeed, the bar remains green. 438 If a test fails, the bar turns from green to red. 439 </p> 440 </li> 441 <li> 442 A test method summary. Below the bar, you see a line for each class in the 443 test application, labeled by its fully-qualified class name. 444 To look at the results for the individual methods in a test case class, 445 click the arrow at the left of the class to expand the line. 446 You see the name of each test method. To the right of the method name, you see the 447 time needed to run that method. You can look at the method's code by 448 double-clicking its name. 449 </li> 450 </ul> 451 <p> 452 The lower pane contains the failure trace. If all the tests are successful, 453 this pane is empty. If some tests fail, then if you select a failed test in the 454 upper pane, the lower view contains a stack trace for the test. 455 </p> 456 <h2 id="NextSteps">Next Steps</h2> 457 <p> 458 This simple example test application has shown you how to create a test project, 459 create a test class and test cases, and then run the tests against a target application. 460 Now that you are familiar with these fundamentals, here are some suggested next steps: 461 </p> 462 <p> 463 <strong>Learn more about testing on Android</strong> 464 </p> 465 <ul> 466 <li> 467 The 468 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Android Applications</a> 469 document in the <em>Dev Guide</em> provides an overview of how testing on Android works. 470 If you are just getting started with Android testing, reading that document will 471 help you understand the tools available to you, so that you can develop effective 472 tests. 473 </li> 474 </ul> 475 <p> 476 <strong>Learn more about the testing classes available in Android</strong> 477 </p> 478 <ul> 479 <li> 480 For an overview of the types of testing classes you can use, 481 browse through the reference documentation for 482 {@link android.test.ActivityInstrumentationTestCase2}, 483 {@link android.test.ProviderTestCase2}, 484 {@link android.test.ServiceTestCase}, and 485 {@link junit.framework.Assert}. 486 </li> 487 </ul> 488 <p> 489 <strong>Explore the Android instrumentation framework</strong> 490 </p> 491 <ul> 492 <li> 493 The {@link android.test.InstrumentationTestRunner} class contains the code that Android uses 494 to run tests against an application. The {@link android.test.InstrumentationTestCase} class 495 is the base class for test case classes that use additional instrumentation features. 496 </li> 497 </ul> 498 <p> 499 <strong>Follow the Activity Testing tutorial</strong> 500 </p> 501 <ul> 502 <li> 503 The <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> 504 tutorial is an excellent follow-up to this tutorial. 505 It guides you through a more complex testing scenario that you develop against a 506 more realistic application. 507 </li> 508 </ul> 509
