diff options
Diffstat (limited to 'docs/html/guide/developing/testing')
| -rw-r--r-- | docs/html/guide/developing/testing/index.jd | 36 | ||||
| -rw-r--r-- | docs/html/guide/developing/testing/testing_eclipse.jd | 535 | ||||
| -rw-r--r-- | docs/html/guide/developing/testing/testing_otheride.jd | 694 |
3 files changed, 0 insertions, 1265 deletions
diff --git a/docs/html/guide/developing/testing/index.jd b/docs/html/guide/developing/testing/index.jd deleted file mode 100644 index 8a08959..0000000 --- a/docs/html/guide/developing/testing/index.jd +++ /dev/null @@ -1,36 +0,0 @@ -page.title=Testing -@jd:body -<p> - Android includes powerful tools for setting up and running test applications. - Whether you are working in Eclipse with ADT or working from the command line, these tools - help you set up and run your tests within an emulator or the device you are targeting. - The documents listed below explain how to work with the tools in your development environment. -</p> -<p> - If you aren't yet familiar with the Android testing framework, please read the topic - <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a> - before you get started. - For a step-by-step introduction to Android testing, try the <a - href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, Testing</a> - tutorial, which introduces basic testing concepts and procedures. - 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. -</p> -<dl> - <dt><a href="testing_eclipse.html">Testing from Eclipse, with ADT</a></dt> - <dd> - The ADT plugin lets you quickly set up and manage test projects directly in - the Eclipse UI. Once you have written your tests, you can build and run them and - then see the results in the Eclipse JUnit view. You can also use the SDK command-line - tools to execute your tests if needed. - </dd> - <dt><a href="testing_otheride.html">Testing from Other IDEs</a></dt> - <dd> - The SDK command-line tools provide the same capabilities as the ADT plugin. You can - use them to set up and manage test projects, build your test application, - run your tests, and see the results. You use - the <code>android</code> tool to create and manage test projects, the Ant build system - to compile them, and the <code>adb</code> tool to install and run them. - </dd> -</dl> diff --git a/docs/html/guide/developing/testing/testing_eclipse.jd b/docs/html/guide/developing/testing/testing_eclipse.jd deleted file mode 100644 index 4e9ecca..0000000 --- a/docs/html/guide/developing/testing/testing_eclipse.jd +++ /dev/null @@ -1,535 +0,0 @@ -page.title=Testing from Eclipse with ADT -parent.title=Testing -parent.link=index.html -@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 an Android application with the - basic processes for creating and running applications with ADT, as described in - <a href="{@docRoot}guide/developing/projects/projects-eclipse.html">Managing Projects from -Eclipse</a> - and <a href="{@docRoot}guide/developing/building/building-eclipse.html">Building and Running -from Eclipse</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 from 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> diff --git a/docs/html/guide/developing/testing/testing_otheride.jd b/docs/html/guide/developing/testing/testing_otheride.jd deleted file mode 100644 index 7745ae7..0000000 --- a/docs/html/guide/developing/testing/testing_otheride.jd +++ /dev/null @@ -1,694 +0,0 @@ -page.title=Testing from Other IDEs -parent.title=Testing -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li> - <a href="#CreateTestProjectCommand">Working with Test Projects</a> - <ol> - <li> - <a href="#CreateTestProject">Creating a test project</a> - </li> - <li> - <a href="#UpdateTestProject">Updating a test project</a> - </li> - </ol> - </li> - <li> - <a href="#CreateTestApp">Creating a Test Package</a> - </li> - <li> - <a href="#RunTestsCommand">Running Tests</a> - <ol> - <li> - <a href="#RunTestsAnt">Quick build and run with Ant</a> - </li> - <li> - <a href="#RunTestsDevice">Running tests on a device or emulator</a> - </li> - </ol> - </li> - <li> - <a href="#AMSyntax">Using the Instrument Command</a> - <ol> - <li> - <a href="#AMOptionsSyntax">Instrument options</a> - </li> - <li> - <a href="#RunTestExamples">Instrument examples</a> - </li> - </ol> - </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/tools/adb.html">Android Debug Bridge</a> - </li> - </ol> - </div> -</div> -<p> - This document describes how to create and run tests directly from the command line. - You can use the techniques described here if you are developing in an IDE other than Eclipse - or if you prefer to work from the command line. This document assumes that you already know how - to create a Android application in your programming environment. Before you start this - document, you should read the topic - <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, - which provides an overview of Android testing. -</p> -<p> - If you are developing in Eclipse with ADT, you can set up and run your tests - directly in Eclipse. For more information, please read - <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> - Testing from Eclipse with ADT</a>. -</p> -<h2 id="CreateTestProjectCommand">Working with Test Projects</h2> -<p> - You use the <code>android</code> tool to create test projects. - You also use <code>android</code> to convert existing test code into an Android test project, - or to add the <code>run-tests</code> Ant target to an existing Android test project. - These operations are described in more detail in the section <a href="#UpdateTestProject"> - Updating a test project</a>. The <code>run-tests</code> target is described in - <a href="#RunTestsAnt">Quick build and run with Ant</a>. -</p> -<h3 id="CreateTestProject">Creating a test project</h3> -<p> - To create a test project with the <code>android</code> tool, enter: -</p> -<pre> -android create test-project -m <main_path> -n <project_name> -p <test_path> -</pre> -<p> - You must supply all the flags. The following table explains them in detail: -</p> -<table> - <tr> - <th>Flag</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>-m, --main</code></td> - <td> - Path to the project of the application under test, relative to the test package - directory. - </td> - <td> - For example, if the application under test is in <code>source/HelloAndroid</code>, and - you want to create the test project in <code>source/HelloAndroidTest</code>, then the - value of <code>--main</code> should be <code>../HelloAndroid</code>. - <p> - To learn more about choosing the location of test projects, please read - <a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjects"> - Testing Fundamentals</a>. - </p> - </td> - </tr> - <tr> - <td><code>-n, --name</code></td> - <td>Name that you want to give the test project.</td> - <td> </td> - </tr> - <tr> - <td><code>-p, --path</code></td> - <td>Directory in which you want to create the new test project.</td> - <td> - The <code>android</code> tool creates the test project files and directory structure - in this directory. If the directory does not exist, <code>android</code> creates it. - </td> - </tr> -</table> -<p> - If the operation is successful, <code>android</code> lists to STDOUT the names of the files - and directories it has created. -</p> -<p> - This creates a new test project with the appropriate directories and build files. The directory - structure and build file contents are identical to those in a regular Android application - project. They are described in detail in the topic - <a href="{@docRoot}guide/developing/projects/index.html">Managing Projects</a>. -</p> -<p> - The operation also creates an <code>AndroidManifest.xml</code> file with instrumentation - information. When you run the test, Android uses this information to load the application you - are testing and control it with instrumentation. -</p> -<p> - For example, suppose you create the <a href="{@docRoot}resources/tutorials/hello-world.html"> - Hello, World</a> tutorial application in the directory <code>~/source/HelloAndroid</code>. - In the tutorial, this application uses the package name <code>com.example.helloandroid</code> - and the activity name <code>HelloAndroid</code>. You can to create the test for this in - <code>~/source/HelloAndroidTest</code>. To do so, you enter: -</p> -<pre> -$ cd ~/source -$ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAndroidTest -</pre> -<p> - This creates a directory called <code>~/src/HelloAndroidTest</code>. In the new directory you - see the file <code>AndroidManifest.xml</code>. This file contains the following - instrumentation-related elements and attributes: -</p> -<ul> - <li> - <code><application></code>: to contain the - <code><uses-library></code> element. - </li> - <li> - <code><uses-library android:name="android.test.runner"</code>: - specifies this testing application uses the <code>android.test.runner</code> library. - </li> - <li> - <code><instrumentation></code>: contains attributes that control Android - instrumentation. The attributes are: - <ul> - <li> - <code>android:name="android.test.InstrumentationTestRunner"</code>: - {@link android.test.InstrumentationTestRunner} runs test cases. It extends both - JUnit test case runner classes and Android instrumentation classes. - </li> - <li> - <code>android:targetPackage="com.example.helloandroid"</code>: specifies - that the tests in HelloAndroidTest should be run against the application with the - <em>Android</em> package name <code>com.example.helloandroid</code>. This is the - package name of the <a - href="{@docRoot}resources/tutorials/hello-world.html">Hello, World</a> - tutorial application. - </li> - <li> - <code>android:label="Tests for .HelloAndroid"</code>: specifies a - user-readable label for the instrumentation class. By default, - the <code>android</code> tool gives it the value "Tests for " plus - the name of the main Activity of the application under test. - </li> - </ul> - </li> -</ul> -<h3 id="UpdateTestProject">Updating a test project</h3> -<p> - You use the <code>android</code> tool when you need to change the path to the - project of the application under test. If you are changing an existing test project created in - Eclipse with ADT so that you can also build and run it from the command line, you must use the - "create" operation. See the section <a href="#CreateTestProject">Creating a test project</a>. -</p> -<p class="note"> - <strong>Note:</strong> If you change the Android package name of the application under test, - you must <em>manually</em> change the value of the <code><android:targetPackage></code> - attribute within the <code>AndroidManifest.xml</code> file of the test package. - Running <code>android update test-project</code> does not do this. -</p> -<p> - To update a test project with the <code>android</code> tool, enter: -</p> -<pre>android update test-project -m <main_path> -p <test_path></pre> - -<table> - <tr> - <th>Flag</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>-m, --main</code></td> - <td>The path to the project of the application under test, relative to the test project</td> - <td> - For example, if the application under test is in <code>source/HelloAndroid</code>, and - the test project is in <code>source/HelloAndroidTest</code>, then the value for - <code>--main</code> is <code>../HelloAndroid</code>. - </td> - </tr> - <tr> - <td><code>-p, --path</code></td> - <td>The of the test project.</td> - <td> - For example, if the test project is in <code>source/HelloAndroidTest</code>, then the - value for <code>--path</code> is <code>HelloAndroidTest</code>. - </td> - </tr> -</table> -<p> - If the operation is successful, <code>android</code> lists to STDOUT the names of the files - and directories it has created. -</p> -<h2 id="CreateTestApp">Creating a Test Package</h2> -<p> - Once you have created a test project, you populate it with a test package. - The application does not require an {@link android.app.Activity Activity}, - although you can define one if you wish. Although your test package 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> - If you run your tests with {@link android.test.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 package, 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> - To learn more about creating test packages, see the topic <a - href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, - which provides an overview of Android testing. If you prefer to follow a tutorial, - try the <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> - tutorial, which leads you through the creation of tests for an actual Android application. -</p> -<h2 id="RunTestsCommand">Running Tests</h2> -<p> - You run tests from the command line, either with Ant or with an - <a href="{@docRoot}guide/developing/tools/adb.html"> - Android Debug Bridge (adb)</a> shell. -</p> -<h3 id="RunTestsAnt">Quick build and run with Ant</h3> -<p> - You can use Ant to run all the tests in your test project, using the target - <code>run-tests</code>, which is created automatically when you create a test project with - the <code>android</code> tool. -</p> -<p> - This target re-builds your main project and test project if necessary, installs the test - application to the current AVD or device, and then runs all the test classes in the test - application. The results are directed to <code>STDOUT</code>. -</p> -<p> - You can update an existing test project to use this feature. To do this, use the - <code>android</code> tool with the <code>update test-project</code> option. This is described - in the section <a href="#UpdateTestProject">Updating a test project</a>. -</p> -<h3 id="RunTestsDevice">Running tests on a device or emulator</h3> -<p> - When you run tests from the command line with - <a href="{@docRoot}guide/developing/tools/adb.html"> - Android Debug Bridge (adb)</a>, you get more options for choosing the tests - to run than with any other method. You can select individual test methods, filter tests - according to their annotation, or specify testing options. Since the test run is controlled - entirely from a command line, you can customize your testing with shell scripts in various ways. -</p> -<p> - To run a test from the command line, you run <code>adb shell</code> to start a command-line - shell on your device or emulator, and then in the shell run the <code>am instrument</code> - command. You control <code>am</code> and your tests with command-line flags. -</p> -<p> - As a shortcut, you can start an <code>adb</code> shell, call <code>am instrument</code>, and - specify command-line flags all on one input line. The shell opens on the device or emulator, - runs your tests, produces output, and then returns to the command line on your computer. -</p> -<p> - To run a test with <code>am instrument</code>: -</p> -<ol> - <li> - If necessary, rebuild your main application and test package. - </li> - <li> - Install your test package and main application Android package files - (<code>.apk</code> files) to your current Android device or emulator</li> - <li> - At the command line, enter: -<pre> -$ adb shell am instrument -w <test_package_name>/<runner_class> -</pre> - <p> - where <code><test_package_name></code> is the Android package name of your test - application, and <code><runner_class></code> is the name of the Android test - runner class you are using. The Android package name is the value of the - <code>package</code> attribute of the <code>manifest</code> element in the manifest file - (<code>AndroidManifest.xml</code>) of your test package. The Android test runner - class is usually {@link android.test.InstrumentationTestRunner}. - </p> - <p> - Your test results appear in <code>STDOUT</code>. - </p> - </li> -</ol> -<p> - This operation starts an <code>adb</code> shell, then runs <code>am instrument</code> - with the specified parameters. This particular form of the command will run all of the tests - in your test package. You can control this behavior with flags that you pass to - <code>am instrument</code>. These flags are described in the next section. -</p> -<h2 id="AMSyntax">Using the am instrument Command</h2> -<p> - The general syntax of the <code>am instrument</code> command is: -</p> -<pre> - am instrument [flags] <test_package>/<runner_class> -</pre> -<p> - The main input parameters to <code>am instrument</code> are described in the following table: -</p> -<table> - <tr> - <th> - Parameter - </th> - <th> - Value - </th> - <th> - Description - </th> - </tr> - <tr> - <td> - <code><test_package></code> - </td> - <td> - The Android package name of the test package. - </td> - <td> - The value of the <code>package</code> attribute of the <code>manifest</code> - element in the test package's manifest file. - </td> - </tr> - <tr> - <td> - <code><runner_class></code> - </td> - <td> - The class name of the instrumented test runner you are using. - </td> - <td> - This is usually {@link android.test.InstrumentationTestRunner}. - </td> - </tr> -</table> -<p> - The flags for <code>am instrument</code> are described in the following table: -</p> -<table> - <tr> - <th> - Flag - </th> - <th> - Value - </th> - <th> - Description - </th> - </tr> - <tr> - <td> - <code>-w</code> - </td> - <td> - (none) - </td> - <td> - Forces <code>am instrument</code> to wait until the instrumentation terminates - before terminating itself. The net effect is to keep the shell open until the tests - have finished. This flag is not required, but if you do not use it, you will not - see the results of your tests. - </td> - </tr> - <tr> - <td> - <code>-r</code> - </td> - <td> - (none) - </td> - <td> - Outputs results in raw format. Use this flag when you want to collect - performance measurements, so that they are not formatted as test results. This flag is - designed for use with the flag <code>-e perf true</code> (documented in the section - <a href="#AMOptionsSyntax">Instrument options</a>). - </td> - </tr> - <tr> - <td> - <code>-e</code> - </td> - <td> - <test_options> - </td> - <td> - Provides testing options as key-value pairs. The - <code>am instrument</code> tool passes these to the specified instrumentation class - via its <code>onCreate()</code> method. You can specify multiple occurrences of - <code>-e <test_options></code>. The keys and values are described in the - section <a href="#AMOptionsSyntax">am instrument options</a>. - <p> - The only instrumentation class that uses these key-value pairs is - {@link android.test.InstrumentationTestRunner} (or a subclass). Using them with - any other class has no effect. - </p> - </td> - </tr> -</table> - -<h3 id="AMOptionsSyntax">am instrument options</h3> -<p> - The <code>am instrument</code> tool passes testing options to - <code>InstrumentationTestRunner</code> or a subclass in the form of key-value pairs, - using the <code>-e</code> flag, with this syntax: -</p> -<pre> - -e <key> <value> -</pre> -<p> - Some keys accept multiple values. You specify multiple values in a comma-separated list. - For example, this invocation of <code>InstrumentationTestRunner</code> provides multiple - values for the <code>package</code> key: -</p> -<pre> -$ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \ -> com.android.test/android.test.InstrumentationTestRunner -</pre> -<p> - The following table describes the key-value pairs and their result. Please review the - <strong>Usage Notes</strong> following the table. -</p> -<table> - <tr> - <th>Key</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <code>package</code> - </td> - <td> - <Java_package_name> - </td> - <td> - The fully-qualified <em>Java</em> package name for one of the packages in the test - application. Any test case class that uses this package name is executed. Notice that - this is not an <em>Android</em> package name; a test package has a single - Android package name but may have several Java packages within it. - </td> - </tr> - <tr> - <td rowspan="2"><code>class</code></td> - <td><class_name></td> - <td> - The fully-qualified Java class name for one of the test case classes. Only this test - case class is executed. - </td> - </tr> - <tr> - <td><class_name><strong>#</strong>method name</td> - <td> - A fully-qualified test case class name, and one of its methods. Only this method is - executed. Note the hash mark (#) between the class name and the method name. - </td> - </tr> - <tr> - <td><code>func</code></td> - <td><code>true</code></td> - <td> - Runs all test classes that extend {@link android.test.InstrumentationTestCase}. - </td> - </tr> - <tr> - <td><code>unit</code></td> - <td><code>true</code></td> - <td> - Runs all test classes that do <em>not</em> extend either - {@link android.test.InstrumentationTestCase} or - {@link android.test.PerformanceTestCase}. - </td> - </tr> - <tr> - <td><code>size</code></td> - <td> - [<code>small</code> | <code>medium</code> | <code>large</code>] - </td> - <td> - Runs a test method annotated by size. The annotations are <code>@SmallTest</code>, - <code>@MediumTest</code>, and <code>@LargeTest</code>. - </td> - </tr> - <tr> - <td><code>perf</code></td> - <td><code>true</code></td> - <td> - Runs all test classes that implement {@link android.test.PerformanceTestCase}. - When you use this option, also specify the <code>-r</code> flag for - <code>am instrument</code>, so that the output is kept in raw format and not - re-formatted as test results. - </td> - </tr> - <tr> - <td><code>debug</code></td> - <td><code>true</code></td> - <td> - Runs tests in debug mode. - </td> - </tr> - <tr> - <td><code>log</code></td> - <td><code>true</code></td> - <td> - Loads and logs all specified tests, but does not run them. The test - information appears in <code>STDOUT</code>. Use this to verify combinations of other - filters and test specifications. - </td> - </tr> - <tr> - <td><code>emma</code></td> - <td><code>true</code></td> - <td> - Runs an EMMA code coverage analysis and writes the output to - <code>/data//coverage.ec</code> on the device. To override the file location, use the - <code>coverageFile</code> key that is described in the following entry. - <p class="note"> - <strong>Note:</strong> This option requires an EMMA-instrumented build of the test - application, which you can generate with the <code>coverage</code> target. - </p> - </td> - </tr> - <tr> - <td><code>coverageFile</code></td> - <td><code><filename></code></td> - <td> - Overrides the default location of the EMMA coverage file on the device. Specify this - value as a path and filename in UNIX format. The default filename is described in the - entry for the <code>emma</code> key. - </td> - </tr> -</table> -<strong><code>-e</code> Flag Usage Notes</strong> -<ul> - <li> - <code>am instrument</code> invokes - {@link android.test.InstrumentationTestRunner#onCreate(Bundle)} - with a {@link android.os.Bundle} containing the key-value pairs. - </li> - <li> - The <code>package</code> key takes precedence over the <code>class</code> key. If you - specifiy a package, and then separately specify a class within that package, Android - will run all the tests in the package and ignore the <code>class</code> key. - </li> - <li> - The <code>func</code> key and <code>unit</code> key are mutually exclusive. - </li> -</ul> -<h3 id="RunTestExamples">Usage examples</h3> -<p> -The following sections provide examples of using <code>am instrument</code> to run tests. -They are based on the following structure:</p> -<ul> - <li> - The test package has the Android package name <code>com.android.demo.app.tests</code> - </li> - <li> - There are three test classes: - <ul> - <li> - <code>UnitTests</code>, which contains the methods - <code>testPermissions</code> and <code>testSaveState</code>. - </li> - <li> - <code>FunctionTests</code>, which contains the methods - <code>testCamera</code>, <code>testXVGA</code>, and <code>testHardKeyboard</code>. - </li> - <li> - <code>IntegrationTests</code>, - which contains the method <code>testActivityProvider</code>. - </li> - </ul> - </li> - <li> - The test runner is {@link android.test.InstrumentationTestRunner}. - </li> -</ul> -<h4>Running the entire test package</h4> -<p> - To run all of the test classes in the test package, enter: -</p> -<pre> -$ adb shell am instrument -w com.android.demo.app.tests/android.test.InstrumentationTestRunner -</pre> -<h4>Running all tests in a test case class</h4> -<p> - To run all of the tests in the class <code>UnitTests</code>, enter: -</p> -<pre> -$ adb shell am instrument -w \ -> -e class com.android.demo.app.tests.UnitTests \ -> com.android.demo.app.tests/android.test.InstrumentationTestRunner -</pre> -<p> - <code>am instrument</code> gets the value of the <code>-e</code> flag, detects the - <code>class</code> keyword, and runs all the methods in the <code>UnitTests</code> class. -</p> -<h4>Selecting a subset of tests</h4> -<p> - To run all of the tests in <code>UnitTests</code>, and the <code>testCamera</code> method in - <code>FunctionTests</code>, enter: -</p> -<pre> -$ adb shell am instrument -w \ -> -e class com.android.demo.app.tests.UnitTests,com.android.demo.app.tests.FunctionTests#testCamera \ -> com.android.demo.app.tests/android.test.InstrumentationTestRunner -</pre> -<p> - You can find more examples of the command in the documentation for - {@link android.test.InstrumentationTestRunner}. -</p> |