Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Doc change: cherrypick testing changes from master. Squashed commit of the following:" into gingerbread

Browse Source
This commit is contained in:
Dirk Dougherty
2010-10-12 14:16:05 -07:00
committed by Android (Google) Code Review
parent 844a6b3cca dafac622a4
commit 354954a01c
14 changed files with 2324 additions and 1030 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/html/guide/developing/testing/index.jd
View File

@@ -1,6 +1,5 @@
page.title=Testing Overview page.title=Testing Overview
@jd:body @jd:body
<p> <p>
Android includes powerful tools for setting up and running test applications. Android includes powerful tools for setting up and running test applications.
Whether you are working in Eclipse with ADT or working from the command line, these tools Whether you are working in Eclipse with ADT or working from the command line, these tools
@@ -9,7 +8,7 @@ page.title=Testing Overview
</p> </p>
<p> <p>
If you aren't yet familiar with the Android testing framework, please read the topic If you aren't yet familiar with the Android testing framework, please read the topic
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a> <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>
before you get started. before you get started.
For a step-by-step introduction to Android testing, try the <a For a step-by-step introduction to Android testing, try the <a
href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, Testing</a> href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, Testing</a>

740
docs/html/guide/developing/testing/testing_eclipse.jd
View File

@@ -1,28 +1,23 @@
page.title=Testing In Eclipse, with ADT page.title=Testing In Eclipse, with ADT
@jd:body @jd:body
<div id="qv-wrapper"> <div id="qv-wrapper">
<div id="qv"> <div id="qv">
<h2>In this document</h2> <h2>In this document</h2>
<ol> <ol>
<li><a href="#CreateTestProjectEclipse">Creating a Test Project</a></li> <li><a href="#CreateTestProjectEclipse">Creating a Test Project</a></li>
<li><a href="#CreateTestAppEclipse">Creating a Test Application</a></li> <li><a href="#CreateTestAppEclipse">Creating a Test Package</a></li>
<li><a href="#RunTestEclipse">Running Tests</a></li> <li><a href="#RunTestEclipse">Running Tests</a></li>
</ol> </ol>
</div> </div>
</div> </div>
<p> <p>
This topic explains how create and run tests of Android applications in Eclipse with ADT. This topic explains how create and run tests of Android applications in Eclipse with ADT.
Before you read this topic, you should read about how to create a Android application with the
with the basic processes for creating and running applications with ADT, as described in basic processes for creating and running applications with ADT, as described in
<a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>. <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>.
You may also want to read
Before you read this topic, you should read about how to create a Android application with the <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
basic processes for creating and running applications with ADT, as described in which provides an overview of the Android testing framework.
<a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>.
You may also want to read
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a>,
which provides an overview of the Android testing framework.
</p> </p>
<p> <p>
ADT provides several features that help you set up and manage your testing environment ADT provides several features that help you set up and manage your testing environment
@@ -32,20 +27,20 @@ page.title=Testing In Eclipse, with ADT
<li> <li>
It lets you quickly create a test project and link it to the application under test. It lets you quickly create a test project and link it to the application under test.
When it creates the test project, it automatically inserts the necessary When it creates the test project, it automatically inserts the necessary
<code>&lt;instrumentation&gt;</code> element in the test application's manifest file. <code>&lt;instrumentation&gt;</code> element in the test package's manifest file.
</li> </li>
<li> <li>
It lets you quickly import the classes of the application under test, so that your It lets you quickly import the classes of the application under test, so that your
tests can inspect them. tests can inspect them.
</li> </li>
<li> <li>
It lets you create run configurations for your test application and include in It lets you create run configurations for your test package and include in
them flags that are passed to the Android testing framework. them flags that are passed to the Android testing framework.
</li> </li>
<li> <li>
It lets you run your test application without leaving Eclipse. ADT builds both the It lets you run your test package without leaving Eclipse. ADT builds both the
application under test and the test application automatically, installs them if application under test and the test package automatically, installs them if
necessary to your device or emulator, runs the test application, and displays the necessary to your device or emulator, runs the test package, and displays the
results in a separate window in Eclipse. results in a separate window in Eclipse.
</li> </li>
</ul> </ul>
@@ -55,305 +50,452 @@ page.title=Testing In Eclipse, with ADT
<a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a>. <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a>.
</p> </p>
<h2 id="CreateTestProjectEclipse">Creating a Test Project</h2> <h2 id="CreateTestProjectEclipse">Creating a Test Project</h2>
<p> <p>
To set up a test environment for your Android application, you must first create a separate To set up a test environment for your Android application, you must first create a separate
application project that holds the test code. The new project follows the directory structure project that holds the test code. The new project follows the directory structure
used for any Android application. It includes the same types of content and files, such as used for any Android application. It includes the same types of content and files, such as
source code, resources, a manifest file, and so forth. The test application you source code, resources, a manifest file, and so forth. The test package you
create is connected to the application under test by an create is connected to the application under test by an
<a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"> <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">
<code>&lt;instrumentation&gt;</code></a> element in its manifest file. <code>&lt;instrumentation&gt;</code></a> element in its manifest file.
</p> </p>
<p>
The <strong>New Android Test Project</strong> dialog makes it easy for you to generate a
new test project that has the proper structure, including the
<code>&lt;instrumentation&gt;</code> element in the manifest file. You can use the New Android
Test Project dialog to generate the test project at any time. The dialog appears just after you
create a new Android main application project, but you can also run it to create a test project
for a project that you created previously.
</p>
<p> <p>
To create a test project in Eclipse with ADT: The <em>New Android Test Project</em> dialog makes it easy for you to generate a
new test project that has the proper structure, including the
<code>&lt;instrumentation&gt;</code> element in the manifest file. You can use the New
Android Test Project dialog to generate the test project at any time. The dialog appears
just after you create a new Android main application project, but you can also run it to
create a test project for a project that you created previously.
</p>
<p>
To create a test project in Eclipse with ADT:
</p> </p>
<ol> <ol>
<li> <li>
In Eclipse, select <strong>File &gt; New &gt; Other</strong>. This In Eclipse, select <strong>File &gt; New &gt; Other</strong>. This opens the <em>Select a
opens the Select a Wizard dialog. Wizard</em> dialog.
</li> </li>
<li> <li>
In the dialog, in the Wizards drop-down list, In the dialog, in the <em>Wizards</em> drop-down list, find the entry for Android, then
find the entry for Android, then click the toggle to the left. Select click the toggle to the left. Select <strong>Android Test Project</strong>, then at the
Android Test Project, then at the bottom bottom of the dialog click <strong>Next</strong>. The <em>New Android Test Project</em>
of the dialog click Next. The New Android Test Project wizard appears. wizard appears.
</li> </li>
<li> <li>
Enter a project name. You may use any name, but you may want to Next to <em>Test Project Name</em>, enter a name for the project. You may use any name,
associate the name with the project name for your Application. One but you may want to associate the name with the project name for the application under test.
way to do this is to take the Application's project name, append the One way to do this is to take the application's project name, append the string "Test" to
string "Test" to it, and then use this as the test case project name. it, and then use this as the test package project name.
</li> <p>
<li> The name becomes part of the suggested project path, but you can change this in the
In the Test Target panel, set next step.
An Existing Android Project, click </p>
Browse, then select your Android application from </li>
the list. You now see that the wizard has completed the Test <li>
Target Package, Application Name, and In the <em>Content</em> panel, examine the suggested path to the project.
Package Name fields for you (the latter two are in If <em>Use default location</em> is set, then the wizard will suggest a path that is
the Properties panel). a concatenation of the workspace path and the project name you entered. For example,
</li> if your workspace path is <code>/usr/local/workspace</code> and your project name is
<li> <code>MyTestApp</code>, then the wizard will suggest
In the Build Target panel, select the Android SDK <code>/usr/local/workspace/MyTestApp</code>. To enter your own
platform that you will use to test your application. Make this the same as the choice for a path, unselect <em>Use default location</em>, then enter or browse to the
build target of the application under test. path where you want your project.
</li> <p>
<li> To learn more about choosing the location of test projects, please read
Click Finish to complete the wizard. If <a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjectPaths">
Finish is disabled, look Testing Fundamentals</a>.
for error messages at the top of the wizard dialog, and then fix </p>
any problems. </li>
</li> <li>
In the Test Target panel, set An Existing Android Project, click Browse, then select your
Android application from the list. You now see that the wizard has completed the Test
Target Package, Application Name, and Package Name fields for you (the latter two are in
the Properties panel).
</li>
<li>
In the Build Target panel, select the Android SDK platform that the application under test
uses.
</li>
<li>
Click Finish to complete the wizard. If Finish is disabled, look for error messages at the
top of the wizard dialog, and then fix any problems.
</li>
</ol>
<h2 id="CreateTestAppEclipse">Creating a Test Package</h2>
<p>
Once you have created a test project, you populate it with a test package. This package does not
require an Activity, although you can define one if you wish. Although your test package can
combine Activity classes, test case classes, or ordinary classes, your main test case
should extend one of the Android test case classes or JUnit classes, because these provide the
best testing features.
</p>
<p>
Test packages do not need to have an Android GUI. When you run the package in
Eclipse with ADT, its results appear in the JUnit view. Running tests and seeing the results is
described in more detail in the section <a href="#RunTestEclipse">Running Tests</a>.
</p>
<p>
To create a test package, start with one of Android's test case classes defined in
{@link android.test android.test}. These extend the JUnit
{@link junit.framework.TestCase TestCase} class. The Android test classes for Activity objects
also provide instrumentation for testing an Activity. To learn more about test case
classes, please read the topic <a href="{@docRoot}guide/topics/testing/testing_android.html">
Testing Fundamentals</a>.
</p>
<p>
Before you create your test package, you choose the Java package identifier you want to use
for your test case classes and the Android package name you want to use. To learn more
about this, please read
<a href="{@docRoot}guide/topics/testing/testing_android.html#PackageNames">
Testing Fundamentals</a>.
</p>
<p>
To add a test case class to your project:
</p>
<ol>
<li>
In the <em>Project Explorer</em> tab, open your test project, then open the <em>src</em>
folder.
</li>
<li>
Find the Java package identifier set by the projection creation wizard. If you haven't
added classes yet, this node won't have any children, and its icon will not be filled in.
If you want to change the identifier value, right-click the identifier and select
<strong>Refactor</strong> &gt; <strong>Rename</strong>, then enter the new name.
</li>
<li>
When you are ready, right-click the Java package identifier again and select
<strong>New</strong> &gt; <strong>Class</strong>. This displays the <em>New Java Class</em>
dialog, with the <em>Source folder</em> and <em>Package</em> values already set.
</li>
<li>
In the <em>Name</em> field, enter a name for the test case class. One way to choose a
class name is to append the string "Test" to the class of the component you are testing.
For example, if you are testing the class MyAppActivity, your test case class
name would be MyAppActivityTest. Leave the modifiers set to <em>public</em>.
</li>
<li>
In the <em>Superclass</em> field, enter the name of the Android test case class you
are extending. You can also browse the available classes.
</li>
<li>
In <em>Which method stubs would you like to create?</em>, unset all the options, then
click <strong>Finish</strong>. You will set up the constructor manually.
</li>
<li>
Your new class appears in a new Java editor pane.
</li>
</ol> </ol>
<p> <p>
You now have to ensure that the constructor is set up correctly. Create a constructor for your
</p> class that has no arguments; this is required by JUnit. As the first statement in this
<h2 id="CreateTestAppEclipse">Creating a Test Application</h2> constructor, add a call to the base class' constructor. Each base test case class has its
<p> own constructor signature. Refer to the class documentation in the documentation for
Once you have created a test project, you populate it with a test {@link android.test} for more information.
Android application. This application does not require an {@link android.app.Activity Activity},
although you can define one if you wish. Although your test application can
combine Activities, Android test class extensions, JUnit extensions, or
ordinary classes, you should extend one of the Android test classes or JUnit classes,
because these provide the best testing features.
</p> </p>
<p> <p>
Test applications do not have an Android GUI. Instead, when you run the application in To control your test environment, you will want to override the <code>setUp()</code> and
Eclipse with ADT, its results appear in the JUnit view. If you run <code>tearDown()</code> methods:
your tests with {@link android.test.InstrumentationTestRunner InstrumentationTestRunner} (or a related test runner),
then it will run all the methods in each class. You can modify this behavior
by using the {@link junit.framework.TestSuite TestSuite} class.
</p>
<p>
To create a test application, start with one of Android's test classes in the Java package {@link android.test android.test}.
These extend the JUnit {@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test classes
also provide instrumentation for testing.
</p>
<p>
For test classes that extend {@link junit.framework.TestCase TestCase}, you probably want to override
the <code>setUp()</code> and <code>tearDown()</code> methods:
</p> </p>
<ul> <ul>
<li> <li>
<code>setUp()</code>: This method is invoked before any of the test methods in the class. <code>setUp()</code>: This method is invoked before any of the test methods in the class.
Use it to set up the environment for the test. You can use <code>setUp()</code> Use it to set up the environment for the test (the test fixture. You can use
to instantiate a new <code>Intent</code> object with the action <code>ACTION_MAIN</code>. You can <code>setUp()</code> to instantiate a new Intent with the action <code>ACTION_MAIN</code>.
then use this intent to start the Activity under test. You can then use this intent to start the Activity under test.
<p class="note"><strong>Note:</strong> If you override this method, call </li>
<code>super.setUp()</code> as the first statement in your code. <li>
</p> <code>tearDown()</code>: This method is invoked after all the test methods in the class. Use
</li> it to do garbage collection and to reset the test fixture.
<li> </li>
<code>tearDown()</code>: This method is invoked after all the test methods in the class. Use
it to do garbage collection and re-setting before moving on to the next set of tests.
<p class="note"><strong>Note:</strong> If you override this method, you must call
<code>super.tearDown()</code> as the <em>last</em> statement in your code.</p>
</li>
</ul> </ul>
<p> <p>
Another useful convention is to add the method <code>testPreConditions()</code> to your test Another useful convention is to add the method <code>testPreconditions()</code> to your test
class. Use this method to test that the application under test is initialized correctly. If this class. Use this method to test that the application under test is initialized correctly. If this
test fails, you know that that the initial conditions were in error. When this happens, further test test fails, you know that that the initial conditions were in error. When this happens, further
results are suspect, regardless of whether or not the tests succeeded. test results are suspect, regardless of whether or not the tests succeeded.
</p> </p>
<p> <p>
The Resources tab contains an <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> The Resources tab contains an
tutorial with more information about creating test classes and methods. <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
tutorial with more information about creating test classes and methods.
</p> </p>
<h2 id="RunTestEclipse">Running Tests</h2> <h2 id="RunTestEclipse">Running Tests</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Running tests from the command line</h2>
<p>
If you've created your tests in Eclipse, you can still run your tests and test
suites by using command-line tools included with the Android SDK. You may want
to do this, for example, if you have a large number of tests to run, if you
have a large test case, or if you want a fine level of control over which
tests are run at a particular time.
</p>
<p>
To run tests created in Eclipse with ADT with command-line tools, you must first
install additional files into the test project using the <code>android</code>
tool's "create test-project" option. To see how to do this, read
<a href="{@docRoot}guide/developing/testing/testing_otheride.html#CreateProject">
Testing in Other IDEs</a>.
</p>
</div>
</div>
<p>
When you run a test package in Eclipse with ADT, the output appears in the Eclipse JUnit view.
You can run the entire test package or one test case class. To do run tests, Eclipse runs the
<code>adb</code> command for running a test package, and displays the output, so there is no
difference between running tests inside Eclipse and running them from the command line.
</p>
<p>
As with any other package, to run a test package in Eclipse with ADT you must either attach a
device to your computer or use the Android emulator. If you use the emulator, you must have an
Android Virtual Device (AVD) that uses the same target as the test package.
</p>
<p>
To run a test in Eclipse, you have two choices:</p>
<ul>
<li>
Run a test just as you run an application, by selecting
<strong>Run As... &gt; Android JUnit Test</strong> from the project's context menu or
from the main menu's <strong>Run</strong> item.
</li>
<li>
Create an Eclipse run configuration for your test project. This is useful if you want
multiple test suites, each consisting of selected tests from the project. To run
a test suite, you run the test configuration.
<p>
Creating and running test configurations is described in the next section.
</p>
</li>
</ul>
<p>
To create and run a test suite using a run configuration:
</p>
<ol>
<li>
In the Package Explorer, select the test project, then from the main menu, select
<strong>Run &gt; Run Configurations...</strong>. The Run Configurations dialog appears.
</li>
<li>
In the left-hand pane, find the Android JUnit Test entry. In the right-hand pane, click the
Test tab. The Name: text box shows the name of your project. The Test class: dropdown box
shows one of the test classes in your project.
</li>
<li>
To run one test class, click Run a single test, then enter your project name in the
Project: text box and the class name in the Test class: text box.
<p>
To run all the test classes, click Run all tests in the selected project or package,
then enter the project or package name in the text box.
</p>
</li>
<li>
Now click the Target tab.
<ul>
<li>
Optional: If you are using the emulator, click Automatic, then in the Android
Virtual Device (AVD) selection table, select an existing AVD.
</li>
<li>
In the Emulator Launch Parameters pane, set the Android emulator flags you want to
use. These are documented in the topic
<a href="{@docRoot}guide/developing/tools/emulator.html#startup-options">
Android Emulator</a>.
</li>
</ul>
</li>
<li>
Click the Common tab. In the Save As pane, click Local to save this run configuration
locally, or click Shared to save it to another project.
</li>
<li>
Optional: Add the configuration to the Run toolbar and the <strong>Favorites</strong>
menu: in the Display in Favorites pane click the checkbox next to Run.
</li>
<li>
Optional: To add this configuration to the <strong>Debug</strong> menu and toolbar, click
the checkbox next to Debug.
</li>
<li>
To save your settings, click Close.<br/>
<p class="note"><strong>Note:</strong>
Although you can run the test immediately by clicking Run, you should save the test
first and then run it by selecting it from the Eclipse standard toolbar.
</p>
</li>
<li>
On the Eclipse standard toolbar, click the down arrow next to the green Run arrow. This
displays a menu of saved Run and Debug configurations.
</li>
<li>
Select the test run configuration you just created. The test starts.
</li>
</ol>
<p>
The progress of your test appears in the Console view as a series of messages. Each message is
preceded by a timestamp and the <code>.apk</code> filename to which it applies. For example,
this message appears when you run a test to the emulator, and the emulator is not yet started:
</p>
<div class="sidebox-wrapper"> <div class="sidebox-wrapper">
<div class="sidebox"> <div class="sidebox">
<h2>Running tests from the command line</h2> <h2>Message Examples</h2>
<p> <p>
If you've created your tests in Eclipse, you can still run your tests and test The examples shown in this section come from the
suites by using command-line tools included with the Android SDK. You may want to <a href="{@docRoot}resources/samples/SpinnerTest/index.html">SpinnerTest</a>
do this, for example, if you have a large number of tests to run, if you have a sample test package, which tests the
large test case, or if you want a fine level of control over which tests are run at <a href="{@docRoot}resources/samples/Spinner/index.html">Spinner</a>
a particular time. sample application. This test package is also featured in the
</p> <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
<p> tutorial.
To run tests created in Eclipse with ADT with command-line tools, you must first </p>
install additional files into the test project using the <code>android</code> tool's
"create test-project" option. To see how to do this, read the section
<a href="{@docRoot}guide/developing/testing/testing_otheride.html#CreateProject">
Creating a test project</a> in the topic
<a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other
IDEs</a>.
</p>
</div> </div>
</div> </div>
<pre>
[<em>yyyy-mm-dd hh:mm:ss</em> - <em>testfile</em>] Waiting for HOME ('android.process.acore') to be launched...
</pre>
<p> <p>
When you run a test application in Eclipse with ADT, the output appears in In the following description of these messages, <code><em>devicename</em></code> is the name of
an Eclipse view panel. You can run the entire test application, one class, or one the device or emulator you are using to run the test, and <code><em>port</em></code> is the
method of a class. To do this, Eclipse runs the <code>adb</code> command for running a test application, and port number for the device. The name and port number are in the format used by the
displays the output, so there is no difference between running tests inside Eclipse and running them from the command line. <code><a href="{@docRoot}guide/developing/tools/adb.html#devicestatus">adb devices</a></code>
command. Also, <code><em>testfile</em></code> is the <code>.apk</code> filename of the test
package you are running, and <em>appfile</em> is the filename of the application under test.
</p> </p>
<p> <ul>
As with any other application, to run a test application in Eclipse with ADT you must either attach a device to your <li>
computer or use the Android emulator. If you use the emulator, you must have an Android Virtual Device (AVD) that uses If you are using an emulator and you have not yet started it, then Eclipse
the same target first starts the emulator. When this is complete, you see
</p>
<p>
To run a test in Eclipse, you have two choices:</p>
<ol>
<li>
Run a test just as you run an application, by selecting
<strong>Run As... &gt; Android JUnit Test</strong> from the project's context menu or
from the main menu's <strong>Run</strong> item.
</li>
<li>
Create an Eclipse run configuration for your test project. This is useful if you want multiple test suites, each consisting of selected tests from the project. To run
a test suite, you run the test configuration.
<p>
Creating and running test configurations is described in the next section.
</p>
</li>
</ol>
<p>To create and run a test suite using a run configuration:</p>
<ol>
<li>
In the Package Explorer, select the test
project, then from the main menu, select
<strong>Run &gt; Run Configurations...</strong>. The
Run Configurations dialog appears.
</li>
<li>
In the left-hand pane, find the
Android JUnit Test entry.
In the right-hand pane, click the Test tab.
The Name: text box
shows the name of your project. The
Test class: dropdown box shows one your project's classes
test classes in your project.
</li>
<li>
To run one test class, click Run a single test, then enter your project
name in the Project: text box and the class name in the
Test class: text box.
<p>
To run all the test classes,
click Run all tests in the selected project or package,
then enter the project or package name in the text box.
</p>
</li>
<li>
Now click the Target tab.
<ul>
<li>
Optional: If you are using the emulator, click
Automatic, then in the Android Virtual Device (AVD)
selection table, select an existing AVD.
</li>
<li>
In the Emulator Launch Parameters pane, set the
Android emulator flags you want to use. These are documented in the topic
<a href="{@docRoot}guide/developing/tools/emulator.html#startup-options">Emulator Startup Options</a>.
</li>
</ul>
<li>
Click the Common tab. In the
Save As pane, click Local to save
this run configuration locally, or click Shared to
save it to another project.
</li>
<li>
Optional: Add the configuration to the Run toolbar and the <strong>Favorites</strong>
menu: in the Display in Favorites pane
click the checkbox next to Run.
</li>
<li>
Optional: To add this configuration to the <strong>Debug</strong> menu and toolbar, click
the checkbox next to Debug.
</li>
<li>
To save your settings, click Close.<br/>
<p class="note"><strong>Note:</strong> Although you can run the test immediately by
clicking Run, you should save the test first and then
run it by selecting it from the Eclipse standard toolbar.</p>
</li>
<li>
On the Eclipse standard toolbar, click the down arrow next to the
green Run arrow. This displays a menu of saved Run and Debug
configurations.
</li>
<li>
Select the test run configuration you just created.
</li>
<li>
The progress of your test appears in the Console view.
You should see the following messages, among others:
<ul>
<li>
<code>Performing Android.test.InstrumentationTestRunner JUnit launch</code><br>
The class name that proceeds "JUnit" depends on the Android instrumentation
class you have chosen.
</li>
<li>
If you are using an emulator and you have not yet started it, then you will see
the message: the message:
<p> <p>
<code>Automatic Target Mode: launching new emulator with compatible <code>HOME is up on device '<em>devicename</em>-<em>port</em>'</code>
AVD <em>avdname</em></code><br>(where <em>avdname</em> is the name of
the AVD you are using.)
</p> </p>
</li> </li>
<li> <li>
If you have not already installed your test application, then you will see If you have not already installed your test package, then you see
the message: the message:
<p> <p>
<code>Uploading <em>testclass</em>.apk onto device '<em>device-id</em>'</code><br> <code>Uploading <em>testfile</em> onto device '<em>devicename</em>-<em>port</em>'
where <em>testclass</em> is the name of your unit test class and <em>device-id</em> </code>
is the name and port for your test device or emulator, followed by the message <code>Installing <em>testclass</em>.apk</code>
</p> </p>
</li> <p>
<li> then the message <code>Installing <em>testfile</em></code>.
<code>Launching instrumentation Android.test.InstrumentationTestRunner on device <em>device-id</em></code>.<br> </p>
This indicates that Android's Instrumentation system is now testing your code. Again, the <p>
instrumentation class name depends on the Android instrumentation class you have chosen. and finally the message <code>Success!</code>
</li> </p>
<li> </li>
<code>Test run complete</code>.<br> When you see this, your unit tests have finished. </ul>
</li>
</ul>
</ol>
<p> <p>
The test results appear in the JUnit view. This is divided into an upper summary pane, The following lines are an example of this message sequence:
and a lower stack trace pane. </p>
<code>
[2010-07-01 12:44:40 - MyTest] HOME is up on device 'emulator-5554'<br>
[2010-07-01 12:44:40 - MyTest] Uploading MyTest.apk onto device 'emulator-5554'<br>
[2010-07-01 12:44:40 - MyTest] Installing MyTest.apk...<br>
[2010-07-01 12:44:49 - MyTest] Success!<br>
</code>
<br>
<ul>
<li>
Next, if you have not yet installed the application under test to the device or
emulator, you see the message
<p>
<code>Project dependency found, installing: <em>appfile</em></code>
</p>
<p>
then the message <code>Uploading <em>appfile</em></code> onto device
'<em>devicename</em>-<em>port</em>'
</p>
<p>
then the message <code>Installing <em>appfile</em></code>
</p>
<p>
and finally the message <code>Success!</code>
</p>
</li>
</ul>
<p>
The following lines are an example of this message sequence:
</p>
<code>
[2010-07-01 12:44:49 - MyTest] Project dependency found, installing: MyApp<br>
[2010-07-01 12:44:49 - MyApp] Uploading MyApp.apk onto device 'emulator-5554'<br>
[2010-07-01 12:44:49 - MyApp] Installing MyApp.apk...<br>
[2010-07-01 12:44:54 - MyApp] Success!<br>
</code>
<br>
<ul>
<li>
Next, you see the message
<code>Launching instrumentation <em>instrumentation_class</em> on device
<em>devicename</em>-<em>port</em></code>
<p>
<code>instrumentation_class</code> is the fully-qualified class name of the
instrumentation test runner you have specified (usually
{@link android.test.InstrumentationTestRunner}.
</p>
</li>
<li>
Next, as {@link android.test.InstrumentationTestRunner} builds a list of tests to run,
you see the message
<p>
<code>Collecting test information</code>
</p>
<p>
followed by
</p>
<p>
<code>Sending test information to Eclipse</code>
</p>
</li>
<li>
Finally, you see the message <code>Running tests</code>, which indicates that your tests
are running. At this point, you should start seeing the test results in the JUnit view.
When the tests are finished, you see the console message <code>Test run complete</code>.
This indicates that your tests are finished.
</li>
</ul>
<p>
The following lines are an example of this message sequence:
</p>
<code>
[2010-01-01 12:45:02 - MyTest] Launching instrumentation android.test.InstrumentationTestRunner on device emulator-5554<br>
[2010-01-01 12:45:02 - MyTest] Collecting test information<br>
[2010-01-01 12:45:02 - MyTest] Sending test information to Eclipse<br>
[2010-01-01 12:45:02 - MyTest] Running tests...<br>
[2010-01-01 12:45:22 - MyTest] Test run complete<br>
</code>
<br>
<p>
The test results appear in the JUnit view. This is divided into an upper summary pane,
and a lower stack trace pane.
</p> </p>
<p> <p>
The upper pane contains test information. In the pane's header, you see the following The upper pane contains test information. In the pane's header, you see the following
information: information:
</p> </p>
<ul> <ul>
<li> <li>
Total time elapsed for the test application (labeled Finished after <em>x</em> seconds). Total time elapsed for the test package (labeled Finished after <em>x</em> seconds).
</li> </li>
<li> <li>
Number of runs (Runs:) - the number of tests in the entire test class. Number of runs (Runs:) - the number of tests in the entire test class.
</li> </li>
<li> <li>
Number of errors (Errors:) - the number of program errors and exceptions encountered Number of errors (Errors:) - the number of program errors and exceptions encountered
during the test run. during the test run.
</li> </li>
<li> <li>
Number of failures (Failures:) - the number of test failures encountered during the test Number of failures (Failures:) - the number of test failures encountered during the test
run. This is the number of assertion failures. A test can fail even if the program does run. This is the number of assertion failures. A test can fail even if the program does
not encounter an error. not encounter an error.
</li> </li>
<li> <li>
A progress bar. The progress bar extends from left to right as the tests run. If all the A progress bar. The progress bar extends from left to right as the tests run. If all the
tests succeed, the bar remains green. If a test fails, the bar turns from green to red. tests succeed, the bar remains green. If a test fails, the bar turns from green to red.
</li> </li>
</ul> </ul>
<p> <p>
The body of the upper pane contains the details of the test run. For each test case class The body of the upper pane contains the details of the test run. For each test case class
that was run, you see a line with the class name. To look at the results for the individual that was run, you see a line with the class name. To look at the results for the individual
@@ -362,9 +504,31 @@ page.title=Testing In Eclipse, with ADT
If you double-click the method name, Eclipse opens the test class source in an editor view If you double-click the method name, Eclipse opens the test class source in an editor view
pane and moves the focus to the first line of the test method. pane and moves the focus to the first line of the test method.
</p> </p>
<p>
The results of a successful test are shown in
<a href="#TestResults">Figure 1. Messages for a successful test</a>:
</p>
<a href="{@docRoot}images/testing/eclipse_test_results.png">
<img src="{@docRoot}images/testing/eclipse_test_results.png"
alt="Messages for a successful test" height="327px" id="TestResults"/>
</a>
<p class="img-caption">
<strong>Figure 1.</strong> Messages for a successful test
</p>
<p> <p>
The lower pane is for stack traces. If you highlight a failed test in the upper pane, the The lower pane is for stack traces. If you highlight a failed test in the upper pane, the
lower pane contains a stack trace for the test. If a line corresponds to a point in your lower pane contains a stack trace for the test. If a line corresponds to a point in your
test code, you can double-click it to display the code in an editor view pane, with the test code, you can double-click it to display the code in an editor view pane, with the
line highlighted. For a successful test, the lower pane is empty. line highlighted. For a successful test, the lower pane is empty.
</p> </p>
<p>
The results of a failed test are shown in
<a href="#FailedTestResults">Figure 2. Messages for a test failure</a>
</p>
<a href="{@docRoot}images/testing/eclipse_test_run_failure.png">
<img src="{@docRoot}images/testing/eclipse_test_run_failure.png"
alt="Messages for a test failure" height="372px" id="TestRun"/>
</a>
<p class="img-caption">
<strong>Figure 2.</strong> Messages for a test failure
</p>

629
docs/html/guide/developing/testing/testing_otheride.jd
View File

@@ -2,122 +2,128 @@ page.title=Testing In Other IDEs
@jd:body @jd:body
<div id="qv-wrapper"> <div id="qv-wrapper">
<div id="qv"> <div id="qv">
<h2>In this document</h2> <h2>In this document</h2>
<ol> <ol>
<li> <li>
<a href="#CreateTestProjectCommand">Working with Test Projects</a> <a href="#CreateTestProjectCommand">Working with Test Projects</a>
<ol> <ol>
<li> <li>
<a href="#CreateTestProject">Creating a test project</a> <a href="#CreateTestProject">Creating a test project</a>
</li> </li>
<li> <li>
<a href="#UpdateTestProject">Updating a test project</a> <a href="#UpdateTestProject">Updating a test project</a>
</li> </li>
</ol> </ol>
</li> </li>
<li> <li>
<a href="#CreateTestApp">Creating a Test Application</a> <a href="#CreateTestApp">Creating a Test Package</a>
</li> </li>
<li> <li>
<a href="#RunTestsCommand">Running Tests</a> <a href="#RunTestsCommand">Running Tests</a>
<ol> <ol>
<li> <li>
<a href="#RunTestsAnt">Quick build and run with Ant</a> <a href="#RunTestsAnt">Quick build and run with Ant</a>
</li> </li>
<li> <li>
<a href="#RunTestsDevice">Running tests on a device or emulator</a> <a href="#RunTestsDevice">Running tests on a device or emulator</a>
</li> </li>
</ol> </ol>
</li> </li>
<li> <li>
<a href="#AMSyntax">Using the Instrument Command</a> <a href="#AMSyntax">Using the Instrument Command</a>
<ol> <ol>
<li> <li>
<a href="#AMOptionsSyntax">Instrument options</a> <a href="#AMOptionsSyntax">Instrument options</a>
</li> </li>
<li> <li>
<a href="#RunTestExamples">Instrument examples</a> <a href="#RunTestExamples">Instrument examples</a>
</li> </li>
</ol> </ol>
</li> </li>
</ol>
</ol> <h2>See Also</h2>
<h2>See Also</h2> <ol>
<ol> <li>
<li> <a href="{@docRoot}guide/topics/testing/testing_android.html">
<a Testing Fundamentals</a>
href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a> </li>
</li> <li>
<li> <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>
<a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> </li>
</li> </ol>
<li> </div>
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>
</li>
</ol>
</div>
</div> </div>
<p> <p>
This document describes how to create and run tests directly from the command line. This document describes how to create and run tests directly from the command line.
You can use the techniques described here if you are developing in an IDE other than Eclipse You can use the techniques described here if you are developing in an IDE other than Eclipse
or if you prefer to work from the command line. This document assumes that you already know how or if you prefer to work from the command line. This document assumes that you already know how
to create a Android application in your programming environment. Before you start this to create a Android application in your programming environment. Before you start this
document, you should read the document <a document, you should read the topic
href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a>, <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
which provides an overview of Android testing. which provides an overview of Android testing.
</p> </p>
<p> <p>
If you are developing in Eclipse with ADT, you can set up and run your tests If you are developing in Eclipse with ADT, you can set up and run your tests
directly in Eclipse. For more information, please read <a directly in Eclipse. For more information, please read
href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing&nbsp;in&nbsp;Eclipse,&nbsp;with&nbsp;ADT</a>. <a href="{@docRoot}guide/developing/testing/testing_eclipse.html">
Testing in Eclipse, with ADT</a>.
</p> </p>
<h2 id="CreateTestProjectCommand">Working with Test Projects</h2> <h2 id="CreateTestProjectCommand">Working with Test Projects</h2>
<p> <p>
You use the <code>android</code> tool to create test projects. You use the <code>android</code> tool to create test projects.
You also use <code>android</code> to convert existing test code into an Android test project, You also use <code>android</code> to convert existing test code into an Android test project,
or to add the <code>run-tests</code> Ant target to an existing Android test project. or to add the <code>run-tests</code> Ant target to an existing Android test project.
These operations are described in more detail in the section <a These operations are described in more detail in the section <a href="#UpdateTestProject">
href="#UpdateTestProject">Updating a test project</a>. Updating a test project</a>. The <code>run-tests</code> target is described in
The <code>run-tests</code> target is described in <a <a href="#RunTestsAnt">Quick build and run with Ant</a>.
href="#RunTestsAnt">Quick build and run with Ant</a>.
</p> </p>
<h3 id="CreateTestProject">Creating a test project</h3> <h3 id="CreateTestProject">Creating a test project</h3>
<p> <p>
To create a test project with the <code>android</code> tool, enter: To create a test project with the <code>android</code> tool, enter:
<pre>android create test-project -m &lt;main_path&gt; -n &lt;project_name&gt; -p &lt;test_path&gt;</pre> </p>
<pre>
android create test-project -m &lt;main_path&gt; -n &lt;project_name&gt; -p &lt;test_path&gt;
</pre>
<p> <p>
You must supply all the flags. The following table explains them in detail: You must supply all the flags. The following table explains them in detail:
</p> </p>
<table> <table>
<tr> <tr>
<th>Flag</th> <th>Flag</th>
<th>Value</th> <th>Value</th>
<th>Description</th> <th>Description</th>
<tr> </tr>
<td><code>-m, --main</code></td> <tr>
<td> <td><code>-m, --main</code></td>
Path to the project of the application under test, relative to the test application <td>
directory. Path to the project of the application under test, relative to the test package
</td> directory.
<td>
For example, if the application under test is in <code>source/HelloAndroid</code>, and you
want to create the test project in <code>source/HelloAndroidTest</code>, then the value of
<code>--main</code> should be <code>../HelloAndroid</code>.
</td> </td>
<tr> <td>
<td><code>-n, --name</code></td> For example, if the application under test is in <code>source/HelloAndroid</code>, and
<td>Name that you want to give the test project.</td> you want to create the test project in <code>source/HelloAndroidTest</code>, then the
<td>&nbsp;</td> value of <code>--main</code> should be <code>../HelloAndroid</code>.
</tr> <p>
<tr> To learn more about choosing the location of test projects, please read
<td><code>-p, --path</code></td> <a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjects">
<td>Directory in which you want to create the new test project.</td> Testing Fundamentals</a>.
<td> </p>
The <code>android</code> tool creates the test project files and directory structure in this </td>
directory. If the directory does not exist, <code>android</code> creates it. </tr>
</td> <tr>
</tr> <td><code>-n, --name</code></td>
<td>Name that you want to give the test project.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>-p, --path</code></td>
<td>Directory in which you want to create the new test project.</td>
<td>
The <code>android</code> tool creates the test project files and directory structure
in this directory. If the directory does not exist, <code>android</code> creates it.
</td>
</tr>
</table> </table>
<p> <p>
If the operation is successful, <code>android</code> lists to STDOUT the names of the files If the operation is successful, <code>android</code> lists to STDOUT the names of the files
@@ -135,11 +141,10 @@ directly in Eclipse. For more information, please read <a
are testing and control it with instrumentation. are testing and control it with instrumentation.
</p> </p>
<p> <p>
For example, suppose you create the <a For example, suppose you create the <a href="{@docRoot}resources/tutorials/hello-world.html">
href="{@docRoot}resources/tutorials/hello-world.html">Hello, World</a> tutorial application Hello, World</a> tutorial application in the directory <code>~/source/HelloAndroid</code>.
in the directory <code>~/source/HelloAndroid</code>. In the tutorial, this application uses the In the tutorial, this application uses the package name <code>com.example.helloandroid</code>
package name <code>com.example.helloandroid</code> and the activity name and the activity name <code>HelloAndroid</code>. You can to create the test for this in
<code>HelloAndroid</code>. You can to create the test for this in
<code>~/source/HelloAndroidTest</code>. To do so, you enter: <code>~/source/HelloAndroidTest</code>. To do so, you enter:
</p> </p>
<pre> <pre>
@@ -196,7 +201,7 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd
<p class="note"> <p class="note">
<strong>Note:</strong> If you change the Android package name of the application under test, <strong>Note:</strong> If you change the Android package name of the application under test,
you must <em>manually</em> change the value of the <code>&lt;android:targetPackage&gt;</code> you must <em>manually</em> change the value of the <code>&lt;android:targetPackage&gt;</code>
attribute within the <code>AndroidManifest.xml</code> file of the test application. attribute within the <code>AndroidManifest.xml</code> file of the test package.
Running <code>android update test-project</code> does not do this. Running <code>android update test-project</code> does not do this.
</p> </p>
<p> <p>
@@ -205,38 +210,38 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd
<pre>android update-test-project -m &lt;main_path&gt; -p &lt;test_path&gt;</pre> <pre>android update-test-project -m &lt;main_path&gt; -p &lt;test_path&gt;</pre>
<table> <table>
<tr> <tr>
<th>Flag</th> <th>Flag</th>
<th>Value</th> <th>Value</th>
<th>Description</th> <th>Description</th>
</tr> </tr>
<tr> <tr>
<td><code>-m, --main</code></td> <td><code>-m, --main</code></td>
<td>The path to the project of the application under test, relative to the test project</td> <td>The path to the project of the application under test, relative to the test project</td>
<td> <td>
For example, if the application under test is in <code>source/HelloAndroid</code>, and For example, if the application under test is in <code>source/HelloAndroid</code>, and
the test project is in <code>source/HelloAndroidTest</code>, then the value for the test project is in <code>source/HelloAndroidTest</code>, then the value for
<code>--main</code> is <code>../HelloAndroid</code>. <code>--main</code> is <code>../HelloAndroid</code>.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>-p, --path</code></td> <td><code>-p, --path</code></td>
<td>The of the test project.</td> <td>The of the test project.</td>
<td> <td>
For example, if the test project is in <code>source/HelloAndroidTest</code>, then the For example, if the test project is in <code>source/HelloAndroidTest</code>, then the
value for <code>--path</code> is <code>HelloAndroidTest</code>. value for <code>--path</code> is <code>HelloAndroidTest</code>.
</td> </td>
</tr> </tr>
</table> </table>
<p> <p>
If the operation is successful, <code>android</code> lists to STDOUT the names of the files If the operation is successful, <code>android</code> lists to STDOUT the names of the files
and directories it has created. and directories it has created.
</p> </p>
<h2 id="CreateTestApp">Creating a Test Application</h2> <h2 id="CreateTestApp">Creating a Test Package</h2>
<p> <p>
Once you have created a test project, you populate it with a test application. Once you have created a test project, you populate it with a test package.
The application does not require an {@link android.app.Activity Activity}, The application does not require an {@link android.app.Activity Activity},
although you can define one if you wish. Although your test application can although you can define one if you wish. Although your test package can
combine Activities, Android test class extensions, JUnit extensions, or combine Activities, Android test class extensions, JUnit extensions, or
ordinary classes, you should extend one of the Android test classes or JUnit classes, ordinary classes, you should extend one of the Android test classes or JUnit classes,
because these provide the best testing features. because these provide the best testing features.
@@ -248,7 +253,7 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd
</p> </p>
<p> <p>
To create a test application, start with one of Android's test classes in the Java package To create a test package, start with one of Android's test classes in the Java package
{@link android.test android.test}. These extend the JUnit {@link android.test android.test}. These extend the JUnit
{@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test {@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test
classes also provide instrumentation for testing. classes also provide instrumentation for testing.
@@ -282,24 +287,17 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd
test results are suspect, regardless of whether or not the tests succeeded. test results are suspect, regardless of whether or not the tests succeeded.
</p> </p>
<p> <p>
To learn more about creating test applications, see the topic <a To learn more about creating test packages, see the topic <a
href="{@docRoot}guide/topics/testing/testing_android.html">Testing and Instrumentation</a>, href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
which provides an overview of Android testing. If you prefer to follow a tutorial, which provides an overview of Android testing. If you prefer to follow a tutorial,
try the <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> try the <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
tutorial, which leads you through the creation of tests for an actual Android application. tutorial, which leads you through the creation of tests for an actual Android application.
</p> </p>
<h2 id="RunTestsCommand">Running Tests</h2> <h2 id="RunTestsCommand">Running Tests</h2>
<p> <p>
If you are not developing in Eclipse with ADT, you need to run tests from the command line. You run tests from the command line, either with Ant or with an
You can do this either with Ant or with the {@link android.app.ActivityManager ActivityManager} <a href="{@docRoot}http://developer.android.com/guide/developing/tools/adb.html">
command line interface. Android Debug Bridge (adb)</a> shell.
</p>
<p>
You can also run tests from the command line even if you are using Eclipse with ADT to develop
them. To do this, you need to create the proper files and directory structure in the test
project, using the <code>android</code> tool with the option <code>create test-project</code>.
This is described in the section <a
href="#CreateTestProjectCommand">Working with Test Projects</a>.
</p> </p>
<h3 id="RunTestsAnt">Quick build and run with Ant</h3> <h3 id="RunTestsAnt">Quick build and run with Ant</h3>
<p> <p>
@@ -316,57 +314,63 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd
You can update an existing test project to use this feature. To do this, use the You can update an existing test project to use this feature. To do this, use the
<code>android</code> tool with the <code>update test-project</code> option. This is described <code>android</code> tool with the <code>update test-project</code> option. This is described
in the section <a href="#UpdateTestProject">Updating a test project</a>. in the section <a href="#UpdateTestProject">Updating a test project</a>.
</p>
<h3 id="RunTestsDevice">Running tests on a device or emulator</h3> <h3 id="RunTestsDevice">Running tests on a device or emulator</h3>
<p> <p>
When you run tests from the command line with the ActivityManager (<code>am</code>) When you run tests from the command line with
command-line tool, you get more options for choosing the tests to run than with any other <a href="{@docRoot}http://developer.android.com/guide/developing/tools/adb.html">
method. You can select individual test methods, filter tests according to their annotation, or Android Debug Bridge (adb)</a>, you get more options for choosing the tests
specify testing options. Since the test run is controlled entirely from a command line, you can to run than with any other method. You can select individual test methods, filter tests
customize your testing with shell scripts in various ways. according to their annotation, or specify testing options. Since the test run is controlled
entirely from a command line, you can customize your testing with shell scripts in various ways.
</p> </p>
<p> <p>
You run the <code>am</code> tool on an Android device or emulator using the To run a test from the command line, you run <code>adb shell</code> to start a command-line
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> shell on your device or emulator, and then in the shell run the <code>am instrument</code>
(<code>adb</code>) shell. When you do this, you use the ActivityManager command. You control <code>am</code> and your tests with command-line flags.
<code>instrument</code> option to run your test application using an Android test runner
(usually {@link android.test.InstrumentationTestRunner}). You set <code>am</code>
options with command-line flags.
</p> </p>
<p> <p>
To run a test with <code>am</code>: As a shortcut, you can start an <code>adb</code> shell, call <code>am instrument</code>, and
specify command-line flags all on one input line. The shell opens on the device or emulator,
runs your tests, produces output, and then returns to the command line on your computer.
</p>
<p>
To run a test with <code>am instrument</code>:
</p> </p>
<ol> <ol>
<li> <li>
If necessary, re-build your main application and test application. If necessary, rebuild your main application and test package.
</li> </li>
<li> <li>
Install your test application and main application Android package files Install your test package and main application Android package files
(<code>.apk</code> files) to your current Android device or emulator</li> (<code>.apk</code> files) to your current Android device or emulator</li>
<li> <li>
At the command line, enter: At the command line, enter:
<pre> <pre>
$ adb shell am instrument -w &lt;test_package_name&gt;/&lt;runner_class&gt; $ adb shell am instrument -w &lt;test_package_name&gt;/&lt;runner_class&gt;
</pre> </pre>
<p> <p>
where <code>&lt;test_package_name&gt;</code> is the Android package name of your test where <code>&lt;test_package_name&gt;</code> is the Android package name of your test
application, and <code>&lt;runner_class&gt;</code> is the name of the Android test runner application, and <code>&lt;runner_class&gt;</code> is the name of the Android test
class you are using. The Android package name is the value of the <code>package</code> runner class you are using. The Android package name is the value of the
attribute of the <code>manifest</code> element in the manifest file <code>package</code> attribute of the <code>manifest</code> element in the manifest file
(<code>AndroidManifest.xml</code>) of your test application. The Android test runner (<code>AndroidManifest.xml</code>) of your test package. The Android test runner
class is usually <code>InstrumentationTestRunner</code>. class is usually {@link android.test.InstrumentationTestRunner}.
</p> </p>
<p>Your test results appear in <code>STDOUT</code>.</p> <p>
</li> Your test results appear in <code>STDOUT</code>.
</p>
</li>
</ol> </ol>
<p> <p>
This operation starts an <code>adb</code> shell, then runs <code>am instrument</code> in it This operation starts an <code>adb</code> shell, then runs <code>am instrument</code>
with the specified parameters. This particular form of the command will run all of the tests with the specified parameters. This particular form of the command will run all of the tests
in your test application. You can control this behavior with flags that you pass to in your test package. You can control this behavior with flags that you pass to
<code>am instrument</code>. These flags are described in the next section. <code>am instrument</code>. These flags are described in the next section.
</p> </p>
<h2 id="AMSyntax">Using the Instrument Command</h2> <h2 id="AMSyntax">Using the am instrument Command</h2>
<p> <p>
The general syntax of the <code>am instrument</code> command is: The general syntax of the <code>am instrument</code> command is:
</p> </p>
<pre> <pre>
am instrument [flags] &lt;test_package&gt;/&lt;runner_class&gt; am instrument [flags] &lt;test_package&gt;/&lt;runner_class&gt;
@@ -391,11 +395,11 @@ $ adb shell am instrument -w &lt;test_package_name&gt;/&lt;runner_class&gt;
<code>&lt;test_package&gt;</code> <code>&lt;test_package&gt;</code>
</td> </td>
<td> <td>
The Android package name of the test application. The Android package name of the test package.
</td> </td>
<td> <td>
The value of the <code>package</code> attribute of the <code>manifest</code> The value of the <code>package</code> attribute of the <code>manifest</code>
element in the test application's manifest file. element in the test package's manifest file.
</td> </td>
</tr> </tr>
<tr> <tr>
@@ -411,7 +415,7 @@ $ adb shell am instrument -w &lt;test_package_name&gt;/&lt;runner_class&gt;
</tr> </tr>
</table> </table>
<p> <p>
The flags for <code>am instrument</code> are described in the following table: The flags for <code>am instrument</code> are described in the following table:
</p> </p>
<table> <table>
<tr> <tr>
@@ -461,20 +465,21 @@ The flags for <code>am instrument</code> are described in the following table:
&lt;test_options&gt; &lt;test_options&gt;
</td> </td>
<td> <td>
Provides testing options , in the form of key-value pairs. The Provides testing options as key-value pairs. The
<code>am instrument</code> tool passes these to the specified instrumentation class <code>am instrument</code> tool passes these to the specified instrumentation class
via its <code>onCreate()</code> method. You can specify multiple occurrences of via its <code>onCreate()</code> method. You can specify multiple occurrences of
<code>-e &lt;test_options</code>. The keys and values are described in the next table. <code>-e &lt;test_options&gt;</code>. The keys and values are described in the
section <a href="#AMOptionsSyntax">am instrument options</a>.
<p> <p>
The only instrumentation class that understands these key-value pairs is The only instrumentation class that uses these key-value pairs is
<code>InstrumentationTestRunner</code> (or a subclass). Using them with {@link android.test.InstrumentationTestRunner} (or a subclass). Using them with
any other class has no effect. any other class has no effect.
</p> </p>
</td> </td>
</tr> </tr>
</table> </table>
<h3 id="AMOptionsSyntax">Instrument options</h3> <h3 id="AMOptionsSyntax">am instrument options</h3>
<p> <p>
The <code>am instrument</code> tool passes testing options to The <code>am instrument</code> tool passes testing options to
<code>InstrumentationTestRunner</code> or a subclass in the form of key-value pairs, <code>InstrumentationTestRunner</code> or a subclass in the form of key-value pairs,
@@ -484,123 +489,127 @@ The flags for <code>am instrument</code> are described in the following table:
-e &lt;key&gt; &lt;value&gt; -e &lt;key&gt; &lt;value&gt;
</pre> </pre>
<p> <p>
Where applicable, a &lt;key&gt; may have multiple values separated by a comma (,). Some keys accept multiple values. You specify multiple values in a comma-separated list.
For example, this invocation of <code>InstrumentationTestRunner</code> provides multiple For example, this invocation of <code>InstrumentationTestRunner</code> provides multiple
values for the <code>package</code> key: values for the <code>package</code> key:
</p>
<pre> <pre>
$ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 com.android.test/android.test.InstrumentationTestRunner $ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
&gt; com.android.test/android.test.InstrumentationTestRunner
</pre> </pre>
<p> <p>
The following table describes the key-value pairs and their result. Please review the The following table describes the key-value pairs and their result. Please review the
<strong>Usage Notes</strong> following the table. <strong>Usage Notes</strong> following the table.
</p> </p>
<table> <table>
<tr> <tr>
<th>Key</th> <th>Key</th>
<th>Value</th> <th>Value</th>
<th>Description</th> <th>Description</th>
</tr> </tr>
<tr> <tr>
<td> <td>
<code>package</code> <code>package</code>
</td> </td>
<td> <td>
&lt;Java_package_name&gt; &lt;Java_package_name&gt;
</td> </td>
<td> <td>
The fully-qualified <em>Java</em> package name for one of the packages in the test The fully-qualified <em>Java</em> package name for one of the packages in the test
application. Any test case class that uses this package name is executed. Notice that this application. Any test case class that uses this package name is executed. Notice that
is not an <em>Android</em> package name; a test application has a single Android package this is not an <em>Android</em> package name; a test package has a single
name but may have several Java packages within it. Android package name but may have several Java packages within it.
</td> </td>
</tr> </tr>
<tr> <tr>
<td rowspan="2"><code>class</code></td> <td rowspan="2"><code>class</code></td>
<td>&lt;class_name&gt;</td> <td>&lt;class_name&gt;</td>
<td> <td>
The fully-qualified Java class name for one of the test case classes. Only this test case The fully-qualified Java class name for one of the test case classes. Only this test
class is executed. case class is executed.
</td> </td>
</tr> </tr>
<tr> <tr>
<td>&lt;class_name&gt;<strong>#</strong>method name</td> <td>&lt;class_name&gt;<strong>#</strong>method name</td>
<td> <td>
A fully-qualified test case class name, and one of its methods. Only this method is A fully-qualified test case class name, and one of its methods. Only this method is
executed. Note the hash mark (#) between the class name and the method name. executed. Note the hash mark (#) between the class name and the method name.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>func</code></td> <td><code>func</code></td>
<td><code>true</code></td> <td><code>true</code></td>
<td> <td>
Runs all test classes that extend {@link android.test.InstrumentationTestCase}. Runs all test classes that extend {@link android.test.InstrumentationTestCase}.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><code>unit</code></td> <td><code>unit</code></td>
<td><code>true</code></td> <td><code>true</code></td>
<td> <td>
Runs all test classes that do <em>not</em> extend either Runs all test classes that do <em>not</em> extend either
{@link android.test.InstrumentationTestCase} or {@link android.test.PerformanceTestCase}. {@link android.test.InstrumentationTestCase} or
</td> {@link android.test.PerformanceTestCase}.
</tr> </td>
<tr> </tr>
<td><code>size</code></td> <tr>
<td>[<code>small</code> | <code>medium</code> | <code>large</code>] <td><code>size</code></td>
</td> <td>
<td> [<code>small</code> | <code>medium</code> | <code>large</code>]
Runs a test method annotated by size. The annotations are <code>@SmallTest</code>, </td>
<code>@MediumTest</code>, and <code>@LargeTest</code>. <td>
</td> Runs a test method annotated by size. The annotations are <code>@SmallTest</code>,
</tr> <code>@MediumTest</code>, and <code>@LargeTest</code>.
<tr> </td>
<td><code>perf</code></td> </tr>
<td><code>true</code></td> <tr>
<td> <td><code>perf</code></td>
Runs all test classes that implement {@link android.test.PerformanceTestCase}. <td><code>true</code></td>
When you use this option, also specify the <code>-r</code> flag for <td>
<code>am instrument</code>, so that the output is kept in raw format and not Runs all test classes that implement {@link android.test.PerformanceTestCase}.
re-formatted as test results. When you use this option, also specify the <code>-r</code> flag for
</td> <code>am instrument</code>, so that the output is kept in raw format and not
</tr> re-formatted as test results.
<tr> </td>
<td><code>debug</code></td> </tr>
<td><code>true</code></td> <tr>
<td> <td><code>debug</code></td>
Runs tests in debug mode. <td><code>true</code></td>
</td> <td>
</tr> Runs tests in debug mode.
<tr> </td>
<td><code>log</code></td> </tr>
<td><code>true</code></td> <tr>
<td> <td><code>log</code></td>
Loads and logs all specified tests, but does not run them. The test <td><code>true</code></td>
information appears in <code>STDOUT</code>. Use this to verify combinations of other filters <td>
and test specifications. Loads and logs all specified tests, but does not run them. The test
</td> information appears in <code>STDOUT</code>. Use this to verify combinations of other
</tr> filters and test specifications.
<tr> </td>
<td><code>emma</code></td> </tr>
<td><code>true</code></td> <tr>
<td> <td><code>emma</code></td>
Runs an EMMA code coverage analysis and writes the output to <code>/data//coverage.ec</code> <td><code>true</code></td>
on the device. To override the file location, use the <code>coverageFile</code> key that <td>
is described in the following entry. Runs an EMMA code coverage analysis and writes the output to
<p class="note"> <code>/data//coverage.ec</code> on the device. To override the file location, use the
<strong>Note:</strong> This option requires an EMMA-instrumented build of the test <code>coverageFile</code> key that is described in the following entry.
application, which you can generate with the <code>coverage</code> target. <p class="note">
</p> <strong>Note:</strong> This option requires an EMMA-instrumented build of the test
</td> application, which you can generate with the <code>coverage</code> target.
</tr> </p>
<tr> </td>
<td><code>coverageFile</code></td> </tr>
<td><code>&lt;filename&gt;</code></td> <tr>
<td> <td><code>coverageFile</code></td>
Overrides the default location of the EMMA coverage file on the device. Specify this <td><code>&lt;filename&gt;</code></td>
value as a path and filename in UNIX format. The default filename is described in the <td>
entry for the <code>emma</code> key. Overrides the default location of the EMMA coverage file on the device. Specify this
</td> value as a path and filename in UNIX format. The default filename is described in the
</tr> entry for the <code>emma</code> key.
</td>
</tr>
</table> </table>
<strong><code>-e</code> Flag Usage Notes</strong> <strong><code>-e</code> Flag Usage Notes</strong>
<ul> <ul>
@@ -618,13 +627,13 @@ $ adb shell am instrument -w -e package com.android.test.package1,com.android.te
The <code>func</code> key and <code>unit</code> key are mutually exclusive. The <code>func</code> key and <code>unit</code> key are mutually exclusive.
</li> </li>
</ul> </ul>
<h3 id="RunTestExamples">Instrument examples</h3> <h3 id="RunTestExamples">Usage examples</h3>
<p> <p>
Here are some examples of using <code>am instrument</code> to run tests. They are based on The following sections provide examples of using <code>am instrument</code> to run tests.
the following structure:</p> They are based on the following structure:</p>
<ul> <ul>
<li> <li>
The test application has the Android package name <code>com.android.demo.app.tests</code> The test package has the Android package name <code>com.android.demo.app.tests</code>
</li> </li>
<li> <li>
There are three test classes: There are three test classes:
@@ -647,35 +656,35 @@ the following structure:</p>
The test runner is {@link android.test.InstrumentationTestRunner}. The test runner is {@link android.test.InstrumentationTestRunner}.
</li> </li>
</ul> </ul>
<h4>Running the Entire Test Application</h4> <h4>Running the entire test package</h4>
<p> <p>
To run all of the test classes in the test application, enter: To run all of the test classes in the test package, enter:
</p> </p>
<pre> <pre>
$ adb shell am instrument -w com.android.demo.app.tests/android.test.InstrumentationTestRunner $ adb shell am instrument -w com.android.demo.app.tests/android.test.InstrumentationTestRunner
</pre> </pre>
<h4>Running All Tests in a Test Case Class</h4> <h4>Running all tests in a test case class</h4>
<p> <p>
To run all of the tests in the class <code>UnitTests</code>, enter: To run all of the tests in the class <code>UnitTests</code>, enter:
</p> </p>
<pre> <pre>
$ adb shell am instrument -w \ $ adb shell am instrument -w \
-e class com.android.demo.app.tests.UnitTests \ &gt; -e class com.android.demo.app.tests.UnitTests \
com.android.demo.app.tests/android.test.InstrumentationTestRunner &gt; com.android.demo.app.tests/android.test.InstrumentationTestRunner
</pre> </pre>
<p> <p>
<code>am instrument</code> gets the value of the <code>-e</code> flag, detects the <code>am instrument</code> gets the value of the <code>-e</code> flag, detects the
<code>class</code> keyword, and runs all the methods in the <code>UnitTests</code> class. <code>class</code> keyword, and runs all the methods in the <code>UnitTests</code> class.
</p> </p>
<h4>Selecting a Subset of Tests</h4> <h4>Selecting a subset of tests</h4>
<p> <p>
To run all of the tests in <code>UnitTests</code>, and the <code>testCamera</code> method in To run all of the tests in <code>UnitTests</code>, and the <code>testCamera</code> method in
<code>FunctionTests</code>, enter: <code>FunctionTests</code>, enter:
</p> </p>
<pre> <pre>
$ adb shell am instrument -w \ $ adb shell am instrument -w \
-e class com.android.demo.app.tests.UnitTests,com.android.demo.app.tests.FunctionTests#testCamera \ &gt; -e class com.android.demo.app.tests.UnitTests,com.android.demo.app.tests.FunctionTests#testCamera \
com.android.demo.app.tests/android.test.InstrumentationTestRunner &gt; com.android.demo.app.tests/android.test.InstrumentationTestRunner
</pre> </pre>
<p> <p>
You can find more examples of the command in the documentation for You can find more examples of the command in the documentation for

30
docs/html/guide/guide_toc.cs
View File

@@ -254,12 +254,34 @@
<li><a href="<?cs var:toroot?>guide/topics/search/searchable-config.html">Searchable Configuration</a></li> <li><a href="<?cs var:toroot?>guide/topics/search/searchable-config.html">Searchable Configuration</a></li>
</ul> </ul>
</li> </li>
<li><a href="<?cs var:toroot?>guide/topics/testing/testing_android.html"> <li class="toggle-list">
<span class="en">Testing and Instrumentation</span> <div>
</a></li> <a href="<?cs var:toroot ?>guide/topics/testing/index.html">
<span class="en">Testing</span>
</a> <span class="new">new!</span>
</div>
<ul>
<li><a href="<?cs var:toroot?>guide/topics/testing/testing_android.html">
<span class="en">Testing Fundamentals</span></a>
</li>
<li><a href="<?cs var:toroot?>guide/topics/testing/activity_testing.html">
<span class="en">Activity Testing</span></a>
</li>
<li><a href="<?cs var:toroot ?>guide/topics/testing/contentprovider_testing.html">
<span class="en">Content Provider Testing</span></a>
</li>
<li><a href="<?cs var:toroot ?>guide/topics/testing/service_testing.html">
<span class="en">Service Testing</span></a>
</li>
<li><a href="<?cs var:toroot ?>guide/topics/testing/what_to_test.html">
<span class="en">What To Test</span></a>
</li>
</ul>
</li>
<li><a href="<?cs var:toroot?>guide/topics/admin/device-admin.html"> <li><a href="<?cs var:toroot?>guide/topics/admin/device-admin.html">
<span class="en">Device Administration</span> <span class="en">Device Administration</span>
</a> <span class="new">new!</span><!-- 10/8/10 --></li> </a> <span class="new">new!</span>
</li>
</ul> </ul>
</li> </li>

392
docs/html/guide/topics/testing/activity_testing.jd Normal file
View File

@@ -0,0 +1,392 @@
page.title=Activity Testing
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#ActivityTestAPI">The Activity Testing API</a>
<ol>
<li>
<a href="#ActivityInstrumentationTestCase2">ActivityInstrumentationTestCase2</a>
</li>
<li>
<a href="#ActivityUnitTestCase">ActivityUnitTestCase</a>
</li>
<li>
<a href="#SingleLaunchActivityTestCase">SingleLaunchActivityTestCase</a>
</li>
<li>
<a href="#MockObjectNotes">Mock objects and activity testing</a>
</li>
<li>
<a href="#AssertionNotes">Assertions for activity testing</a>
</li>
</ol>
</li>
<li>
<a href="#WhatToTest">What to Test</a>
</li>
<li>
<a href="#NextSteps">Next Steps</a>
</li>
<li>
<a href="#UITesting">Appendix: UI Testing Notes</a>
<ol>
<li>
<a href="#RunOnUIThread">Testing on the UI thread</a>
</li>
<li>
<a href="#NotouchMode">Turning off touch mode</a>
</li>
<li>
<a href="#UnlockDevice">Unlocking the Emulator or Device</a>
</li>
<li>
<a href="#UITestTroubleshooting">Troubleshooting UI tests</a>
</li>
</ol>
</li>
</ol>
<h2>Key Classes</h2>
<ol>
<li>{@link android.test.InstrumentationTestRunner}</li>
<li>{@link android.test.ActivityInstrumentationTestCase2}</li>
<li>{@link android.test.ActivityUnitTestCase}</li>
</ol>
<h2>Related Tutorials</h2>
<ol>
<li>
<a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">
Hello, Testing</a>
</li>
<li>
<a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
</li>
</ol>
<h2>See Also</h2>
<ol>
<li>
<a href="{@docRoot}guide/developing/testing/testing_eclipse.html">
Testing in Eclipse, with ADT</a>
</li>
<li>
<a href="{@docRoot}guide/developing/testing/testing_otheride.html">
Testing in Other IDEs</a>
</li>
</ol>
</div>
</div>
<p>
Activity testing is particularly dependent on the the Android instrumentation framework.
Unlike other components, activities have a complex lifecycle based on callback methods; these
can't be invoked directly except by instrumentation. Also, the only way to send events to the
user interface from a program is through instrumentation.
</p>
<p>
This document describes how to test activities using instrumentation and other test
facilities. The document assumes you have already read
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
the introduction to the Android testing and instrumentation framework.
</p>
<h2 id="ActivityTestAPI">The Activity Testing API</h2>
<p>
The activity testing API base class is {@link android.test.InstrumentationTestCase},
which provides instrumentation to the test case subclasses you use for Activities.
</p>
<p>
For activity testing, this base class provides these functions:
</p>
<ul>
<li>
Lifecycle control: With instrumentation, you can start the activity under test, pause it,
and destroy it, using methods provided by the test case classes.
</li>
<li>
Dependency injection: Instrumentation allows you to create mock system objects such as
Contexts or Applications and use them to run the activity under test. This
helps you control the test environment and isolate it from production systems. You can
also set up customized Intents and start an activity with them.
</li>
<li>
User interface interaction: You use instrumentation to send keystrokes or touch events
directly to the UI of the activity under test.
</li>
</ul>
<p>
The activity testing classes also provide the JUnit framework by extending
{@link junit.framework.TestCase} and {@link junit.framework.Assert}.
</p>
<p>
The two main testing subclasses are {@link android.test.ActivityInstrumentationTestCase2} and
{@link android.test.ActivityUnitTestCase}. To test an Activity that is launched in a mode
other than <code>standard</code>, you use {@link android.test.SingleLaunchActivityTestCase}.
</p>
<h3 id="ActivityInstrumentationTestCase2">ActivityInstrumentationTestCase2</h3>
<p>
The {@link android.test.ActivityInstrumentationTestCase2} test case class is designed to do
functional testing of one or more Activities in an application, using a normal system
infrastructure. It runs the Activities in a normal instance of the application under test,
using a standard system Context. It allows you to send mock Intents to the activity under
test, so you can use it to test an activity that responds to multiple types of intents, or
an activity that expects a certain type of data in the intent, or both. Notice, though, that it
does not allow mock Contexts or Applications, so you can not isolate the test from the rest of
a production system.
</p>
<h3 id="ActivityUnitTestCase">ActivityUnitTestCase</h3>
<p>
The {@link android.test.ActivityUnitTestCase} test case class tests a single activity in
isolation. Before you start the activity, you can inject a mock Context or Application, or both.
You use it to run activity tests in isolation, and to do unit testing of methods
that do not interact with Android. You can not send mock Intents to the activity under test,
although you can call
{@link android.app.Activity#startActivity(Intent) Activity.startActivity(Intent)} and then
look at arguments that were received.
</p>
<h3 id="SingleLaunchActivityTestCase">SingleLaunchActivityTestCase</h3>
<p>
The {@link android.test.SingleLaunchActivityTestCase} class is a convenience class for
testing a single activity in an environment that doesn't change from test to test.
It invokes {@link junit.framework.TestCase#setUp() setUp()} and
{@link junit.framework.TestCase#tearDown() tearDown()} only once, instead of once per
method call. It does not allow you to inject any mock objects.
</p>
<p>
This test case is useful for testing an activity that runs in a mode other than
<code>standard</code>. It ensures that the test fixture is not reset between tests. You
can then test that the activity handles multiple calls correctly.
</p>
<h3 id="MockObjectNotes">Mock objects and activity testing</h3>
<p>
This section contains notes about the use of the mock objects defined in
{@link android.test.mock} with activity tests.
</p>
<p>
The mock object {@link android.test.mock.MockApplication} is only available for activity
testing if you use the {@link android.test.ActivityUnitTestCase} test case class.
By default, <code>ActivityUnitTestCase</code>, creates a hidden <code>MockApplication</code>
object that is used as the application under test. You can inject your own object using
{@link android.test.ActivityUnitTestCase#setApplication(Application) setApplication()}.
</p>
<h3 id="AssertionNotes">Assertions for activity testing</h3>
<p>
{@link android.test.ViewAsserts} defines assertions for Views. You use it to verify the
alignment and position of View objects, and to look at the state of ViewGroup objects.
</p>
<h2 id="WhatToTest">What To Test</h2>
<ul>
<li>
Input validation: Test that an activity responds correctly to input values in an
EditText View. Set up a keystroke sequence, send it to the activity, and then
use {@link android.view.View#findViewById(int)} to examine the state of the View. You can
verify that a valid keystroke sequence enables an OK button, while an invalid one leaves the
button disabled. You can also verify that the Activity responds to invalid input by
setting error messages in the View.
</li>
<li>
Lifecycle events: Test that each of your application's activities handles lifecycle events
correctly. In general, lifecycle events are actions, either from the system or from the
user, that trigger a callback method such as <code>onCreate()</code> or
<code>onClick()</code>. For example, an activity should respond to pause or destroy events
by saving its state. Remember that even a change in screen orientation causes the current
activity to be destroyed, so you should test that accidental device movements don't
accidentally lose the application state.
</li>
<li>
Intents: Test that each activity correctly handles the intents listed in the intent
filter specified in its manifest. You can use
{@link android.test.ActivityInstrumentationTestCase2} to send mock Intents to the
activity under test.
</li>
<li>
Runtime configuration changes: Test that each activity responds correctly to the
possible changes in the device's configuration while your application is running. These
include a change to the device's orientation, a change to the current language, and so
forth. Handling these changes is described in detail in the topic
<a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime
Changes</a>.
</li>
<li>
Screen sizes and resolutions: Before you publish your application, make sure to test it on
all of the screen sizes and densities on which you want it to run. You can test the
application on multiple sizes and densities using AVDs, or you can test your application
directly on the devices that you are targeting. For more information, see the topic
<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.
</li>
</ul>
<h2 id="NextSteps">Next Steps</h2>
<p>
To learn how to set up and run tests in Eclipse, please refer to <a
href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in
Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a
href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other
IDEs</a>.
</p>
<p>
If you want a step-by-step introduction to testing activities, try one of the
testing tutorials:
</p>
<ul>
<li>
The <a
href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello,
Testing</a> tutorial introduces basic testing concepts and procedures in the
context of the Hello, World application.
</li>
<li>
The <a
href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity
Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial.
It guides you through a more complex testing scenario that you develop against a
more realistic activity-oriented application.
</li>
</ul>
<h2 id="UITesting">Appendix: UI Testing Notes</h2>
<p>
The following sections have tips for testing the UI of your Android application, specifically
to help you handle actions that run in the UI thread, touch screen and keyboard events, and home
screen unlock during testing.
</p>
<h3 id="RunOnUIThread">Testing on the UI thread</h3>
<p>
An application's activities run on the application's <strong>UI thread</strong>. Once the
UI is instantiated, for example in the activity's <code>onCreate()</code> method, then all
interactions with the UI must run in the UI thread. When you run the application normally, it
has access to the thread and does not have to do anything special.
</p>
<p>
This changes when you run tests against the application. With instrumentation-based classes,
you can invoke methods against the UI of the application under test. The other test classes
don't allow this. To run an entire test method on the UI thread, you can annotate the thread
with <code>@UIThreadTest</code>. Notice that this will run <em>all</em> of the method statements
on the UI thread. Methods that do not interact with the UI are not allowed; for example, you
can't invoke <code>Instrumentation.waitForIdleSync()</code>.
</p>
<p>
To run a subset of a test method on the UI thread, create an anonymous class of type
<code>Runnable</code>, put the statements you want in the <code>run()</code> method, and
instantiate a new instance of the class as a parameter to the method
<code><em>appActivity</em>.runOnUiThread()</code>, where <code><em>appActivity</em></code> is
the instance of the application you are testing.
</p>
<p>
For example, this code instantiates an activity to test, requests focus (a UI action) for the
Spinner displayed by the activity, and then sends a key to it. Notice that the calls to
<code>waitForIdleSync</code> and <code>sendKeys</code> aren't allowed to run on the UI thread:
</p>
<pre>
private MyActivity mActivity; // MyActivity is the class name of the app under test
private Spinner mSpinner;
...
protected void setUp() throws Exception {
super.setUp();
mInstrumentation = getInstrumentation();
mActivity = getActivity(); // get a references to the app under test
/*
* Get a reference to the main widget of the app under test, a Spinner
*/
mSpinner = (Spinner) mActivity.findViewById(com.android.demo.myactivity.R.id.Spinner01);
...
public void aTest() {
/*
* request focus for the Spinner, so that the test can send key events to it
* This request must be run on the UI thread. To do this, use the runOnUiThread method
* and pass it a Runnable that contains a call to requestFocus on the Spinner.
*/
mActivity.runOnUiThread(new Runnable() {
public void run() {
mSpinner.requestFocus();
}
});
mInstrumentation.waitForIdleSync();
this.sendKeys(KeyEvent.KEYCODE_DPAD_CENTER);
</pre>
<h3 id="NotouchMode">Turning off touch mode</h3>
<p>
To control the emulator or a device with key events you send from your tests, you must turn off
touch mode. If you do not do this, the key events are ignored.
</p>
<p>
To turn off touch mode, you invoke
<code>ActivityInstrumentationTestCase2.setActivityTouchMode(false)</code>
<em>before</em> you call <code>getActivity()</code> to start the activity. You must invoke the
method in a test method that is <em>not</em> running on the UI thread. For this reason, you
can't invoke the touch mode method from a test method that is annotated with
<code>@UIThread</code>. Instead, invoke the touch mode method from <code>setUp()</code>.
</p>
<h3 id="UnlockDevice">Unlocking the emulator or device</h3>
<p>
You may find that UI tests don't work if the emulator's or device's home screen is disabled with
the keyguard pattern. This is because the application under test can't receive key events sent
by <code>sendKeys()</code>. The best way to avoid this is to start your emulator or device
first and then disable the keyguard for the home screen.
</p>
<p>
You can also explicitly disable the keyguard. To do this,
you need to add a permission in the manifest file (<code>AndroidManifest.xml</code>) and
then disable the keyguard in your application under test. Note, though, that you either have to
remove this before you publish your application, or you have to disable it with code in
the published application.
</p>
<p>
To add the the permission, add the element
<code>&lt;uses-permission android:name="android.permission.DISABLE_KEYGUARD"/&gt;</code>
as a child of the <code>&lt;manifest&gt;</code> element. To disable the KeyGuard, add the
following code to the <code>onCreate()</code> method of activities you intend to test:
</p>
<pre>
mKeyGuardManager = (KeyguardManager) getSystemService(KEYGUARD_SERVICE);
mLock = mKeyGuardManager.newKeyguardLock("<em>activity_classname</em>");
mLock.disableKeyguard();
</pre>
<p>where <code><em>activity_classname</em></code> is the class name of the activity.</p>
<h3 id="UITestTroubleshooting">Troubleshooting UI tests</h3>
<p>
This section lists some of the common test failures you may encounter in UI testing, and their
causes:
</p>
<dl>
<dt><code>WrongThreadException</code></dt>
<dd>
<p><strong>Problem:</strong></p>
For a failed test, the Failure Trace contains the following error message:
<code>
android.view.ViewRoot$CalledFromWrongThreadException: Only the original thread that created
a view hierarchy can touch its views.
</code>
<p><strong>Probable Cause:</strong></p>
This error is common if you tried to send UI events to the UI thread from outside the UI
thread. This commonly happens if you send UI events from the test application, but you don't
use the <code>@UIThread</code> annotation or the <code>runOnUiThread()</code> method. The
test method tried to interact with the UI outside the UI thread.
<p><strong>Suggested Resolution:</strong></p>
Run the interaction on the UI thread. Use a test class that provides instrumentation. See
the previous section <a href="#RunOnUIThread">Testing on the UI Thread</a>
for more details.
</dd>
<dt><code>java.lang.RuntimeException</code></dt>
<dd>
<p><strong>Problem:</strong></p>
For a failed test, the Failure Trace contains the following error message:
<code>
java.lang.RuntimeException: This method can not be called from the main application thread
</code>
<p><strong>Probable Cause:</strong></p>
This error is common if your test method is annotated with <code>@UiThreadTest</code> but
then tries to do something outside the UI thread or tries to invoke
<code>runOnUiThread()</code>.
<p><strong>Suggested Resolution:</strong></p>
Remove the <code>@UiThreadTest</code> annotation, remove the <code>runOnUiThread()</code>
call, or re-factor your tests.
</dd>
</dl>

224
docs/html/guide/topics/testing/contentprovider_testing.jd Normal file
View File

@@ -0,0 +1,224 @@
page.title=Content Provider Testing
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#DesignAndTest">Content Provider Design and Testing</a>
</li>
<li>
<a href="#ContentProviderTestAPI">The Content Provider Testing API</a>
<ol>
<li>
<a href="#ProviderTestCase2">ProviderTestCase2 </a>
</li>
<li>
<a href="#MockObjects">Mock object classes</a>
</li>
</ol>
</li>
<li>
<a href="#WhatToTest">What To Test</a>
</li>
<li>
<a href="#NextSteps">Next Steps</a>
</li>
</ol>
<h2>Key Classes</h2>
<ol>
<li>{@link android.test.InstrumentationTestRunner}</li>
<li>{@link android.test.ProviderTestCase2}</li>
<li>{@link android.test.IsolatedContext}</li>
<li>{@link android.test.mock.MockContentResolver}</li>
</ol>
<h2>See Also</h2>
<ol>
<li>
<a
href="{@docRoot}guide/topics/testing/topics/testing_android.html">
Testing Fundamentals</a>
</li>
<li>
<a href="{@docRoot}guide/developing/testing/testing_eclipse.html">
Testing in Eclipse, with ADT</a>
</li>
<li>
<a href="{@docRoot}guide/developing/testing/testing_otheride.html">
Testing in Other IDEs</a>
</li>
</ol>
</div>
</div>
<p>
Content providers, which store and retrieve data and make it accessible across applications,
are a key part of the Android API. As an application developer you're allowed to provide your
own public providers for use by other applications. If you do, then you should test them
using the API you publish.
</p>
<p>
This document describes how to test public content providers, although the information is
also applicable to providers that you keep private to your own application. If you aren't
familiar with content providers or the Android testing framework, please read
<a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>,
the guide to developing content providers, and
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
the introduction to the Android testing and instrumentation framework.
</p>
<h2 id="DesignAndTest">Content Provider Design and Testing</h2>
<p>
In Android, content providers are viewed externally as data APIs that provide
tables of data, with their internals hidden from view. A content provider may have many
public constants, but it usually has few if any public methods and no public variables.
This suggests that you should write your tests based only on the provider's public members.
A content provider that is designed like this is offering a contract between itself and its
users.
</p>
<p>
The base test case class for content providers,
{@link android.test.ProviderTestCase2}, allows you to test your content provider in an
isolated environment. Android mock objects such as {@link android.test.IsolatedContext} and
{@link android.test.mock.MockContentResolver} also help provide an isolated test environment.
</p>
<p>
As with other Android tests, provider test packages are run under the control of the test
runner {@link android.test.InstrumentationTestRunner}. The section
<a href="{@docRoot}guide/topics/testing/testing_android.html#InstrumentationTestRunner">
Running Tests With InstrumentationTestRunner</a> describes the test runner in
more detail. The topic <a href="{@docRoot}guide/developing/testing/testing_eclipse.html">
Testing in Eclipse, with ADT</a> shows you how to run a test package in Eclipse, and the
topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html">
Testing in Other IDEs</a>
shows you how to run a test package from the command line.
</p>
<h2 id="ContentProviderTestAPI">Content Provider Testing API</h2>
<p>
The main focus of the provider testing API is to provide an isolated testing environment. This
ensures that tests always run against data dependencies set explicitly in the test case. It
also prevents tests from modifying actual user data. For example, you want to avoid writing
a test that fails because there was data left over from a previous test, and you want to
avoid adding or deleting contact information in a actual provider.
</p>
<p>
The test case class and mock object classes for provider testing set up this isolated testing
environment for you.
</p>
<h3 id="ProviderTestCase2">ProviderTestCase2</h3>
<p>
You test a provider with a subclass of {@link android.test.ProviderTestCase2}. This base class
extends {@link android.test.AndroidTestCase}, so it provides the JUnit testing framework as well
as Android-specific methods for testing application permissions. The most important
feature of this class is its initialization, which creates the isolated test environment.
</p>
<p>
The initialization is done in the constructor for {@link android.test.ProviderTestCase2}, which
subclasses call in their own constructors. The {@link android.test.ProviderTestCase2}
constructor creates an {@link android.test.IsolatedContext} object that allows file and
database operations but stubs out other interactions with the Android system.
The file and database operations themselves take place in a directory that is local to the
device or emulator and has a special prefix.
</p>
<p>
The constructor then creates a {@link android.test.mock.MockContentResolver} to use as the
resolver for the test. The {@link android.test.mock.MockContentResolver} class is described in
detail in the section
<a href="{@docRoot}guide/topics/testing/test_android#MockObjectClasses">Mock object classes</a>.
</p>
<p>
Lastly, the constructor creates an instance of the provider under test. This is a normal
{@link android.content.ContentProvider} object, but it takes all of its environment information
from the {@link android.test.IsolatedContext}, so it is restricted to
working in the isolated test environment. All of the tests done in the test case class run
against this isolated object.
</p>
<h3 id="MockObjects">Mock object classes</h3>
<p>
{@link android.test.ProviderTestCase2} uses {@link android.test.IsolatedContext} and
{@link android.test.mock.MockContentResolver}, which are standard mock object classes. To
learn more about them, please read
<a href="{@docRoot}guide/topics/testing/test_android#MockObjectClasses">
Testing Fundamentals</a>.
</p>
<h2 id="WhatToTest">What To Test</h2>
<p>
The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a>
lists general considerations for testing Android components.
Here are some specific guidelines for testing content providers.
</p>
<ul>
<li>
Test with resolver methods: Even though you can instantiate a provider object in
{@link android.test.ProviderTestCase2}, you should always test with a resolver object
using the appropriate URI. This ensures that you are testing the provider using the same
interaction that a regular application would use.
</li>
<li>
Test a public provider as a contract: If you intent your provider to be public and
available to other applications, you should test it as a contract. This includes
the following ideas:
<ul>
<li>
Test with constants that your provider publicly exposes. For
example, look for constants that refer to column names in one of the provider's
data tables. These should always be constants publicly defined by the provider.
</li>
<li>
Test all the URIs offered by your provider. Your provider may offer several URIs,
each one referring to a different aspect of the data. The
<a href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample,
for example, features a provider that offers one URI for retrieving a list of notes,
another for retrieving an individual note by it's database ID, and a third for
displaying notes in a live folder. The sample test package for Note Pad,
<a href="{@docRoot}resources/samples/NotePadTest/index.html"> Note Pad Test</a>, has
unit tests for two of these URIs.
</li>
<li>
Test invalid URIs: Your unit tests should deliberately call the provider with an
invalid URI, and look for errors. Good provider design is to throw an
IllegalArgumentException for invalid URIs.
</li>
</ul>
</li>
<li>
Test the standard provider interactions: Most providers offer six access methods:
query, insert, delete, update, getType, and onCreate(). Your tests should verify that all
of these methods work. These are described in more detail in the topic
<a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.
</li>
<li>
Test business logic: Don't forget to test the business logic that your provider should
enforce. Business logic includes handling of invalid values, financial or arithmetic
calculations, elimination or combining of duplicates, and so forth. A content provider
does not have to have business logic, because it may be implemented by activities that
modify the data. If the provider does implement business logic, you should test it.
</li>
</ul>
<h2 id="NextSteps">Next Steps</h2>
<p>
To learn how to set up and run tests in Eclipse, please refer to <a
href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in
Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a
href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other
IDEs</a>.
</p>
<p>
If you want a step-by-step introduction to testing activities, try one of the
testing tutorials:
</p>
<ul>
<li>
The <a
href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello,
Testing</a> tutorial introduces basic testing concepts and procedures in the
context of the Hello, World application.
</li>
<li>
The <a
href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity
Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial.
It guides you through a more complex testing scenario that you develop against a
more realistic activity-oriented application.
</li>
</ul>

80
docs/html/guide/topics/testing/index.jd Normal file
View File

@@ -0,0 +1,80 @@
page.title=Testing
@jd:body
<p>
The Android development environment includes an integrated testing framework that helps you
test all aspects of your application.
</p>
<h4>Fundamentals</h4>
<p>
To start learning how to use the framework to create tests for your applications, please
read the topic <a href="{@docRoot}guide/topics/testing/testing_android.html">
Testing Fundamentals</a>.
</p>
<h4>Concepts</h4>
<ul>
<li>
Testing Tools describes the Eclipse with ADT and command-line tools you use to test
Android applications.
</li>
<li>
What to Test is an overview of the types of testing you should do. It focuses on testing
system-wide aspects of Android that can affect every component in your application.
</li>
<li>
<a href="{@docRoot}guide/topics/testing/activity_testing.html">
Activity Testing</a> focuses on testing activities. It describes how instrumentation allows
you to control activities outside the normal application lifecycle. It also lists
activity-specific features you should test, and it provides tips for testing Android
user interfaces.
</li>
<li>
<a href="{@docRoot}guide/topics/testing/contentprovider_testing.html">
Content Provider Testing</a> focuses on testing content providers. It describes the
mock system objects you can use, provides tips for designing providers so that they
can be tested, and lists provider-specific features you should test.
</li>
<li>
<a href="{@docRoot}guide/topics/testing/service_testing.html">
Service Testing</a> focuses on testing services. It also lists service-specific features
you should test.
</li>
</ul>
<h4>Procedures</h4>
<ul>
<li>
The topic <a href="{@docRoot}guide/developing/testing/testing_eclipse.html">
Testing in Eclipse, with ADT</a> describes how to create and run tests in Eclipse with ADT.
</li>
<li>
The topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html">
Testing in other IDEs</a> describes how to create and run tests with command-line tools.
</li>
</ul>
<h4>Tutorials</h4>
<ul>
<li>
The <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">
Hello, Testing</a> tutorial introduces basic testing concepts and procedures.
</li>
<li>
For a more advanced tutorial, try
<a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>,
which guides you through a more complex testing scenario.
</li>
</ul>
<h4>Samples</h4>
<ul>
<li>
<a href="{@docRoot}resources/samples/NotePadTest.html">Note Pad Provider
Test</a> is a test package for the
<a href="{@docRoot}resources/samples/NotePad.html">Note Pad</a> sample
application. It provides a simple example of unit testing
a {@link android.content.ContentProvider}.
</li>
<li>
The <a href="{@docRoot}resources/samples/AlarmServiceTest.html">Alarm Service Test</a>
is a test package for the <a href="{@docRoot}resources/samples/Alarm.html">Alarm</a>
sample application. It provides a simple example of unit
testing a {@link android.app.Service}.
</li>
</ul>

178
docs/html/guide/topics/testing/service_testing.jd Normal file
View File

@@ -0,0 +1,178 @@
page.title=Service Testing
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#DesignAndTest">Service Design and Testing</a>
</li>
<li>
<a href="#ServiceTestCase">ServiceTestCase</a>
</li>
<li>
<a href="#MockObjects">Mock object classes</a>
</li>
<li>
<a href="#TestAreas">What to Test</a>
</li>
</ol>
<h2>Key Classes</h2>
<ol>
<li>{@link android.test.InstrumentationTestRunner}</li>
<li>{@link android.test.ServiceTestCase}</li>
<li>{@link android.test.mock.MockApplication}</li>
<li>{@link android.test.RenamingDelegatingContext}</li>
</ol>
<h2>Related Tutorials</h2>
<ol>
<li>
<a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">
Hello, Testing</a>
</li>
<li>
<a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
</li>
</ol>
<h2>See Also</h2>
<ol>
<li>
<a href="{@docRoot}guide/developing/testing/testing_eclipse.html">
Testing in Eclipse, with ADT</a>
</li>
<li>
<a href="{@docRoot}guide/developing/testing/testing_otheride.html">
Testing in Other IDEs</a>
</li>
</ol>
</div>
</div>
<p>
Android provides a testing framework for Service objects that can run them in
isolation and provides mock objects. The test case class for Service objects is
{@link android.test.ServiceTestCase}. Since the Service class assumes that it is separate
from its clients, you can test a Service object without using instrumentation.
</p>
<p>
This document describes techniques for testing Service objects. If you aren't familiar with the
Service class, please read <a href="{@docRoot}guide/topics/fundamentals.html">
Application Fundamentals</a>. If you aren't familiar with Android testing, please read
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
the introduction to the Android testing and instrumentation framework.
</p>
<h2 id="DesignAndTest">Service Design and Testing</h2>
<p>
When you design a Service, you should consider how your tests can examine the various states
of the Service lifecycle. If the lifecycle methods that start up your Service, such as
{@link android.app.Service#onCreate() onCreate()} or
{@link android.app.Service#onStartCommand(Intent, int, int) onStartCommand()} do not normally
set a global variable to indicate that they were successful, you may want to provide such a
variable for testing purposes.
</p>
<p>
Most other testing is facilitated by the methods in the {@link android.test.ServiceTestCase}
test case class. For example, the {@link android.test.ServiceTestCase#getService()} method
returns a handle to the Service under test, which you can test to confirm that the Service is
running even at the end of your tests.
</p>
<h2 id="ServiceTestCase">ServiceTestCase</h2>
<p>
{@link android.test.ServiceTestCase} extends the JUnit {@link junit.framework.TestCase} class
with with methods for testing application permissions and for controlling the application and
Service under test. It also provides mock application and Context objects that isolate your
test from the rest of the system.
</p>
<p>
{@link android.test.ServiceTestCase} defers initialization of the test environment until you
call {@link android.test.ServiceTestCase#startService(Intent) ServiceTestCase.startService()} or
{@link android.test.ServiceTestCase#bindService(Intent) ServiceTestCase.bindService()}. This
allows you to set up your test environment, particularly your mock objects, before the Service
is started.
</p>
<p>
Notice that the parameters to <code>ServiceTestCase.bindService()</code>are different from
those for <code>Service.bindService()</code>. For the <code>ServiceTestCase</code> version,
you only provide an Intent. Instead of returning a boolean,
<code>ServiceTestCase.bindService()</code> returns an object that subclasses
{@link android.os.IBinder}.
</p>
<p>
The {@link android.test.ServiceTestCase#setUp()} method for {@link android.test.ServiceTestCase}
is called before each test. It sets up the test fixture by making a copy of the current system
Context before any test methods touch it. You can retrieve this Context by calling
{@link android.test.ServiceTestCase#getSystemContext()}. If you override this method, you must
call <code>super.setUp()</code> as the first statement in the override.
</p>
<p>
The methods {@link android.test.ServiceTestCase#setApplication(Application) setApplication()}
and {@link android.test.AndroidTestCase#setContext(Context)} setContext()} allow you to set
a mock Context or mock Application (or both) for the Service, before you start it. These mock
objects are described in <a href="#MockObjects">Mock object classes</a>.
</p>
<p>
By default, {@link android.test.ServiceTestCase} runs the test method
{@link android.test.AndroidTestCase#testAndroidTestCaseSetupProperly()}, which asserts that
the base test case class successfully set up a Context before running.
</p>
<h2 id="MockObjects">Mock object classes</h2>
<p>
<code>ServiceTestCase</code> assumes that you will use a mock Context or mock Application
(or both) for the test environment. These objects isolate the test environment from the
rest of the system. If you don't provide your own instances of these objects before you
start the Service, then {@link android.test.ServiceTestCase} will create its own internal
instances and inject them into the Service. You can override this behavior by creating and
injecting your own instances before starting the Service
</p>
<p>
To inject a mock Application object into the Service under test, first create a subclass of
{@link android.test.mock.MockApplication}. <code>MockApplication</code> is a subclass of
{@link android.app.Application} in which all the methods throw an Exception, so to use it
effectively you subclass it and override the methods you need. You then inject it into the
Service with the
{@link android.test.ServiceTestCase#setApplication(Application) setApplication()} method.
This mock object allows you to control the application values that the Service sees, and
isolates it from the real system. In addition, any hidden dependencies your Service has on
its application reveal themselves as exceptions when you run the test.
</p>
<p>
You inject a mock Context into the Service under test with the
{@link android.test.AndroidTestCase#setContext(Context) setContext()} method. The mock
Context classes you can use are described in more detail in
<a href="{@docRoot}guide/topics/testing/testing_android.html#MockObjectClasses">
Testing Fundamentals</a>.
</p>
<h2 id="TestAreas">What to Test</h2>
<p>
The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a>
lists general considerations for testing Android components.
Here are some specific guidelines for testing a Service:
</p>
<ul>
<li>
Ensure that the {@link android.app.Service#onCreate()} is called in response to
{@link android.content.Context#startService(Intent) Context.startService()} or
{@link android.content.Context#bindService(Intent,ServiceConnection,int) Context.bindService()}.
Similarly, you should ensure that {@link android.app.Service#onDestroy()} is called in
response to {@link android.content.Context#stopService(Intent) Context.stopService()},
{@link android.content.Context#unbindService(ServiceConnection) Context.unbindService()},
{@link android.app.Service#stopSelf()}, or
{@link android.app.Service#stopSelfResult(int) stopSelfResult()}.
</li>
<li>
Test that your Service correctly handles multiple calls from
<code>Context.startService()</code>. Only the first call triggers
<code>Service.onCreate()</code>, but all calls trigger a call to
<code>Service.onStartCommand()</code>.
<p>
In addition, remember that <code>startService()</code> calls don't
nest, so a single call to <code>Context.stopService()</code> or
<code>Service.stopSelf()</code> (but not <code>stopSelf(int)</code>)
will stop the Service. You should test that your Service stops at the correct point.
</p>
</li>
<li>
Test any business logic that your Service implements. Business logic includes checking for
invalid values, financial and arithmetic calculations, and so forth.
</li>
</ul>

994
docs/html/guide/topics/testing/testing_android.jd
View File

File diff suppressed because it is too large Load Diff

84
docs/html/guide/topics/testing/what_to_test.jd Normal file
View File

@@ -0,0 +1,84 @@
page.title=What To Test
@jd:body
<p>
As you develop Android applications, knowing what to test is as important as knowing how to
test. This document lists some most common Android-related situations that you should consider
when you test, even at the unit test level. This is not an exhaustive list, and you consult the
documentation for the features that you use for more ideas. The
<a href="http://groups.google.com/group/android-developers">android-developers</a> Google Groups
site is another resource for information about testing.
</p>
<h2 id="Tests">Ideas for Testing</h2>
<p>
The following sections are organized by behaviors or situations that you should test. Each
section contains a scenario that further illustrates the situation and the test or tests you
should do.
</p>
<h4>Change in orientation</h4>
<p>
For devices that support multiple orientations, Android detects a change in orientation when
the user turns the device so that the display is "landscape" (long edge is horizontal) instead
of "portrait" (long edge is vertical).
</p>
<p>
When Android detects a change in orientation, its default behavior is to destroy and then
re-start the foreground Activity. You should consider testing the following:
</p>
<ul>
<li>
Is the screen re-drawn correctly? Any custom UI code you have should handle changes in the
orientation.
</li>
<li>
Does the application maintain its state? The Activity should not lose anything that the
user has already entered into the UI. The application should not "forget" its place in the
current transaction.
</li>
</ul>
<h4>Change in configuration</h4>
<p>
A situation that is more general than a change in orientation is a change in the device's
configuration, such as a change in the availability of a keyboard or a change in system
language.
</p>
<p>
A change in configuration also triggers the default behavior of destroying and then restarting
the foreground Activity. Besides testing that the application maintains the UI and its
transaction state, you should also test that the application updates itself to respond
correctly to the new configuration.
</p>
<h4>Battery life</h4>
<p>
Mobile devices primarily run on battery power. A device has finite "battery budget", and when it
is gone, the device is useless until it is recharged. You need to write your application to
minimize battery usage, you need to test its battery performance, and you need to test the
methods that manage battery usage.
</p>
<p>
Techniques for minimizing battery usage were presented at the 2010 Google I/O conference in the
presentation
<a href="http://code.google.com/events/io/2009/sessions/CodingLifeBatteryLife.html">
Coding for Life -- Battery Life, That Is</a>. This presentation describes the impact on battery
life of various operations, and the ways you can design your application to minimize these
impacts. When you code your application to reduce battery usage, you also write the
appropriate unit tests.
</p>
<h4>Dependence on external resources</h4>
<p>
If your application depends on network access, SMS, Bluetooth, or GPS, then you should
test what happens when the resource or resources are not available.
</p>
<p>
For example, if your application uses the network,it can notify the user if access is
unavailable, or disable network-related features, or do both. For GPS, it can switch to
IP-based location awareness. It can also wait for WiFi access before doing large data transfers,
since WiFi transfers maximize battery usage compared to transfers over 3G or EDGE.
</p>
<p>
You can use the emulator to test network access and bandwidth. To learn more, please see
<a href="{@docRoot}guide/developing/tools/emulator.html#netspeed">Network Speed Emulation</a>.
To test GPS, you can use the emulator console and {@link android.location.LocationManager}. To
learn more about the emulator console, please see
<a href="{@docRoot}/guide/developing/tools/emulator.html#console">
Using the Emulator Console</a>.
</p>

BIN
docs/html/images/testing/android_test_framework.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 80 KiB

After

Width:  |  Height:  |  Size: 46 KiB

BIN
docs/html/images/testing/eclipse_test_results.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
docs/html/images/testing/eclipse_test_run_failure.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/html/images/testing/test_framework.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB