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