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