page.title=Testing In Eclipse, with ADT @jd:body

In this document

  1. Creating a Test Project
  2. Creating a Test Application
  3. Running Tests

This topic explains how create and run tests of Android applications in Eclipse with ADT. with the basic processes for creating and running applications with ADT, as described in Developing 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 and Instrumentation, which provides an overview of the Android testing framework.

ADT provides several features that help you set up and manage your testing environment effectively:

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.

Creating a Test Project

To set up a test environment for your Android application, you must first create a separate application project that holds the test code. The new project follows the directory structure used for any Android application. It includes the same types of content and files, such as source code, resources, a manifest file, and so forth. The test application you 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:

  1. In Eclipse, select File > New > Other. This opens the Select a Wizard dialog.
  2. In the dialog, in the Wizards drop-down list, find the entry for Android, then click the toggle to the left. Select Android Test Project, then at the bottom of the dialog click Next. The New Android Test Project wizard appears.
  3. Enter a project name. You may use any name, but you may want to associate the name with the project name for your Application. 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 case project name.
  4. 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).
  5. In the Build Target panel, select the Android SDK platform that you will use to test your application. Make this the same as the build target of the application under test.
  6. 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.

Creating a Test Application

Once you have created a test project, you populate it with a test Android application. This application does not require an {@link android.app.Activity Activity}, although you can define one if you wish. Although your test application can combine Activities, Android test class extensions, JUnit extensions, or ordinary classes, you should extend one of the Android test classes or JUnit classes, because these provide the best testing features.

Test applications do not have an Android GUI. Instead, when you run the application in Eclipse with ADT, its results appear in the JUnit view. If you run your tests with {@link android.test.InstrumentationTestRunner InstrumentationTestRunner} (or a related test runner), then it will run all the methods in each class. You can modify this behavior by using the {@link junit.framework.TestSuite TestSuite} class.

To create a test application, start with one of Android's test classes in the Java package {@link android.test android.test}. These extend the JUnit {@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test classes also provide instrumentation for testing.

For test classes that extend {@link junit.framework.TestCase TestCase}, you probably want to override the setUp() and tearDown() methods:

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.

Running Tests

When you run a test application in Eclipse with ADT, the output appears in an Eclipse view panel. You can run the entire test application, one class, or one method of a class. To do this, Eclipse runs the adb command for running a test application, 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 application, to run a test application 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

To run a test in Eclipse, you have two choices:

  1. Run a test just as you run an application, by selecting Run As... > Android JUnit Test from the project's context menu or from the main menu's Run item.
  2. 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.

    Creating and running test configurations is described in the next section.

To create and run a test suite using a run configuration:

  1. In the Package Explorer, select the test project, then from the main menu, select Run > Run Configurations.... The Run Configurations dialog appears.
  2. In the left-hand pane, find the Android JUnit Test entry. In the right-hand pane, click the Test tab. The Name: text box shows the name of your project. The Test class: dropdown box shows one your project's classes test classes in your project.
  3. 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.

    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.

  4. Now click the Target tab.
  5. 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.
  6. Optional: Add the configuration to the Run toolbar and the Favorites menu: in the Display in Favorites pane click the checkbox next to Run.
  7. Optional: To add this configuration to the Debug menu and toolbar, click the checkbox next to Debug.
  8. To save your settings, click Close.

    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.

  9. 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.
  10. Select the test run configuration you just created.
  11. The progress of your test appears in the Console view. You should see the following messages, among others:

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 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.