1page.title=Testing Fundamentals 2@jd:body 3 4<div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>In this document</h2> 7 <ol> 8 <li> 9 <a href="#TestStructure">Test Structure</a> 10 </li> 11 <li> 12 <a href="#TestProjects">Test Projects</a> 13 </li> 14 <li> 15 <a href="#TestAPI">The Testing API</a> 16 <ol> 17 <li> 18 <a href="#JUnit">JUnit</a> 19 </li> 20 <li> 21 <a href="#Instrumentation">Instrumentation</a> 22 </li> 23 <li> 24 <a href="#TestCaseClasses">Test case classes</a> 25 </li> 26 <li> 27 <a href="#AssertionClasses">Assertion classes</a> 28 </li> 29 <li> 30 <a href="#MockObjectClasses">Mock object classes</a> 31 </li> 32 </ol> 33 </li> 34 <li> 35 <a href="#InstrumentationTestRunner">Running Tests</a> 36 </li> 37 <li> 38 <a href="#TestResults">Seeing Test Results</a> 39 </li> 40 <li> 41 <a href="#Monkeys">monkey and monkeyrunner</a> 42 </li> 43 <li> 44 <a href="#PackageNames">Working With Package Names</a> 45 </li> 46 <li> 47 <a href="#WhatToTest">What To Test</a> 48 </li> 49 <li> 50 <a href="#NextSteps">Next Steps</a> 51 </li> 52 </ol> 53 <h2>Key classes</h2> 54 <ol> 55 <li>{@link android.test.InstrumentationTestRunner}</li> 56 <li>{@link android.test}</li> 57 <li>{@link android.test.mock}</li> 58 <li>{@link junit.framework}</li> 59 </ol> 60 <h2>Related tutorials</h2> 61 <ol> 62 <li> 63 <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> 64 Hello, Testing</a> 65 </li> 66 <li> 67 <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> 68 </li> 69 </ol> 70 <h2>See also</h2> 71 <ol> 72 <li> 73 <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> 74 Testing in Eclipse, with ADT</a> 75 </li> 76 <li> 77 <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> 78 Testing in Other IDEs</a> 79 </li> 80 <li> 81 <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html"> 82 monkeyrunner</a> 83 </li> 84 <li> 85 <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a> 86 </li> 87 </ol> 88 </div> 89</div> 90<p> 91 The Android testing framework, an integral part of the development environment, 92 provides an architecture and powerful tools that help you test every aspect of your application 93 at every level from unit to framework. 94</p> 95<p> 96 The testing framework has these key features: 97</p> 98<ul> 99 <li> 100 Android test suites are based on JUnit. You can use plain JUnit to test a class that doesn't 101 call the Android API, or Android's JUnit extensions to test Android components. If you're 102 new to Android testing, you can start with general-purpose test case classes such as {@link 103 android.test.AndroidTestCase} and then go on to use more sophisticated classes. 104 </li> 105 <li> 106 The Android JUnit extensions provide component-specific test case classes. These classes 107 provide helper methods for creating mock objects and methods that help you control the 108 lifecycle of a component. 109 </li> 110 <li> 111 Test suites are contained in test packages that are similar to main application packages, so 112 you don't need to learn a new set of tools or techniques for designing and building tests. 113 </li> 114 <li> 115 The SDK tools for building and tests are available in Eclipse with ADT, and also in 116 command-line form for use with other IDES. These tools get information from the project of 117 the application under test and use this information to automatically create the build files, 118 manifest file, and directory structure for the test package. 119 </li> 120 <li> 121 The SDK also provides 122 <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a>, an API 123 testing devices with Python programs, and <a 124 href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, 125 a command-line tool for stress-testing UIs by sending pseudo-random events to a device. 126 </li> 127</ul> 128<p> 129 This document describes the fundamentals of the Android testing framework, including the 130 structure of tests, the APIs that you use to develop tests, and the tools that you use to run 131 tests and view results. The document assumes you have a basic knowledge of Android application 132 programming and JUnit testing methodology. 133</p> 134<p> 135 The following diagram summarizes the testing framework: 136</p> 137<div style="width: 70%; margin-left:auto; margin-right:auto;"> 138<a href="{@docRoot}images/testing/test_framework.png"> 139 <img src="{@docRoot}images/testing/test_framework.png" 140 alt="The Android testing framework"/> 141</a> 142</div> 143<h2 id="TestStructure">Test Structure</h2> 144<p> 145 Android's build and test tools assume that test projects are organized into a standard 146 structure of tests, test case classes, test packages, and test projects. 147</p> 148<p> 149 Android testing is based on JUnit. In general, a JUnit test is a method whose 150 statements test a part of the application under test. You organize test methods into classes 151 called test cases (or test suites). Each test is an isolated test of an individual module in 152 the application under test. Each class is a container for related test methods, although it 153 often provides helper methods as well. 154</p> 155<p> 156 In JUnit, you build one or more test source files into a class file. Similarly, in Android you 157 use the SDK's build tools to build one or more test source files into class files in an 158 Android test package. In JUnit, you use a test runner to execute test classes. In Android, you 159 use test tools to load the test package and the application under test, and the tools then 160 execute an Android-specific test runner. 161</p> 162<h2 id="TestProjects">Test Projects</h2> 163<p> 164 Tests, like Android applications, are organized into projects. 165</p> 166<p> 167 A test project is a directory or Eclipse project in which you create the source code, manifest 168 file, and other files for a test package. The Android SDK contains tools for Eclipse with ADT 169 and for the command line that create and update test projects for you. The tools create the 170 directories you use for source code and resources and the manifest file for the test package. 171 The command-line tools also create the Ant build files you need. 172</p> 173<p> 174 You should always use Android tools to create a test project. Among other benefits, 175 the tools: 176</p> 177 <ul> 178 <li> 179 Automatically set up your test package to use 180 {@link android.test.InstrumentationTestRunner} as the test case runner. You must use 181 <code>InstrumentationTestRunner</code> (or a subclass) to run JUnit tests. 182 </li> 183 <li> 184 Create an appropriate name for the test package. If the application 185 under test has a package name of <code>com.mydomain.myapp</code>, then the 186 Android tools set the test package name to <code>com.mydomain.myapp.test</code>. This 187 helps you identify their relationship, while preventing conflicts within the system. 188 </li> 189 <li> 190 Automatically create the proper build files, manifest file, and directory 191 structure for the test project. This helps you to build the test package without 192 having to modify build files and sets up the linkage between your test package and 193 the application under test. 194 The 195 </li> 196 </ul> 197<p> 198 You can create a test project anywhere in your file system, but the best approach is to 199 add the test project so that its root directory <code>tests/</code> is at the same level 200 as the <code>src/</code> directory of the main application's project. This helps you find the 201 tests associated with an application. For example, if your application project's root directory 202 is <code>MyProject</code>, then you should use the following directory structure: 203</p> 204<pre class="classic no-pretty-print"> 205 MyProject/ 206 AndroidManifest.xml 207 res/ 208 ... (resources for main application) 209 src/ 210 ... (source code for main application) ... 211 tests/ 212 AndroidManifest.xml 213 res/ 214 ... (resources for tests) 215 src/ 216 ... (source code for tests) 217</pre> 218<h2 id="TestAPI">The Testing API</h2> 219<p> 220 The Android testing API is based on the JUnit API and extended with a instrumentation 221 framework and Android-specific testing classes. 222</p> 223<h3 id="JUnit">JUnit</h3> 224<p> 225 You can use the JUnit {@link junit.framework.TestCase TestCase} class to do unit testing on 226 a plain Java object. <code>TestCase</code> is also the base class for 227 {@link android.test.AndroidTestCase}, which you can use to test Android-dependent objects. 228 Besides providing the JUnit framework, AndroidTestCase offers Android-specific setup, 229 teardown, and helper methods. 230</p> 231<p> 232 You use the JUnit {@link junit.framework.Assert} class to display test results. 233 The assert methods compare values you expect from a test to the actual results and 234 throw an exception if the comparison fails. Android also provides a class of assertions that 235 extend the possible types of comparisons, and another class of assertions for testing the UI. 236 These are described in more detail in the section <a href="#AssertionClasses"> 237 Assertion classes</a> 238</p> 239<p> 240 To learn more about JUnit, you can read the documentation on the 241 <a href="http://www.junit.org">junit.org</a> home page. 242 Note that the Android testing API supports JUnit 3 code style, but not JUnit 4. Also, you must 243 use Android's instrumented test runner {@link android.test.InstrumentationTestRunner} to run 244 your test case classes. This test runner is described in the 245 section <a href="#InstrumentationTestRunner">Running Tests</a>. 246</p> 247<h3 id="Instrumentation">Instrumentation</h3> 248<p> 249 Android instrumentation is a set of control methods or "hooks" in the Android system. These hooks 250 control an Android component independently of its normal lifecycle. They also control how 251 Android loads applications. 252</p> 253<p> 254 Normally, an Android component runs in a lifecycle determined by the system. For example, an 255 Activity object's lifecycle starts when the Activity is activated by an Intent. The object's 256 <code>onCreate()</code> method is called, followed by <code>onResume()</code>. When the user 257 starts another application, the <code>onPause()</code> method is called. If the Activity 258 code calls the <code>finish()</code> method, the <code>onDestroy()</code> method is called. 259 The Android framework API does not provide a way for your code to invoke these callback 260 methods directly, but you can do so using instrumentation. 261</p> 262<p> 263 Also, the system runs all the components of an application into the same 264 process. You can allow some components, such as content providers, to run in a separate process, 265 but you can't force an application to run in the same process as another application that is 266 already running. 267</p> 268<p> 269 With Android instrumentation, though, you can invoke callback methods in your test code. 270 This allows you to run through the lifecycle of a component step by step, as if you were 271 debugging the component. The following test code snippet demonstrates how to use this to 272 test that an Activity saves and restores its state: 273</p> 274<a name="ActivitySnippet"></a> 275<pre> 276 // Start the main activity of the application under test 277 mActivity = getActivity(); 278 279 // Get a handle to the Activity object's main UI widget, a Spinner 280 mSpinner = (Spinner)mActivity.findViewById(com.android.example.spinner.R.id.Spinner01); 281 282 // Set the Spinner to a known position 283 mActivity.setSpinnerPosition(TEST_STATE_DESTROY_POSITION); 284 285 // Stop the activity - The onDestroy() method should save the state of the Spinner 286 mActivity.finish(); 287 288 // Re-start the Activity - the onResume() method should restore the state of the Spinner 289 mActivity = getActivity(); 290 291 // Get the Spinner's current position 292 int currentPosition = mActivity.getSpinnerPosition(); 293 294 // Assert that the current position is the same as the starting position 295 assertEquals(TEST_STATE_DESTROY_POSITION, currentPosition); 296</pre> 297<p> 298 The key method used here is 299 {@link android.test.ActivityInstrumentationTestCase2#getActivity()}, which is a 300 part of the instrumentation API. The Activity under test is not started until you call this 301 method. You can set up the test fixture in advance, and then call this method to start the 302 Activity. 303</p> 304<p> 305 Also, instrumentation can load both a test package and the application under test into the 306 same process. Since the application components and their tests are in the same process, the 307 tests can invoke methods in the components, and modify and examine fields in the components. 308</p> 309<h3 id="TestCaseClasses">Test case classes</h3> 310<p> 311 Android provides several test case classes that extend {@link junit.framework.TestCase} and 312 {@link junit.framework.Assert} with Android-specific setup, teardown, and helper methods. 313</p> 314<h4 id="AndroidTestCase">AndroidTestCase</h4> 315<p> 316 A useful general test case class, especially if you are 317 just starting out with Android testing, is {@link android.test.AndroidTestCase}. It extends 318 both {@link junit.framework.TestCase} and {@link junit.framework.Assert}. It provides the 319 JUnit-standard <code>setUp()</code> and <code>tearDown()</code> methods, as well as well as 320 all of JUnit's Assert methods. In addition, it provides methods for testing permissions, and a 321 method that guards against memory leaks by clearing out certain class references. 322</p> 323<h4 id="ComponentTestCase">Component-specific test cases</h4> 324<p> 325 A key feature of the Android testing framework is its component-specific test case classes. 326 These address specific component testing needs with methods for fixture setup and 327 teardown and component lifecycle control. They also provide methods for setting up mock objects. 328 These classes are described in the component-specific testing topics: 329</p> 330<ul> 331 <li> 332 <a href="{@docRoot}guide/topics/testing/activity_testing.html">Activity Testing</a> 333 </li> 334 <li> 335 <a href="{@docRoot}guide/topics/testing/contentprovider_testing.html"> 336 Content Provider Testing</a> 337 </li> 338 <li> 339 <a href="{@docRoot}guide/topics/testing/service_testing.html">Service Testing</a> 340 </li> 341</ul> 342<p> 343 Android does not provide a separate test case class for BroadcastReceiver. Instead, test a 344 BroadcastReceiver by testing the component that sends it Intent objects, to verify that the 345 BroadcastReceiver responds correctly. 346</p> 347<h4 id="ApplicationTestCase">ApplicationTestCase</h4> 348<p> 349 You use the {@link android.test.ApplicationTestCase} test case class to test the setup and 350 teardown of {@link android.app.Application} objects. These objects maintain the global state of 351 information that applies to all the components in an application package. The test case can 352 be useful in verifying that the <application> element in the manifest file is correctly 353 set up. Note, however, that this test case does not allow you to control testing of the 354 components within your application package. 355</p> 356<h4 id="InstrumentationTestCase">InstrumentationTestCase</h4> 357<p> 358 If you want to use instrumentation methods in a test case class, you must use 359 {@link android.test.InstrumentationTestCase} or one of its subclasses. The 360 {@link android.app.Activity} test cases extend this base class with other functionality that 361 assists in Activity testing. 362</p> 363 364<h3 id="AssertionClasses">Assertion classes</h3> 365<p> 366 Because Android test case classes extend JUnit, you can use assertion methods to display the 367 results of tests. An assertion method compares an actual value returned by a test to an 368 expected value, and throws an AssertionException if the comparison test fails. Using assertions 369 is more convenient than doing logging, and provides better test performance. 370</p> 371<p> 372 Besides the JUnit {@link junit.framework.Assert} class methods, the testing API also provides 373 the {@link android.test.MoreAsserts} and {@link android.test.ViewAsserts} classes: 374</p> 375<ul> 376 <li> 377 {@link android.test.MoreAsserts} contains more powerful assertions such as 378 {@link android.test.MoreAsserts#assertContainsRegex}, which does regular expression 379 matching. 380 </li> 381 <li> 382 {@link android.test.ViewAsserts} contains useful assertions about Views. For example 383 it contains {@link android.test.ViewAsserts#assertHasScreenCoordinates} that tests if a View 384 has a particular X and Y position on the visible screen. These asserts simplify testing of 385 geometry and alignment in the UI. 386 </li> 387</ul> 388<h3 id="MockObjectClasses">Mock object classes</h3> 389<p> 390 To facilitate dependency injection in testing, Android provides classes that create mock system 391 objects such as {@link android.content.Context} objects, 392 {@link android.content.ContentProvider} objects, {@link android.content.ContentResolver} 393 objects, and {@link android.app.Service} objects. Some test cases also provide mock 394 {@link android.content.Intent} objects. You use these mocks both to isolate tests 395 from the rest of the system and to facilitate dependency injection for testing. These classes 396 are found in the Java packages {@link android.test} and {@link android.test.mock}. 397</p> 398<p> 399 Mock objects isolate tests from a running system by stubbing out or overriding 400 normal operations. For example, a {@link android.test.mock.MockContentResolver} 401 replaces the normal resolver framework with its own local framework, which is isolated 402 from the rest of the system. MockContentResolver also also stubs out the 403 {@link android.content.ContentResolver#notifyChange(Uri, ContentObserver, boolean)} method 404 so that observer objects outside the test environment are not accidentally triggered. 405</p> 406<p> 407 Mock object classes also facilitate dependency injection by providing a subclass of the 408 normal object that is non-functional except for overrides you define. For example, the 409 {@link android.test.mock.MockResources} object provides a subclass of 410 {@link android.content.res.Resources} in which all the methods throw Exceptions when called. 411 To use it, you override only those methods that must provide information. 412</p> 413<p> 414 These are the mock object classes available in Android: 415</p> 416<h4 id="SimpleMocks">Simple mock object classes</h4> 417<p> 418 {@link android.test.mock.MockApplication}, {@link android.test.mock.MockContext}, 419 {@link android.test.mock.MockContentProvider}, {@link android.test.mock.MockCursor}, 420 {@link android.test.mock.MockDialogInterface}, {@link android.test.mock.MockPackageManager}, and 421 {@link android.test.mock.MockResources} provide a simple and useful mock strategy. They are 422 stubbed-out versions of the corresponding system object class, and all of their methods throw an 423 {@link java.lang.UnsupportedOperationException} exception if called. To use them, you override 424 the methods you need in order to provide mock dependencies. 425</p> 426<p class="Note"><strong>Note:</strong> 427 {@link android.test.mock.MockContentProvider} 428 and {@link android.test.mock.MockCursor} are new as of API level 8. 429</p> 430<h4 id="ResolverMocks">Resolver mock objects</h4> 431<p> 432 {@link android.test.mock.MockContentResolver} provides isolated testing of content providers by 433 masking out the normal system resolver framework. Instead of looking in the system to find a 434 content provider given an authority string, MockContentResolver uses its own internal table. You 435 must explicitly add providers to this table using 436 {@link android.test.mock.MockContentResolver#addProvider(String,ContentProvider)}. 437</p> 438<p> 439 With this feature, you can associate a mock content provider with an authority. You can create 440 an instance of a real provider but use test data in it. You can even set the provider for an 441 authority to <code>null</code>. In effect, a MockContentResolver object isolates your test 442 from providers that contain real data. You can control the 443 function of the provider, and you can prevent your test from affecting real data. 444</p> 445<h3 id="ContextMocks">Contexts for testing</h3> 446<p> 447 Android provides two Context classes that are useful for testing: 448</p> 449<ul> 450 <li> 451 {@link android.test.IsolatedContext} provides an isolated {@link android.content.Context}, 452 File, directory, and database operations that use this Context take place in a test area. 453 Though its functionality is limited, this Context has enough stub code to respond to 454 system calls. 455 <p> 456 This class allows you to test an application's data operations without affecting real 457 data that may be present on the device. 458 </p> 459 </li> 460 <li> 461 {@link android.test.RenamingDelegatingContext} provides a Context in which 462 most functions are handled by an existing {@link android.content.Context}, but 463 file and database operations are handled by a {@link android.test.IsolatedContext}. 464 The isolated part uses a test directory and creates special file and directory names. 465 You can control the naming yourself, or let the constructor determine it automatically. 466 <p> 467 This object provides a quick way to set up an isolated area for data operations, 468 while keeping normal functionality for all other Context operations. 469 </p> 470 </li> 471</ul> 472<h2 id="InstrumentationTestRunner">Running Tests</h2> 473<p> 474 Test cases are run by a test runner class that loads the test case class, set ups, 475 runs, and tears down each test. An Android test runner must also be instrumented, so that 476 the system utility for starting applications can control how the test package 477 loads test cases and the application under test. You tell the Android platform 478 which instrumented test runner to use by setting a value in the test package's manifest file. 479</p> 480<p> 481 {@link android.test.InstrumentationTestRunner} is the primary Android test runner class. It 482 extends the JUnit test runner framework and is also instrumented. It can run any of the test 483 case classes provided by Android and supports all possible types of testing. 484</p> 485<p> 486 You specify <code>InstrumentationTestRunner</code> or a subclass in your test package's 487 manifest file, in the <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"> 488 instrumentation</a> element. Also, <code>InstrumentationTestRunner</code> code resides 489 in the shared library <code>android.test.runner</code>, which is not normally linked to 490 Android code. To include it, you must specify it in a 491 <a href="{@docRoot}guide/topics/manifest/uses-library-element.html">uses-library</a> element. 492 You do not have to set up these elements yourself. Both Eclipse with ADT and the 493 <code>android</code> command-line tool construct them automatically and add them to your 494 test package's manifest file. 495</p> 496<p class="Note"> 497 <strong>Note:</strong> If you use a test runner other than 498 <code>InstrumentationTestRunner</code>, you must change the <instrumentation> 499 element to point to the class you want to use. 500</p> 501<p> 502 To run {@link android.test.InstrumentationTestRunner}, you use internal system classes called by 503 Android tools. When you run a test in Eclipse with ADT, the classes are called automatically. 504 When you run a test from the command line, you run these classes with 505 <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge (adb)</a>. 506</p> 507<p> 508 The system classes load and start the test package, kill any processes that 509 are running an instance of the application under test, and then load a new instance of the 510 application under test. They then pass control to 511 {@link android.test.InstrumentationTestRunner}, which runs 512 each test case class in the test package. You can also control which test cases and 513 methods are run using settings in Eclipse with ADT, or using flags with the command-line tools. 514</p> 515<p> 516 Neither the system classes nor {@link android.test.InstrumentationTestRunner} run 517 the application under test. Instead, the test case does this directly. It either calls methods 518 in the application under test, or it calls its own methods that trigger lifecycle events in 519 the application under test. The application is under the complete control of the test case, 520 which allows it to set up the test environment (the test fixture) before running a test. This 521 is demonstrated in the previous <a href="#ActivitySnippet">code snippet</a> that tests an 522 Activity that displays a Spinner widget. 523</p> 524<p> 525 To learn more about running tests, please read the topics 526 <a href="{@docRoot}guide/developing/testing/testing_eclipse.html""> 527 Testing in Eclipse, with ADT</a> or 528 <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> 529 Testing in Other IDes</a>. 530</p> 531<h2 id="TestResults">Seeing Test Results</h2> 532<p> 533 The Android testing framework returns test results back to the tool that started the test. 534 If you run a test in Eclipse with ADT, the results are displayed in a new JUnit view pane. If 535 you run a test from the command line, the results are displayed in <code>STDOUT</code>. In 536 both cases, you see a test summary that displays the name of each test case and method that 537 was run. You also see all the assertion failures that occurred. These include pointers to the 538 line in the test code where the failure occurred. Assertion failures also list the expected 539 value and actual value. 540</p> 541<p> 542 The test results have a format that is specific to the IDE that you are using. The test 543 results format for Eclipse with ADT is described in 544 <a href="{@docRoot}guide/developing/testing/testing_eclipse.html#RunTestEclipse"> 545 Testing in Eclipse, with ADT</a>. The test results format for tests run from the 546 command line is described in 547 <a href="{@docRoot}guide/developing/testing/testing_otheride.html#RunTestsCommand"> 548 Testing in Other IDEs</a>. 549</p> 550<h2 id="Monkeys">monkey and monkeyrunner</h2> 551<p> 552 The SDK provides two tools for functional-level application testing: 553</p> 554 <ul> 555 <li> 556The <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, 557 usually called "monkey", is a command-line tool that sends pseudo-random streams of 558 keystrokes, touches, and gestures to a device. You run it with the 559 <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb) tool. 560 You use it to stress-test your application and report back errors that are encountered. 561 You can repeat a stream of events by running the tool each time with the same random 562 number seed. 563 </li> 564 <li> 565 The <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a> tool 566 is an API and execution environment for test programs written in Python. The API 567 includes functions for connecting to a device, installing and uninstalling packages, 568 taking screenshots, comparing two images, and running a test package against an 569 application. Using the API, you can write a wide range of large, powerful, and complex 570 tests. You run programs that use the API with the <code>monkeyrunner</code> command-line 571 tool. 572 </li> 573 </ul> 574<h2 id="PackageNames">Working With Package names</h2> 575<p> 576 In the test environment, you work with both Android application package names and 577 Java package identifiers. Both use the same naming format, but they represent substantially 578 different entities. You need to know the difference to set up your tests correctly. 579</p> 580<p> 581 An Android package name is a unique system name for a <code>.apk</code> file, set by the 582 "android:package" attribute of the <manifest> element in the package's 583 manifest. The Android package name of your test package must be different from the 584 Android package name of the application under test. By default, Android tools create the 585 test package name by appending ".test" to the package name of the application under test. 586</p> 587<p> 588 The test package also uses an Android package name to target the application package it 589 tests. This is set in the "android:targetPackage" attribute of the 590 <instrumentation> element in the test package's manifest. 591</p> 592<p> 593 A Java package identifier applies to a source file. This package name reflects the directory 594 path of the source file. It also affects the visibility of classes and members to each other. 595</p> 596<p> 597 Android tools that create test projects set up an Android test package name for you. 598 From your input, the tools set up the test package name and the target package name for the 599 application under test. For these tools to work, the application project must already exist. 600</p> 601<p> 602 By default, these tools set the Java package identifier for the test class to be the same 603 as the Android package identifier. You may want to change this if you want to expose 604 members in the application under test by giving them package visibility. If you do this, 605 change only the Java package identifier, not the Android package names, and change only the 606 test case source files. Do not change the Java package name of the generated 607 <code>R.java</code> class in your test package, because it will then conflict with the 608 <code>R.java</code> class in the application under test. Do not change the Android package name 609 of your test package to be the same as the application it tests, because then their names 610 will no longer be unique in the system. 611</p> 612<h2 id="WhatToTest">What to Test</h2> 613<p> 614 The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> 615 describes the key functionality you should test in an Android application, and the key 616 situations that might affect that functionality. 617</p> 618<p> 619 Most unit testing is specific to the Android component you are testing. 620 The topics <a href="{@docRoot}guide/topics/testing/activity_testing.html">Activity Testing</a>, 621 <a href="{@docRoot}guide/topics/testing/contentprovider_testing.html"> 622 Content Provider Testing</a>, and <a href="{@docRoot}guide/topics/testing/service_testing.html"> 623 Service Testing</a> each have a section entitled "What To Test" that lists possible testing 624 areas. 625</p> 626<p> 627 When possible, you should run these tests on an actual device. If this is not possible, you can 628 use the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> with 629 <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> configured for 630 the hardware, screens, and versions you want to test. 631</p> 632<h2 id="NextSteps">Next Steps</h2> 633<p> 634 To learn how to set up and run tests in Eclipse, please refer to <a 635 href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in 636 Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a 637 href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other 638 IDEs</a>. 639</p> 640<p> 641 If you want a step-by-step introduction to Android testing, try one of the 642 testing tutorials or sample test packages: 643</p> 644<ul> 645 <li> 646 The <a 647 href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, 648 Testing</a> tutorial introduces basic testing concepts and procedures in the 649 context of the Hello, World application. 650 </li> 651 <li> 652 The <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity 653 Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. 654 It guides you through a more complex testing scenario that you develop against a 655 more realistic application. 656 </li> 657 <li> 658 The sample test package <a href="{@docRoot}resources/samples/AlarmServiceTest"}> 659 Alarm Service Test</a> is an example of testing a {@link android.app.Service}. It contains 660 a set of unit tests for the Alarm Service sample application's {@link android.app.Service}. 661 </li> 662</ul> 663 664
