diff options
Diffstat (limited to 'docs/html/guide/developing/testing/testing_eclipse.jd')
| -rw-r--r-- | docs/html/guide/developing/testing/testing_eclipse.jd | 370 |
1 files changed, 370 insertions, 0 deletions
diff --git a/docs/html/guide/developing/testing/testing_eclipse.jd b/docs/html/guide/developing/testing/testing_eclipse.jd new file mode 100644 index 0000000..da1c0f0 --- /dev/null +++ b/docs/html/guide/developing/testing/testing_eclipse.jd @@ -0,0 +1,370 @@ +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 Application</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. + + 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>. + + 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 and Instrumentation</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 application'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 application and include in + them flags that are passed to the Android testing framework. + </li> + <li> + It lets you run your test application without leaving Eclipse. ADT builds both the + application under test and the test application automatically, installs them if + necessary to your device or emulator, runs the test application, 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 + 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 + <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"> + <code><instrumentation></code></a> element in its manifest file. + </p> + <p> + The <strong>New Android Test Project</strong> dialog makes it easy for you to generate a + new test project that has the proper structure, including the + <code><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 Select a Wizard dialog. + </li> + <li> + 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. + </li> + <li> + 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. + </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 you will use to test your application. Make this the same as the + build target of the application under test. + </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> +<p> + +</p> +<h2 id="CreateTestAppEclipse">Creating a Test Application</h2> +<p> + 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. +</p> +<p> + 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. +</p> + +<p> + To create a test application, start with one of Android's test classes in the Java package {@link android.test android.test}. + These extend the JUnit {@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test classes + also provide instrumentation for testing. +</p> +<p> + For test classes that extend {@link junit.framework.TestCase TestCase}, you probably want to override + the <code>setUp()</code> and <code>tearDown()</code> methods: +</p> +<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. You can use <code>setUp()</code> + to instantiate a new <code>Intent</code> object with the action <code>ACTION_MAIN</code>. You can + then use this intent to start the Activity under test. + <p class="note"><strong>Note:</strong> If you override this method, call + <code>super.setUp()</code> as the first statement in your code. + </p> + </li> + <li> + <code>tearDown()</code>: This method is invoked after all the test methods in the class. Use + it to do garbage collection and re-setting before moving on to the next set of tests. + <p class="note"><strong>Note:</strong> If you override this method, you must call + <code>super.tearDown()</code> as the <em>last</em> statement in your code.</p> + </li> +</ul> +<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 the section + <a href="{@docRoot}guide/developing/testing/testing_otheride.html#CreateProject"> + Creating a test project</a> in the topic + <a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other + IDEs</a>. + </p> + </div> +</div> +<p> + 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 <code>adb</code> 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. +</p> +<p> + 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 +</p> +<p> + To run a test in Eclipse, you have two choices:</p> +<ol> + <li> + Run a test just as you run an application, by selecting + <strong>Run As... > Android JUnit Test</strong> from the project's context menu or + from the main menu's <strong>Run</strong> item. + </li> + <li> + Create an Eclipse run configuration for your test project. This is useful if you want multiple test suites, each consisting of selected tests from the project. To run + a test suite, you run the test configuration. + <p> + Creating and running test configurations is described in the next section. + </p> + </li> +</ol> +<p>To create and run a test suite using a run configuration:</p> +<ol> + <li> + In the Package Explorer, select the test + project, then from the main menu, select + <strong>Run > Run Configurations...</strong>. The + Run Configurations dialog appears. + </li> + <li> + In the left-hand pane, find the + Android JUnit Test entry. + In the right-hand pane, click the Test tab. + The Name: text box + shows the name of your project. The + Test class: dropdown box shows one your project's classes + test classes in your project. + </li> + <li> + To run one test class, click Run a single test, then enter your project + name in the Project: text box and the class name in the + Test class: text box. + <p> + To run all the test classes, + click Run all tests in the selected project or package, + then enter the project or package name in the text box. + </p> + </li> + <li> + Now click the Target tab. + <ul> + <li> + Optional: If you are using the emulator, click + Automatic, then in the Android Virtual Device (AVD) + selection table, select an existing AVD. + </li> + <li> + In the Emulator Launch Parameters pane, set the + Android emulator flags you want to use. These are documented in the topic + <a href="{@docRoot}guide/developing/tools/emulator.html#startup-options">Emulator Startup Options</a>. + </li> + </ul> + <li> + Click the Common tab. In the + Save As pane, click Local to save + this run configuration locally, or click Shared to + save it to another project. + </li> + <li> + Optional: Add the configuration to the Run toolbar and the <strong>Favorites</strong> + menu: in the Display in Favorites pane + click the checkbox next to Run. + </li> + <li> + Optional: To add this configuration to the <strong>Debug</strong> menu and toolbar, click + the checkbox next to Debug. + </li> + <li> + To save your settings, click Close.<br/> + <p class="note"><strong>Note:</strong> Although you can run the test immediately by + clicking Run, you should save the test first and then + run it by selecting it from the Eclipse standard toolbar.</p> + </li> + <li> + On the Eclipse standard toolbar, click the down arrow next to the + green Run arrow. This displays a menu of saved Run and Debug + configurations. + </li> + <li> + Select the test run configuration you just created. + </li> + <li> + The progress of your test appears in the Console view. + You should see the following messages, among others: + <ul> + <li> + <code>Performing Android.test.InstrumentationTestRunner JUnit launch</code><br> + The class name that proceeds "JUnit" depends on the Android instrumentation + class you have chosen. + </li> + <li> + If you are using an emulator and you have not yet started it, then you will see + the message: + <p> + <code>Automatic Target Mode: launching new emulator with compatible + AVD <em>avdname</em></code><br>(where <em>avdname</em> is the name of + the AVD you are using.) + </p> + </li> + <li> + If you have not already installed your test application, then you will see + the message: + <p> + <code>Uploading <em>testclass</em>.apk onto device '<em>device-id</em>'</code><br> + where <em>testclass</em> is the name of your unit test class and <em>device-id</em> + is the name and port for your test device or emulator, followed by the message <code>Installing <em>testclass</em>.apk</code> + </p> + </li> + <li> + <code>Launching instrumentation Android.test.InstrumentationTestRunner on device <em>device-id</em></code>.<br> + This indicates that Android's Instrumentation system is now testing your code. Again, the + instrumentation class name depends on the Android instrumentation class you have chosen. + </li> + <li> + <code>Test run complete</code>.<br> When you see this, your unit tests have finished. + </li> + </ul> +</ol> +<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 application (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 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> |