tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
base/docs/html/guide/topics/testing/activity_testing.jd
+392
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>
base/docs/html/guide/topics/testing/contentprovider_testing.jd
+223
View File
@@ -0,0 +1,223 @@
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/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/testing_android.html#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/testing_android.html#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.
</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>
base/docs/html/guide/topics/testing/index.jd
+86
View File
@@ -0,0 +1,86 @@
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>
<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>
<li>
<a href="{@docRoot}guide/topics/testing/what_to_test.html">What to Test</a>
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>
</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>Tools</h4>
<ul>
<li>
The
<a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>,
usually called Monkey, is a command-line tool that sends pseudo-random
streams of keystrokes, touches, and gestures to a device.
</li>
<li>
The <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a> tool
is an API and execution environment. You use monkeyrunner with Python programs
to test applications and devices.
</li>
</ul>
<!--
<h4>Samples</h4>
<ul>
<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>
-->
base/docs/html/guide/topics/testing/service_testing.jd
+178
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>
base/docs/html/guide/topics/testing/testing_android.jd
Executable
+663
View File
@@ -0,0 +1,663 @@
page.title=Testing Fundamentals
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#TestStructure">Test Structure</a>
</li>
<li>
<a href="#TestProjects">Test Projects</a>
</li>
<li>
<a href="#TestAPI">The Testing API</a>
<ol>
<li>
<a href="#JUnit">JUnit</a>
</li>
<li>
<a href="#Instrumentation">Instrumentation</a>
</li>
<li>
<a href="#TestCaseClasses">Test case classes</a>
</li>
<li>
<a href="#AssertionClasses">Assertion classes</a>
</li>
<li>
<a href="#MockObjectClasses">Mock object classes</a>
</li>
</ol>
</li>
<li>
<a href="#InstrumentationTestRunner">Running Tests</a>
</li>
<li>
<a href="#TestResults">Seeing Test Results</a>
</li>
<li>
<a href="#Monkeys">monkey and monkeyrunner</a>
</li>
<li>
<a href="#PackageNames">Working With Package Names</a>
</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}</li>
<li>{@link android.test.mock}</li>
<li>{@link junit.framework}</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>
<li>
<a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">
monkeyrunner</a>
</li>
<li>
<a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>
</li>
</ol>
</div>
</div>
<p>
The Android testing framework, an integral part of the development environment,
provides an architecture and powerful tools that help you test every aspect of your application
at every level from unit to framework.
</p>
<p>
The testing framework has these key features:
</p>
<ul>
<li>
Android test suites are based on JUnit. You can use plain JUnit to test a class that doesn't
call the Android API, or Android's JUnit extensions to test Android components. If you're
new to Android testing, you can start with general-purpose test case classes such as {@link
android.test.AndroidTestCase} and then go on to use more sophisticated classes.
</li>
<li>
The Android JUnit extensions provide component-specific test case classes. These classes
provide helper methods for creating mock objects and methods that help you control the
lifecycle of a component.
</li>
<li>
Test suites are contained in test packages that are similar to main application packages, so
you don't need to learn a new set of tools or techniques for designing and building tests.
</li>
<li>
The SDK tools for building and tests are available in Eclipse with ADT, and also in
command-line form for use with other IDES. These tools get information from the project of
the application under test and use this information to automatically create the build files,
manifest file, and directory structure for the test package.
</li>
<li>
The SDK also provides
<a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a>, an API
testing devices with Python programs, and <a
href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>,
a command-line tool for stress-testing UIs by sending pseudo-random events to a device.
</li>
</ul>
<p>
This document describes the fundamentals of the Android testing framework, including the
structure of tests, the APIs that you use to develop tests, and the tools that you use to run
tests and view results. The document assumes you have a basic knowledge of Android application
programming and JUnit testing methodology.
</p>
<p>
The following diagram summarizes the testing framework:
</p>
<div style="width: 70%; margin-left:auto; margin-right:auto;">
<a href="{@docRoot}images/testing/test_framework.png">
<img src="{@docRoot}images/testing/test_framework.png"
alt="The Android testing framework"/>
</a>
</div>
<h2 id="TestStructure">Test Structure</h2>
<p>
Android's build and test tools assume that test projects are organized into a standard
structure of tests, test case classes, test packages, and test projects.
</p>
<p>
Android testing is based on JUnit. In general, a JUnit test is a method whose
statements test a part of the application under test. You organize test methods into classes
called test cases (or test suites). Each test is an isolated test of an individual module in
the application under test. Each class is a container for related test methods, although it
often provides helper methods as well.
</p>
<p>
In JUnit, you build one or more test source files into a class file. Similarly, in Android you
use the SDK's build tools to build one or more test source files into class files in an
Android test package. In JUnit, you use a test runner to execute test classes. In Android, you
use test tools to load the test package and the application under test, and the tools then
execute an Android-specific test runner.
</p>
<h2 id="TestProjects">Test Projects</h2>
<p>
Tests, like Android applications, are organized into projects.
</p>
<p>
A test project is a directory or Eclipse project in which you create the source code, manifest
file, and other files for a test package. The Android SDK contains tools for Eclipse with ADT
and for the command line that create and update test projects for you. The tools create the
directories you use for source code and resources and the manifest file for the test package.
The command-line tools also create the Ant build files you need.
</p>
<p>
You should always use Android tools to create a test project. Among other benefits,
the tools:
</p>
<ul>
<li>
Automatically set up your test package to use
{@link android.test.InstrumentationTestRunner} as the test case runner. You must use
<code>InstrumentationTestRunner</code> (or a subclass) to run JUnit tests.
</li>
<li>
Create an appropriate name for the test package. If the application
under test has a package name of <code>com.mydomain.myapp</code>, then the
Android tools set the test package name to <code>com.mydomain.myapp.test</code>. This
helps you identify their relationship, while preventing conflicts within the system.
</li>
<li>
Automatically create the proper build files, manifest file, and directory
structure for the test project. This helps you to build the test package without
having to modify build files and sets up the linkage between your test package and
the application under test.
The
</li>
</ul>
<p>
You can create a test project anywhere in your file system, but the best approach is to
add the test project so that its root directory <code>tests/</code> is at the same level
as the <code>src/</code> directory of the main application's project. This helps you find the
tests associated with an application. For example, if your application project's root directory
is <code>MyProject</code>, then you should use the following directory structure:
</p>
<pre class="classic no-pretty-print">
MyProject/
AndroidManifest.xml
res/
... (resources for main application)
src/
... (source code for main application) ...
tests/
AndroidManifest.xml
res/
... (resources for tests)
src/
... (source code for tests)
</pre>
<h2 id="TestAPI">The Testing API</h2>
<p>
The Android testing API is based on the JUnit API and extended with a instrumentation
framework and Android-specific testing classes.
</p>
<h3 id="JUnit">JUnit</h3>
<p>
You can use the JUnit {@link junit.framework.TestCase TestCase} class to do unit testing on
a plain Java object. <code>TestCase</code> is also the base class for
{@link android.test.AndroidTestCase}, which you can use to test Android-dependent objects.
Besides providing the JUnit framework, AndroidTestCase offers Android-specific setup,
teardown, and helper methods.
</p>
<p>
You use the JUnit {@link junit.framework.Assert} class to display test results.
The assert methods compare values you expect from a test to the actual results and
throw an exception if the comparison fails. Android also provides a class of assertions that
extend the possible types of comparisons, and another class of assertions for testing the UI.
These are described in more detail in the section <a href="#AssertionClasses">
Assertion classes</a>
</p>
<p>
To learn more about JUnit, you can read the documentation on the
<a href="http://www.junit.org">junit.org</a> home page.
Note that the Android testing API supports JUnit 3 code style, but not JUnit 4. Also, you must
use Android's instrumented test runner {@link android.test.InstrumentationTestRunner} to run
your test case classes. This test runner is described in the
section <a href="#InstrumentationTestRunner">Running Tests</a>.
</p>
<h3 id="Instrumentation">Instrumentation</h3>
<p>
Android instrumentation is a set of control methods or "hooks" in the Android system. These hooks
control an Android component independently of its normal lifecycle. They also control how
Android loads applications.
</p>
<p>
Normally, an Android component runs in a lifecycle determined by the system. For example, an
Activity object's lifecycle starts when the Activity is activated by an Intent. The object's
<code>onCreate()</code> method is called, followed by <code>onResume()</code>. When the user
starts another application, the <code>onPause()</code> method is called. If the Activity
code calls the <code>finish()</code> method, the <code>onDestroy()</code> method is called.
The Android framework API does not provide a way for your code to invoke these callback
methods directly, but you can do so using instrumentation.
</p>
<p>
Also, the system runs all the components of an application into the same
process. You can allow some components, such as content providers, to run in a separate process,
but you can't force an application to run in the same process as another application that is
already running.
</p>
<p>
With Android instrumentation, though, you can invoke callback methods in your test code.
This allows you to run through the lifecycle of a component step by step, as if you were
debugging the component. The following test code snippet demonstrates how to use this to
test that an Activity saves and restores its state:
</p>
<a name="ActivitySnippet"></a>
<pre>
// Start the main activity of the application under test
mActivity = getActivity();
// Get a handle to the Activity object's main UI widget, a Spinner
mSpinner = (Spinner)mActivity.findViewById(com.android.example.spinner.R.id.Spinner01);
// Set the Spinner to a known position
mActivity.setSpinnerPosition(TEST_STATE_DESTROY_POSITION);
// Stop the activity - The onDestroy() method should save the state of the Spinner
mActivity.finish();
// Re-start the Activity - the onResume() method should restore the state of the Spinner
mActivity = getActivity();
// Get the Spinner's current position
int currentPosition = mActivity.getSpinnerPosition();
// Assert that the current position is the same as the starting position
assertEquals(TEST_STATE_DESTROY_POSITION, currentPosition);
</pre>
<p>
The key method used here is
{@link android.test.ActivityInstrumentationTestCase2#getActivity()}, which is a
part of the instrumentation API. The Activity under test is not started until you call this
method. You can set up the test fixture in advance, and then call this method to start the
Activity.
</p>
<p>
Also, instrumentation can load both a test package and the application under test into the
same process. Since the application components and their tests are in the same process, the
tests can invoke methods in the components, and modify and examine fields in the components.
</p>
<h3 id="TestCaseClasses">Test case classes</h3>
<p>
Android provides several test case classes that extend {@link junit.framework.TestCase} and
{@link junit.framework.Assert} with Android-specific setup, teardown, and helper methods.
</p>
<h4 id="AndroidTestCase">AndroidTestCase</h4>
<p>
A useful general test case class, especially if you are
just starting out with Android testing, is {@link android.test.AndroidTestCase}. It extends
both {@link junit.framework.TestCase} and {@link junit.framework.Assert}. It provides the
JUnit-standard <code>setUp()</code> and <code>tearDown()</code> methods, as well as well as
all of JUnit's Assert methods. In addition, it provides methods for testing permissions, and a
method that guards against memory leaks by clearing out certain class references.
</p>
<h4 id="ComponentTestCase">Component-specific test cases</h4>
<p>
A key feature of the Android testing framework is its component-specific test case classes.
These address specific component testing needs with methods for fixture setup and
teardown and component lifecycle control. They also provide methods for setting up mock objects.
These classes are described in the component-specific testing topics:
</p>
<ul>
<li>
<a href="{@docRoot}guide/topics/testing/activity_testing.html">Activity Testing</a>
</li>
<li>
<a href="{@docRoot}guide/topics/testing/contentprovider_testing.html">
Content Provider Testing</a>
</li>
<li>
<a href="{@docRoot}guide/topics/testing/service_testing.html">Service Testing</a>
</li>
</ul>
<p>
Android does not provide a separate test case class for BroadcastReceiver. Instead, test a
BroadcastReceiver by testing the component that sends it Intent objects, to verify that the
BroadcastReceiver responds correctly.
</p>
<h4 id="ApplicationTestCase">ApplicationTestCase</h4>
<p>
You use the {@link android.test.ApplicationTestCase} test case class to test the setup and
teardown of {@link android.app.Application} objects. These objects maintain the global state of
information that applies to all the components in an application package. The test case can
be useful in verifying that the &lt;application&gt; element in the manifest file is correctly
set up. Note, however, that this test case does not allow you to control testing of the
components within your application package.
</p>
<h4 id="InstrumentationTestCase">InstrumentationTestCase</h4>
<p>
If you want to use instrumentation methods in a test case class, you must use
{@link android.test.InstrumentationTestCase} or one of its subclasses. The
{@link android.app.Activity} test cases extend this base class with other functionality that
assists in Activity testing.
</p>
<h3 id="AssertionClasses">Assertion classes</h3>
<p>
Because Android test case classes extend JUnit, you can use assertion methods to display the
results of tests. An assertion method compares an actual value returned by a test to an
expected value, and throws an AssertionException if the comparison test fails. Using assertions
is more convenient than doing logging, and provides better test performance.
</p>
<p>
Besides the JUnit {@link junit.framework.Assert} class methods, the testing API also provides
the {@link android.test.MoreAsserts} and {@link android.test.ViewAsserts} classes:
</p>
<ul>
<li>
{@link android.test.MoreAsserts} contains more powerful assertions such as
{@link android.test.MoreAsserts#assertContainsRegex}, which does regular expression
matching.
</li>
<li>
{@link android.test.ViewAsserts} contains useful assertions about Views. For example
it contains {@link android.test.ViewAsserts#assertHasScreenCoordinates} that tests if a View
has a particular X and Y position on the visible screen. These asserts simplify testing of
geometry and alignment in the UI.
</li>
</ul>
<h3 id="MockObjectClasses">Mock object classes</h3>
<p>
To facilitate dependency injection in testing, Android provides classes that create mock system
objects such as {@link android.content.Context} objects,
{@link android.content.ContentProvider} objects, {@link android.content.ContentResolver}
objects, and {@link android.app.Service} objects. Some test cases also provide mock
{@link android.content.Intent} objects. You use these mocks both to isolate tests
from the rest of the system and to facilitate dependency injection for testing. These classes
are found in the Java packages {@link android.test} and {@link android.test.mock}.
</p>
<p>
Mock objects isolate tests from a running system by stubbing out or overriding
normal operations. For example, a {@link android.test.mock.MockContentResolver}
replaces the normal resolver framework with its own local framework, which is isolated
from the rest of the system. MockContentResolver also also stubs out the
{@link android.content.ContentResolver#notifyChange(Uri, ContentObserver, boolean)} method
so that observer objects outside the test environment are not accidentally triggered.
</p>
<p>
Mock object classes also facilitate dependency injection by providing a subclass of the
normal object that is non-functional except for overrides you define. For example, the
{@link android.test.mock.MockResources} object provides a subclass of
{@link android.content.res.Resources} in which all the methods throw Exceptions when called.
To use it, you override only those methods that must provide information.
</p>
<p>
These are the mock object classes available in Android:
</p>
<h4 id="SimpleMocks">Simple mock object classes</h4>
<p>
{@link android.test.mock.MockApplication}, {@link android.test.mock.MockContext},
{@link android.test.mock.MockContentProvider}, {@link android.test.mock.MockCursor},
{@link android.test.mock.MockDialogInterface}, {@link android.test.mock.MockPackageManager}, and
{@link android.test.mock.MockResources} provide a simple and useful mock strategy. They are
stubbed-out versions of the corresponding system object class, and all of their methods throw an
{@link java.lang.UnsupportedOperationException} exception if called. To use them, you override
the methods you need in order to provide mock dependencies.
</p>
<p class="Note"><strong>Note:</strong>
{@link android.test.mock.MockContentProvider}
and {@link android.test.mock.MockCursor} are new as of API level 8.
</p>
<h4 id="ResolverMocks">Resolver mock objects</h4>
<p>
{@link android.test.mock.MockContentResolver} provides isolated testing of content providers by
masking out the normal system resolver framework. Instead of looking in the system to find a
content provider given an authority string, MockContentResolver uses its own internal table. You
must explicitly add providers to this table using
{@link android.test.mock.MockContentResolver#addProvider(String,ContentProvider)}.
</p>
<p>
With this feature, you can associate a mock content provider with an authority. You can create
an instance of a real provider but use test data in it. You can even set the provider for an
authority to <code>null</code>. In effect, a MockContentResolver object isolates your test
from providers that contain real data. You can control the
function of the provider, and you can prevent your test from affecting real data.
</p>
<h3 id="ContextMocks">Contexts for testing</h3>
<p>
Android provides two Context classes that are useful for testing:
</p>
<ul>
<li>
{@link android.test.IsolatedContext} provides an isolated {@link android.content.Context},
File, directory, and database operations that use this Context take place in a test area.
Though its functionality is limited, this Context has enough stub code to respond to
system calls.
<p>
This class allows you to test an application's data operations without affecting real
data that may be present on the device.
</p>
</li>
<li>
{@link android.test.RenamingDelegatingContext} provides a Context in which
most functions are handled by an existing {@link android.content.Context}, but
file and database operations are handled by a {@link android.test.IsolatedContext}.
The isolated part uses a test directory and creates special file and directory names.
You can control the naming yourself, or let the constructor determine it automatically.
<p>
This object provides a quick way to set up an isolated area for data operations,
while keeping normal functionality for all other Context operations.
</p>
</li>
</ul>
<h2 id="InstrumentationTestRunner">Running Tests</h2>
<p>
Test cases are run by a test runner class that loads the test case class, set ups,
runs, and tears down each test. An Android test runner must also be instrumented, so that
the system utility for starting applications can control how the test package
loads test cases and the application under test. You tell the Android platform
which instrumented test runner to use by setting a value in the test package's manifest file.
</p>
<p>
{@link android.test.InstrumentationTestRunner} is the primary Android test runner class. It
extends the JUnit test runner framework and is also instrumented. It can run any of the test
case classes provided by Android and supports all possible types of testing.
</p>
<p>
You specify <code>InstrumentationTestRunner</code> or a subclass in your test package's
manifest file, in the <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">
instrumentation</a> element. Also, <code>InstrumentationTestRunner</code> code resides
in the shared library <code>android.test.runner</code>, which is not normally linked to
Android code. To include it, you must specify it in a
<a href="{@docRoot}guide/topics/manifest/uses-library-element.html">uses-library</a> element.
You do not have to set up these elements yourself. Both Eclipse with ADT and the
<code>android</code> command-line tool construct them automatically and add them to your
test package's manifest file.
</p>
<p class="Note">
<strong>Note:</strong> If you use a test runner other than
<code>InstrumentationTestRunner</code>, you must change the &lt;instrumentation&gt;
element to point to the class you want to use.
</p>
<p>
To run {@link android.test.InstrumentationTestRunner}, you use internal system classes called by
Android tools. When you run a test in Eclipse with ADT, the classes are called automatically.
When you run a test from the command line, you run these classes with
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge (adb)</a>.
</p>
<p>
The system classes load and start the test package, kill any processes that
are running an instance of the application under test, and then load a new instance of the
application under test. They then pass control to
{@link android.test.InstrumentationTestRunner}, which runs
each test case class in the test package. You can also control which test cases and
methods are run using settings in Eclipse with ADT, or using flags with the command-line tools.
</p>
<p>
Neither the system classes nor {@link android.test.InstrumentationTestRunner} run
the application under test. Instead, the test case does this directly. It either calls methods
in the application under test, or it calls its own methods that trigger lifecycle events in
the application under test. The application is under the complete control of the test case,
which allows it to set up the test environment (the test fixture) before running a test. This
is demonstrated in the previous <a href="#ActivitySnippet">code snippet</a> that tests an
Activity that displays a Spinner widget.
</p>
<p>
To learn more about running tests, please read the topics
<a href="{@docRoot}guide/developing/testing/testing_eclipse.html"">
Testing in Eclipse, with ADT</a> or
<a href="{@docRoot}guide/developing/testing/testing_otheride.html">
Testing in Other IDes</a>.
</p>
<h2 id="TestResults">Seeing Test Results</h2>
<p>
The Android testing framework returns test results back to the tool that started the test.
If you run a test in Eclipse with ADT, the results are displayed in a new JUnit view pane. If
you run a test from the command line, the results are displayed in <code>STDOUT</code>. In
both cases, you see a test summary that displays the name of each test case and method that
was run. You also see all the assertion failures that occurred. These include pointers to the
line in the test code where the failure occurred. Assertion failures also list the expected
value and actual value.
</p>
<p>
The test results have a format that is specific to the IDE that you are using. The test
results format for Eclipse with ADT is described in
<a href="{@docRoot}guide/developing/testing/testing_eclipse.html#RunTestEclipse">
Testing in Eclipse, with ADT</a>. The test results format for tests run from the
command line is described in
<a href="{@docRoot}guide/developing/testing/testing_otheride.html#RunTestsCommand">
Testing in Other IDEs</a>.
</p>
<h2 id="Monkeys">monkey and monkeyrunner</h2>
<p>
The SDK provides two tools for functional-level application testing:
</p>
<ul>
<li>
The <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>,
usually called "monkey", is a command-line tool that sends pseudo-random streams of
keystrokes, touches, and gestures to a device. You run it with the
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb) tool.
You use it to stress-test your application and report back errors that are encountered.
You can repeat a stream of events by running the tool each time with the same random
number seed.
</li>
<li>
The <a href="{@docRoot}guide/developing/tools/monkeyrunner_concepts.html">monkeyrunner</a> tool
is an API and execution environment for test programs written in Python. The API
includes functions for connecting to a device, installing and uninstalling packages,
taking screenshots, comparing two images, and running a test package against an
application. Using the API, you can write a wide range of large, powerful, and complex
tests. You run programs that use the API with the <code>monkeyrunner</code> command-line
tool.
</li>
</ul>
<h2 id="PackageNames">Working With Package names</h2>
<p>
In the test environment, you work with both Android application package names and
Java package identifiers. Both use the same naming format, but they represent substantially
different entities. You need to know the difference to set up your tests correctly.
</p>
<p>
An Android package name is a unique system name for a <code>.apk</code> file, set by the
&quot;android:package&quot; attribute of the &lt;manifest&gt; element in the package's
manifest. The Android package name of your test package must be different from the
Android package name of the application under test. By default, Android tools create the
test package name by appending ".test" to the package name of the application under test.
</p>
<p>
The test package also uses an Android package name to target the application package it
tests. This is set in the &quot;android:targetPackage&quot; attribute of the
&lt;instrumentation&gt; element in the test package's manifest.
</p>
<p>
A Java package identifier applies to a source file. This package name reflects the directory
path of the source file. It also affects the visibility of classes and members to each other.
</p>
<p>
Android tools that create test projects set up an Android test package name for you.
From your input, the tools set up the test package name and the target package name for the
application under test. For these tools to work, the application project must already exist.
</p>
<p>
By default, these tools set the Java package identifier for the test class to be the same
as the Android package identifier. You may want to change this if you want to expose
members in the application under test by giving them package visibility. If you do this,
change only the Java package identifier, not the Android package names, and change only the
test case source files. Do not change the Java package name of the generated
<code>R.java</code> class in your test package, because it will then conflict with the
<code>R.java</code> class in the application under test. Do not change the Android package name
of your test package to be the same as the application it tests, because then their names
will no longer be unique in the system.
</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>
describes the key functionality you should test in an Android application, and the key
situations that might affect that functionality.
</p>
<p>
Most unit testing is specific to the Android component you are testing.
The topics <a href="{@docRoot}guide/topics/testing/activity_testing.html">Activity Testing</a>,
<a href="{@docRoot}guide/topics/testing/contentprovider_testing.html">
Content Provider Testing</a>, and <a href="{@docRoot}guide/topics/testing/service_testing.html">
Service Testing</a> each have a section entitled "What To Test" that lists possible testing
areas.
</p>
<p>
When possible, you should run these tests on an actual device. If this is not possible, you can
use the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> with
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> configured for
the hardware, screens, and versions you want to test.
</p>
<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 Android testing, try one of the
testing tutorials or sample test packages:
</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 application.
</li>
<li>
The sample test package <a href="{@docRoot}resources/samples/AlarmServiceTest"}>
Alarm Service Test</a> is an example of testing a {@link android.app.Service}. It contains
a set of unit tests for the Alarm Service sample application's {@link android.app.Service}.
</li>
</ul>
base/docs/html/guide/topics/testing/what_to_test.jd
+84
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>