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 Developing In Eclipse, with ADT. You may also want to read Testing Fundamentals, which provides an overview of the Android testing framework.
ADT provides several features that help you set up and manage your testing environment effectively:
<instrumentation>
element in the test package's manifest file.
If you are not developing in Eclipse or you want to learn how to create and run tests from the command line, see Testing in Other IDEs.
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
<instrumentation>
element in its manifest file.
The New Android Test Project dialog makes it easy for you to generate a
new test project that has the proper structure, including the
<instrumentation>
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.
To create a test project in Eclipse with ADT:
The name becomes part of the suggested project path, but you can change this in the next step.
/usr/local/workspace
and your project name is
MyTestApp
, then the wizard will suggest
/usr/local/workspace/MyTestApp
. To enter your own
choice for a path, unselect Use default location, then enter or browse to the
path where you want your project.
To learn more about choosing the location of test projects, please read Testing Fundamentals.
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.
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 Running Tests.
To create a test package, start with one of Android's test case classes defined in
android.test
. These extend the JUnit
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
Testing Fundamentals.
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 Testing Fundamentals.
To add a test case class to your project:
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
android.test
for more information.
To control your test environment, you will want to override the setUp()
and
tearDown()
methods:
setUp()
: 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
setUp()
to instantiate a new Intent with the action ACTION_MAIN
.
You can then use this intent to start the Activity under test.
tearDown()
: This method is invoked after all the test methods in the class. Use
it to do garbage collection and to reset the test fixture.
Another useful convention is to add the method testPreconditions()
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.
The Resources tab contains an Activity Testing tutorial with more information about creating test classes and methods.
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.
To run tests created in Eclipse with ADT with command-line tools, you must first
install additional files into the test project using the android
tool's "create test-project" option. To see how to do this, read
Testing in Other IDEs.
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
adb
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.
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.
To run a test in Eclipse, you have two choices:
Creating and running test configurations is described in the next section.
To create and run a test suite using a run configuration:
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.
Note: 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.
The progress of your test appears in the Console view as a series of messages. Each message is
preceded by a timestamp and the .apk
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:
The examples shown in this section come from the SpinnerTest sample test package, which tests the Spinner sample application. This test package is also featured in the Activity Testing tutorial.
[yyyy-mm-dd hh:mm:ss - testfile] Waiting for HOME ('android.process.acore') to be launched...
In the following description of these messages, devicename
is the name of
the device or emulator you are using to run the test, and port
is the
port number for the device. The name and port number are in the format used by the
adb devices
command. Also, testfile
is the .apk
filename of the test
package you are running, and appfile is the filename of the application under test.
HOME is up on device 'devicename-port'
Uploading testfile onto device 'devicename-port'
then the message Installing testfile
.
and finally the message Success!
The following lines are an example of this message sequence:
[2010-07-01 12:44:40 - MyTest] HOME is up on device 'emulator-5554'
[2010-07-01 12:44:40 - MyTest] Uploading MyTest.apk onto device 'emulator-5554'
[2010-07-01 12:44:40 - MyTest] Installing MyTest.apk...
[2010-07-01 12:44:49 - MyTest] Success!
Project dependency found, installing: appfile
then the message Uploading appfile
onto device
'devicename-port'
then the message Installing appfile
and finally the message Success!
The following lines are an example of this message sequence:
[2010-07-01 12:44:49 - MyTest] Project dependency found, installing: MyApp
[2010-07-01 12:44:49 - MyApp] Uploading MyApp.apk onto device 'emulator-5554'
[2010-07-01 12:44:49 - MyApp] Installing MyApp.apk...
[2010-07-01 12:44:54 - MyApp] Success!
Launching instrumentation instrumentation_class on device
devicename-port
instrumentation_class
is the fully-qualified class name of the
instrumentation test runner you have specified (usually
InstrumentationTestRunner
.
InstrumentationTestRunner
builds a list of tests to run,
you see the message
Collecting test information
followed by
Sending test information to Eclipse
Running tests
, 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 Test run complete
.
This indicates that your tests are finished.
The following lines are an example of this message sequence:
[2010-01-01 12:45:02 - MyTest] Launching instrumentation android.test.InstrumentationTestRunner on device emulator-5554
[2010-01-01 12:45:02 - MyTest] Collecting test information
[2010-01-01 12:45:02 - MyTest] Sending test information to Eclipse
[2010-01-01 12:45:02 - MyTest] Running tests...
[2010-01-01 12:45:22 - MyTest] Test run complete
The test results appear in the JUnit view. This is divided into an upper summary pane, and a lower stack trace pane.
The upper pane contains test information. In the pane's header, you see the following information:
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.
The results of a successful test are shown in Figure 1. Messages for a successful test:
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.
The results of a failed test are shown in Figure 2. Messages for a test failure