531 lines
24 KiB
Plaintext
531 lines
24 KiB
Plaintext
page.title=Testing In Eclipse, with ADT
|
|
@jd:body
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
<h2>In this document</h2>
|
|
<ol>
|
|
<li><a href="#CreateTestProjectEclipse">Creating a Test Project</a></li>
|
|
<li><a href="#CreateTestAppEclipse">Creating a Test Package</a></li>
|
|
<li><a href="#RunTestEclipse">Running Tests</a></li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
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
|
|
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>.
|
|
You may also want to read
|
|
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
|
|
which provides an overview of the Android testing framework.
|
|
</p>
|
|
<p>
|
|
ADT provides several features that help you set up and manage your testing environment
|
|
effectively:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
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
|
|
<code><instrumentation></code> element in the test package's manifest file.
|
|
</li>
|
|
<li>
|
|
It lets you quickly import the classes of the application under test, so that your
|
|
tests can inspect them.
|
|
</li>
|
|
<li>
|
|
It lets you create run configurations for your test package and include in
|
|
them flags that are passed to the Android testing framework.
|
|
</li>
|
|
<li>
|
|
It lets you run your test package without leaving Eclipse. ADT builds both the
|
|
application under test and the test package automatically, installs them if
|
|
necessary to your device or emulator, runs the test package, and displays the
|
|
results in a separate window in Eclipse.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
If you are not developing in Eclipse or you want to learn how to create and run tests from the
|
|
command line, see
|
|
<a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a>.
|
|
</p>
|
|
<h2 id="CreateTestProjectEclipse">Creating a Test Project</h2>
|
|
<p>
|
|
To set up a test environment for your Android application, you must first create a separate
|
|
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
|
|
source code, resources, a manifest file, and so forth. The test package you
|
|
create is connected to the application under test by an
|
|
<a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">
|
|
<code><instrumentation></code></a> element in its manifest file.
|
|
</p>
|
|
<p>
|
|
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><instrumentation></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>
|
|
<ol>
|
|
<li>
|
|
In Eclipse, select <strong>File > New > Other</strong>. This opens the <em>Select a
|
|
Wizard</em> dialog.
|
|
</li>
|
|
<li>
|
|
In the dialog, in the <em>Wizards</em> drop-down list, find the entry for Android, then
|
|
click the toggle to the left. Select <strong>Android Test Project</strong>, then at the
|
|
bottom of the dialog click <strong>Next</strong>. The <em>New Android Test Project</em>
|
|
wizard appears.
|
|
</li>
|
|
<li>
|
|
Next to <em>Test Project Name</em>, enter a name for the project. You may use any name,
|
|
but you may want to associate the name with the project name for the application under test.
|
|
One way to do this is to take the application's project name, append the string "Test" to
|
|
it, and then use this as the test package project name.
|
|
<p>
|
|
The name becomes part of the suggested project path, but you can change this in the
|
|
next step.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
In the <em>Content</em> panel, examine the suggested path to the project.
|
|
If <em>Use default location</em> is set, then the wizard will suggest a path that is
|
|
a concatenation of the workspace path and the project name you entered. For example,
|
|
if your workspace path is <code>/usr/local/workspace</code> and your project name is
|
|
<code>MyTestApp</code>, then the wizard will suggest
|
|
<code>/usr/local/workspace/MyTestApp</code>. To enter your own
|
|
choice for a path, unselect <em>Use default location</em>, then enter or browse to the
|
|
path where you want your project.
|
|
<p>
|
|
To learn more about choosing the location of test projects, please read
|
|
<a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjectPaths">
|
|
Testing Fundamentals</a>.
|
|
</p>
|
|
</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> > <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> > <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>
|
|
<p>
|
|
You now have to ensure that the constructor is set up correctly. Create a constructor for your
|
|
class that has no arguments; this is required by JUnit. As the first statement in this
|
|
constructor, add a call to the base class' constructor. Each base test case class has its
|
|
own constructor signature. Refer to the class documentation in the documentation for
|
|
{@link android.test} for more information.
|
|
</p>
|
|
<p>
|
|
To control your test environment, you will want to override the <code>setUp()</code> and
|
|
<code>tearDown()</code> methods:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<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 (the test fixture. You can use
|
|
<code>setUp()</code> to instantiate a new Intent with the action <code>ACTION_MAIN</code>.
|
|
You can then use this intent to start the Activity under test.
|
|
</li>
|
|
<li>
|
|
<code>tearDown()</code>: This method is invoked after all the test methods in the class. Use
|
|
it to do garbage collection and to reset the test fixture.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
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
|
|
test fails, you know that that the initial conditions were in error. When this happens, further
|
|
test results are suspect, regardless of whether or not the tests succeeded.
|
|
</p>
|
|
<p>
|
|
The Resources tab contains an
|
|
<a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
|
|
tutorial with more information about creating test classes and methods.
|
|
</p>
|
|
<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... > 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 > 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">
|
|
<h2>Message Examples</h2>
|
|
<p>
|
|
The examples shown in this section come from the
|
|
<a href="{@docRoot}resources/samples/SpinnerTest/index.html">SpinnerTest</a>
|
|
sample test package, which tests the
|
|
<a href="{@docRoot}resources/samples/Spinner/index.html">Spinner</a>
|
|
sample application. This test package is also featured in the
|
|
<a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
|
|
tutorial.
|
|
</p>
|
|
</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>
|
|
In the following description of these messages, <code><em>devicename</em></code> is the name of
|
|
the device or emulator you are using to run the test, and <code><em>port</em></code> is the
|
|
port number for the device. The name and port number are in the format used by the
|
|
<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>
|
|
<ul>
|
|
<li>
|
|
If you are using an emulator and you have not yet started it, then Eclipse
|
|
first starts the emulator. When this is complete, you see
|
|
the message:
|
|
<p>
|
|
<code>HOME is up on device '<em>devicename</em>-<em>port</em>'</code>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
If you have not already installed your test package, then you see
|
|
the message:
|
|
<p>
|
|
<code>Uploading <em>testfile</em> onto device '<em>devicename</em>-<em>port</em>'
|
|
</code>
|
|
</p>
|
|
<p>
|
|
then the message <code>Installing <em>testfile</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: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>
|
|
The upper pane contains test information. In the pane's header, you see the following
|
|
information:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
Total time elapsed for the test package (labeled Finished after <em>x</em> seconds).
|
|
</li>
|
|
<li>
|
|
Number of runs (Runs:) - the number of tests in the entire test class.
|
|
</li>
|
|
<li>
|
|
Number of errors (Errors:) - the number of program errors and exceptions encountered
|
|
during the test run.
|
|
</li>
|
|
<li>
|
|
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
|
|
not encounter an error.
|
|
</li>
|
|
<li>
|
|
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.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
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
|
|
test methods in that class, you click the left arrow to expand the line. You now see a
|
|
line for each test method in the class, and to its right the time it took to run.
|
|
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.
|
|
</p>
|
|
<p>
|
|
The results of a successful test are shown in figure 1.
|
|
</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>
|
|
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
|
|
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.
|
|
</p>
|
|
<p>The results of a failed test are shown in figure 2.</p>
|
|
<a href="{@docRoot}images/testing/eclipse_test_run_failure.png">
|
|
<img src="{@docRoot}images/testing/eclipse_test_run_failure.png"
|
|
alt="" height="372px" id="TestRun"/>
|
|
</a>
|
|
<p class="img-caption">
|
|
<strong>Figure 2.</strong> Messages for a test failure.
|
|
</p>
|