docs/html/guide/developing/testing/testing_otheride.jd

   1 page.title=Testing In Other IDEs
   2 @jd:body
   3
   4 <div id="qv-wrapper">
   5     <div id="qv">
   6         <h2>In this document</h2>
   7             <ol>
   8                 <li>
   9                     <a href="#CreateTestProjectCommand">Working with Test Projects</a>
  10                     <ol>
  11                         <li>
  12                             <a href="#CreateTestProject">Creating a test project</a>
  13                         </li>
  14                         <li>
  15                             <a href="#UpdateTestProject">Updating a test project</a>
  16                         </li>
  17                     </ol>
  18                 </li>
  19                 <li>
  20                     <a href="#CreateTestApp">Creating a Test Package</a>
  21                 </li>
  22                 <li>
  23                     <a href="#RunTestsCommand">Running Tests</a>
  24                     <ol>
  25                         <li>
  26                             <a href="#RunTestsAnt">Quick build and run with Ant</a>
  27                         </li>
  28                         <li>
  29                             <a href="#RunTestsDevice">Running tests on a device or emulator</a>
  30                         </li>
  31                     </ol>
  32                 </li>
  33                 <li>
  34                     <a href="#AMSyntax">Using the Instrument Command</a>
  35                     <ol>
  36                         <li>
  37                             <a href="#AMOptionsSyntax">Instrument options</a>
  38                         </li>
  39                         <li>
  40                             <a href="#RunTestExamples">Instrument examples</a>
  41                         </li>
  42                     </ol>
  43                 </li>
  44             </ol>
  45         <h2>See Also</h2>
  46             <ol>
  47                 <li>
  48                     <a href="{@docRoot}guide/topics/testing/testing_android.html">
  49                         Testing Fundamentals</a>
  50                 </li>
  51                 <li>
  52                     <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>
  53                 </li>
  54             </ol>
  55     </div>
  56 </div>
  57 <p>
  58     This document describes how to create and run tests directly from the command line.
  59     You can use the techniques described here if you are developing in an IDE other than Eclipse
  60     or if you prefer to work from the command line. This document assumes that you already know how
  61     to create a Android application in your programming environment. Before you start this
  62     document, you should read the topic
  63     <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
  64     which provides an overview of Android testing.
  65 </p>
  66 <p>
  67     If you are developing in Eclipse with ADT, you can set up and run your tests
  68     directly in Eclipse. For more information, please read
  69     <a href="{@docRoot}guide/developing/testing/testing_eclipse.html">
  70     Testing in Eclipse, with ADT</a>.
  71 </p>
  72 <h2 id="CreateTestProjectCommand">Working with Test Projects</h2>
  73 <p>
  74     You use the <code>android</code> tool to create test projects.
  75     You also use <code>android</code> to convert existing test code into an Android test project,
  76     or to add the <code>run-tests</code> Ant target to an existing Android test project.
  77     These operations are described in more detail in the section <a href="#UpdateTestProject">
  78     Updating a test project</a>. The <code>run-tests</code> target is described in
  79     <a href="#RunTestsAnt">Quick build and run with Ant</a>.
  80 </p>
  81 <h3 id="CreateTestProject">Creating a test project</h3>
  82 <p>
  83     To create a test project with the <code>android</code> tool, enter:
  84 </p>
  85 <pre>
  86 android create test-project -m &lt;main_path&gt; -n &lt;project_name&gt; -p &lt;test_path&gt;
  87 </pre>
  88 <p>
  89     You must supply all the flags. The following table explains them in detail:
  90 </p>
  91 <table>
  92     <tr>
  93         <th>Flag</th>
  94         <th>Value</th>
  95         <th>Description</th>
  96     </tr>
  97     <tr>
  98         <td><code>-m, --main</code></td>
  99         <td>
 100             Path to the project of the application under test, relative to the test package
 101             directory.
 102         </td>
 103         <td>
 104             For example, if the application under test is in <code>source/HelloAndroid</code>, and
 105             you want to create the test project in <code>source/HelloAndroidTest</code>, then the
 106             value of <code>--main</code> should be <code>../HelloAndroid</code>.
 107         <p>
 108             To learn more about choosing the location of test projects, please read
 109             <a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjects">
 110             Testing Fundamentals</a>.
 111         </p>
 112         </td>
 113     </tr>
 114     <tr>
 115         <td><code>-n, --name</code></td>
 116         <td>Name that you want to give the test project.</td>
 117         <td>&nbsp;</td>
 118     </tr>
 119     <tr>
 120         <td><code>-p, --path</code></td>
 121         <td>Directory in which you want to create the new test project.</td>
 122         <td>
 123             The <code>android</code> tool creates the test project files and directory structure
 124             in this directory. If the directory does not exist, <code>android</code> creates it.
 125         </td>
 126     </tr>
 127 </table>
 128 <p>
 129     If the operation is successful, <code>android</code> lists to STDOUT the names of the files
 130     and directories it has created.
 131 </p>
 132 <p>
 133     This creates a new test project with the appropriate directories and build files. The directory
 134     structure and build file contents are identical to those in a regular Android application
 135     project. They are described in detail in the topic
 136     <a href="{@docRoot}guide/developing/other-ide.html">Developing In Other IDEs</a>.
 137 </p>
 138 <p>
 139     The operation also creates an <code>AndroidManifest.xml</code> file with instrumentation
 140     information. When you run the test, Android uses this information to load the application you
 141     are testing and control it with instrumentation.
 142 </p>
 143 <p>
 144     For example, suppose you create the <a href="{@docRoot}resources/tutorials/hello-world.html">
 145     Hello, World</a> tutorial application in the directory <code>~/source/HelloAndroid</code>.
 146     In the tutorial, this application uses the package name <code>com.example.helloandroid</code>
 147     and the activity name <code>HelloAndroid</code>. You can to create the test for this in
 148     <code>~/source/HelloAndroidTest</code>. To do so, you enter:
 149 </p>
 150 <pre>
 151 $ cd ~/source
 152 $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAndroidTest
 153 </pre>
 154 <p>
 155     This creates a directory called <code>~/src/HelloAndroidTest</code>. In the new directory you
 156     see the file <code>AndroidManifest.xml</code>. This file contains the following
 157     instrumentation-related elements and attributes:
 158 </p>
 159 <ul>
 160     <li>
 161         <code>&lt;application&gt;</code>: to contain the
 162         <code>&lt;uses-library&gt;</code> element.
 163     </li>
 164     <li>
 165         <code>&lt;uses-library android:name=&quot;android.test.runner&quot;</code>:
 166         specifies this testing application uses the <code>android.test.runner</code> library.
 167     </li>
 168     <li>
 169         <code>&lt;instrumentation&gt;</code>: contains attributes that control Android
 170         instrumentation. The attributes are:
 171         <ul>
 172             <li>
 173                 <code>android:name=&quot;android.test.InstrumentationTestRunner&quot;</code>:
 174                 {@link android.test.InstrumentationTestRunner} runs test cases. It extends both
 175                 JUnit test case runner classes and Android instrumentation classes.
 176             </li>
 177             <li>
 178                 <code>android:targetPackage=&quot;com.example.helloandroid&quot;</code>: specifies
 179                 that the tests in HelloAndroidTest should be run against the application with the
 180                 <em>Android</em> package name <code>com.example.helloandroid</code>. This is the
 181                 package name of the <a
 182                 href="{@docRoot}resources/tutorials/hello-world.html">Hello, World</a>
 183                 tutorial application.
 184             </li>
 185             <li>
 186                 <code>android:label=&quot;Tests for .HelloAndroid&quot;</code>: specifies a
 187                 user-readable label for the instrumentation class. By default,
 188                 the <code>android</code> tool gives it the value &quot;Tests for &quot; plus
 189                 the name of the main Activity of the application under test.
 190             </li>
 191         </ul>
 192     </li>
 193 </ul>
 194 <h3 id="UpdateTestProject">Updating a test project</h3>
 195 <p>
 196     You use the <code>android</code> tool when you need to change the path to the
 197     project of the application under test. If you are changing an existing test project created in
 198     Eclipse with ADT so that you can also build and run it from the command line, you must use the
 199     "create" operation. See the section <a href="#CreateTestProject">Creating a test project</a>.
 200 </p>
 201 <p class="note">
 202     <strong>Note:</strong> If you change the Android package name of the application under test,
 203     you must <em>manually</em> change the value of the <code>&lt;android:targetPackage&gt;</code>
 204     attribute within the <code>AndroidManifest.xml</code> file of the test package.
 205     Running <code>android update test-project</code> does not do this.
 206 </p>
 207 <p>
 208   To update a test project with the <code>android</code> tool, enter:
 209 </p>
 210 <pre>android update-test-project -m &lt;main_path&gt; -p &lt;test_path&gt;</pre>
 211
 212 <table>
 213     <tr>
 214         <th>Flag</th>
 215         <th>Value</th>
 216         <th>Description</th>
 217     </tr>
 218     <tr>
 219         <td><code>-m, --main</code></td>
 220         <td>The path to the project of the application under test, relative to the test project</td>
 221         <td>
 222             For example, if the application under test is in <code>source/HelloAndroid</code>, and
 223             the test project is in <code>source/HelloAndroidTest</code>, then the value for
 224             <code>--main</code> is <code>../HelloAndroid</code>.
 225         </td>
 226     </tr>
 227     <tr>
 228         <td><code>-p, --path</code></td>
 229         <td>The of the test project.</td>
 230         <td>
 231             For example, if the test project is in <code>source/HelloAndroidTest</code>, then the
 232             value for <code>--path</code> is <code>HelloAndroidTest</code>.
 233         </td>
 234     </tr>
 235 </table>
 236 <p>
 237     If the operation is successful, <code>android</code> lists to STDOUT the names of the files
 238     and directories it has created.
 239 </p>
 240 <h2 id="CreateTestApp">Creating a Test Package</h2>
 241 <p>
 242     Once you have created a test project, you populate it with a test package.
 243     The application does not require an {@link android.app.Activity Activity},
 244     although you can define one if you wish. Although your test package can
 245     combine Activities, Android test class extensions, JUnit extensions, or
 246     ordinary classes, you should extend one of the Android test classes or JUnit classes,
 247     because these provide the best testing features.
 248 </p>
 249 <p>
 250     If you run your tests with {@link android.test.InstrumentationTestRunner}
 251     (or a related test runner), then it will run all the methods in each class. You can modify
 252     this behavior by using the {@link junit.framework.TestSuite TestSuite} class.
 253 </p>
 254
 255 <p>
 256     To create a test package, start with one of Android's test classes in the Java package
 257     {@link android.test android.test}. These extend the JUnit
 258     {@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test
 259     classes also provide instrumentation for testing.
 260 </p>
 261 <p>
 262     For test classes that extend {@link junit.framework.TestCase TestCase}, you probably want to
 263     override the <code>setUp()</code> and <code>tearDown()</code> methods:
 264 </p>
 265 <ul>
 266     <li>
 267         <code>setUp()</code>: This method is invoked before any of the test methods in the class.
 268         Use it to set up the environment for the test. You can use <code>setUp()</code>
 269         to instantiate a new <code>Intent</code> object with the action <code>ACTION_MAIN</code>.
 270         You can then use this intent to start the Activity under test.
 271         <p class="note">
 272             <strong>Note:</strong> If you override this method, call
 273             <code>super.setUp()</code> as the first statement in your code.
 274         </p>
 275     </li>
 276     <li>
 277         <code>tearDown()</code>: This method is invoked after all the test methods in the class. Use
 278         it to do garbage collection and re-setting before moving on to the next set of tests.
 279         <p class="note"><strong>Note:</strong> If you override this method, you must call
 280         <code>super.tearDown()</code> as the <em>last</em> statement in your code.</p>
 281     </li>
 282 </ul>
 283 <p>
 284     Another useful convention is to add the method <code>testPreConditions()</code> to your test
 285     class. Use this method to test that the application under test is initialized correctly. If this
 286     test fails, you know that that the initial conditions were in error. When this happens, further
 287     test results are suspect, regardless of whether or not the tests succeeded.
 288 </p>
 289 <p>
 290     To learn more about creating test packages, see the topic <a
 291     href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
 292     which provides an overview of Android testing. If you prefer to follow a tutorial,
 293     try the <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
 294     tutorial, which leads you through the creation of tests for an actual Android application.
 295 </p>
 296 <h2 id="RunTestsCommand">Running Tests</h2>
 297 <p>
 298     You run tests from the command line, either with Ant or with an
 299     <a href="{@docRoot}http://developer.android.com/guide/developing/tools/adb.html">
 300     Android Debug Bridge (adb)</a> shell.
 301 </p>
 302 <h3 id="RunTestsAnt">Quick build and run with Ant</h3>
 303 <p>
 304     You can use Ant to run all the tests in your test project, using the target
 305     <code>run-tests</code>, which is created automatically when you create a test project with
 306     the <code>android</code> tool.
 307 </p>
 308 <p>
 309     This target re-builds your main project and test project if necessary, installs the test
 310     application to the current AVD or device, and then runs all the test classes in the test
 311     application. The results are directed to <code>STDOUT</code>.
 312 </p>
 313 <p>
 314     You can update an existing test project to use this feature. To do this, use the
 315     <code>android</code> tool with the <code>update test-project</code> option. This is described
 316     in the section <a href="#UpdateTestProject">Updating a test project</a>.
 317 </p>
 318 <h3 id="RunTestsDevice">Running tests on a device or emulator</h3>
 319 <p>
 320     When you run tests from the command line with
 321     <a href="{@docRoot}http://developer.android.com/guide/developing/tools/adb.html">
 322     Android Debug Bridge (adb)</a>, you get more options for choosing the tests
 323     to run than with any other method. You can select individual test methods, filter tests
 324     according to their annotation, or specify testing options. Since the test run is controlled
 325     entirely from a command line, you can customize your testing with shell scripts in various ways.
 326 </p>
 327 <p>
 328     To run a test from the command line, you run <code>adb shell</code> to start a command-line
 329     shell on your device or emulator, and then in the shell run the <code>am instrument</code>
 330     command. You control <code>am</code> and your tests with command-line flags.
 331 </p>
 332 <p>
 333     As a shortcut, you can start an <code>adb</code> shell, call <code>am instrument</code>, and
 334     specify command-line flags all on one input line. The shell opens on the device or emulator,
 335     runs your tests, produces output, and then returns to the command line on your computer.
 336 </p>
 337 <p>
 338     To run a test with <code>am instrument</code>:
 339 </p>
 340 <ol>
 341     <li>
 342         If necessary, rebuild your main application and test package.
 343     </li>
 344     <li>
 345         Install your test package and main application Android package files
 346         (<code>.apk</code> files) to your current Android device or emulator</li>
 347     <li>
 348         At the command line, enter:
 349 <pre>
 350 $ adb shell am instrument -w &lt;test_package_name&gt;/&lt;runner_class&gt;
 351 </pre>
 352         <p>
 353             where <code>&lt;test_package_name&gt;</code> is the Android package name of your test
 354             application, and <code>&lt;runner_class&gt;</code> is the name of the Android test
 355             runner class you are using. The Android package name is the value of the
 356             <code>package</code> attribute of the <code>manifest</code> element in the manifest file
 357             (<code>AndroidManifest.xml</code>) of your test package. The Android test runner
 358             class is usually {@link android.test.InstrumentationTestRunner}.
 359         </p>
 360         <p>
 361             Your test results appear in <code>STDOUT</code>.
 362         </p>
 363     </li>
 364 </ol>
 365 <p>
 366     This operation starts an <code>adb</code> shell, then runs <code>am instrument</code>
 367     with the specified parameters. This particular form of the command will run all of the tests
 368     in your test package. You can control this behavior with flags that you pass to
 369     <code>am instrument</code>. These flags are described in the next section.
 370 </p>
 371 <h2 id="AMSyntax">Using the am instrument Command</h2>
 372 <p>
 373     The general syntax of the <code>am instrument</code> command is:
 374 </p>
 375 <pre>
 376     am instrument [flags] &lt;test_package&gt;/&lt;runner_class&gt;
 377 </pre>
 378 <p>
 379     The main input parameters to <code>am instrument</code> are described in the following table:
 380 </p>
 381 <table>
 382     <tr>
 383         <th>
 384             Parameter
 385         </th>
 386         <th>
 387             Value
 388         </th>
 389         <th>
 390             Description
 391         </th>
 392     </tr>
 393     <tr>
 394         <td>
 395             <code>&lt;test_package&gt;</code>
 396         </td>
 397         <td>
 398             The Android package name of the test package.
 399         </td>
 400         <td>
 401             The value of the <code>package</code> attribute of the <code>manifest</code>
 402             element in the test package's manifest file.
 403         </td>
 404     </tr>
 405     <tr>
 406         <td>
 407             <code>&lt;runner_class&gt;</code>
 408         </td>
 409         <td>
 410             The class name of the instrumented test runner you are using.
 411         </td>
 412         <td>
 413             This is usually {@link android.test.InstrumentationTestRunner}.
 414         </td>
 415     </tr>
 416 </table>
 417 <p>
 418     The flags for <code>am instrument</code> are described in the following table:
 419 </p>
 420 <table>
 421     <tr>
 422         <th>
 423             Flag
 424         </th>
 425         <th>
 426             Value
 427         </th>
 428         <th>
 429             Description
 430         </th>
 431     </tr>
 432     <tr>
 433         <td>
 434             <code>-w</code>
 435         </td>
 436         <td>
 437             (none)
 438         </td>
 439         <td>
 440             Forces <code>am instrument</code> to wait until the instrumentation terminates
 441             before terminating itself. The net effect is to keep the shell open until the tests
 442             have finished. This flag is not required, but if you do not use it, you will not
 443             see the results of your tests.
 444         </td>
 445     </tr>
 446     <tr>
 447         <td>
 448             <code>-r</code>
 449         </td>
 450         <td>
 451             (none)
 452         </td>
 453         <td>
 454             Outputs results in raw format. Use this flag when you want to collect
 455             performance measurements, so that they are not formatted as test results. This flag is
 456             designed for use with the flag <code>-e perf true</code> (documented in the section
 457             <a href="#AMOptionsSyntax">Instrument options</a>).
 458         </td>
 459     </tr>
 460     <tr>
 461         <td>
 462             <code>-e</code>
 463         </td>
 464         <td>
 465              &lt;test_options&gt;
 466         </td>
 467         <td>
 468             Provides testing options as key-value pairs. The
 469             <code>am instrument</code> tool passes these to the specified instrumentation class
 470             via its <code>onCreate()</code> method. You can specify multiple occurrences of
 471             <code>-e &lt;test_options&gt;</code>. The keys and values are described in the
 472             section <a href="#AMOptionsSyntax">am instrument options</a>.
 473             <p>
 474                 The only instrumentation class that uses these key-value pairs is
 475                 {@link android.test.InstrumentationTestRunner} (or a subclass). Using them with
 476                 any other class has no effect.
 477             </p>
 478         </td>
 479     </tr>
 480 </table>
 481
 482 <h3 id="AMOptionsSyntax">am instrument options</h3>
 483 <p>
 484     The <code>am instrument</code> tool passes testing options to
 485     <code>InstrumentationTestRunner</code> or a subclass in the form of key-value pairs,
 486     using the <code>-e</code> flag, with this syntax:
 487 </p>
 488 <pre>
 489     -e &lt;key&gt; &lt;value&gt;
 490 </pre>
 491 <p>
 492     Some keys accept multiple values. You specify multiple values in a comma-separated list.
 493     For example, this invocation of <code>InstrumentationTestRunner</code> provides multiple
 494     values for the <code>package</code> key:
 495 </p>
 496 <pre>
 497 $ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
 498 &gt; com.android.test/android.test.InstrumentationTestRunner
 499 </pre>
 500 <p>
 501     The following table describes the key-value pairs and their result. Please review the
 502     <strong>Usage Notes</strong> following the table.
 503 </p>
 504 <table>
 505     <tr>
 506         <th>Key</th>
 507         <th>Value</th>
 508         <th>Description</th>
 509     </tr>
 510     <tr>
 511         <td>
 512             <code>package</code>
 513         </td>
 514         <td>
 515             &lt;Java_package_name&gt;
 516         </td>
 517         <td>
 518             The fully-qualified <em>Java</em> package name for one of the packages in the test
 519             application. Any test case class that uses this package name is executed. Notice that
 520             this is not an <em>Android</em> package name; a test package has a single
 521             Android package name but may have several Java packages within it.
 522         </td>
 523     </tr>
 524     <tr>
 525         <td rowspan="2"><code>class</code></td>
 526         <td>&lt;class_name&gt;</td>
 527         <td>
 528             The fully-qualified Java class name for one of the test case classes. Only this test
 529             case class is executed.
 530         </td>
 531     </tr>
 532     <tr>
 533         <td>&lt;class_name&gt;<strong>#</strong>method name</td>
 534         <td>
 535             A fully-qualified test case class name, and one of its methods. Only this method is
 536             executed. Note the hash mark (#) between the class name and the method name.
 537         </td>
 538     </tr>
 539     <tr>
 540         <td><code>func</code></td>
 541         <td><code>true</code></td>
 542         <td>
 543             Runs all test classes that extend {@link android.test.InstrumentationTestCase}.
 544         </td>
 545     </tr>
 546     <tr>
 547         <td><code>unit</code></td>
 548         <td><code>true</code></td>
 549         <td>
 550             Runs all test classes that do <em>not</em> extend either
 551             {@link android.test.InstrumentationTestCase} or
 552             {@link android.test.PerformanceTestCase}.
 553         </td>
 554     </tr>
 555     <tr>
 556         <td><code>size</code></td>
 557         <td>
 558             [<code>small</code> | <code>medium</code> | <code>large</code>]
 559         </td>
 560         <td>
 561             Runs a test method annotated by size. The  annotations are <code>@SmallTest</code>,
 562             <code>@MediumTest</code>, and <code>@LargeTest</code>.
 563         </td>
 564     </tr>
 565     <tr>
 566         <td><code>perf</code></td>
 567         <td><code>true</code></td>
 568         <td>
 569             Runs all test classes that implement {@link android.test.PerformanceTestCase}.
 570             When you use this option, also specify the <code>-r</code> flag for
 571             <code>am instrument</code>, so that the output is kept in raw format and not
 572             re-formatted as test results.
 573         </td>
 574     </tr>
 575     <tr>
 576         <td><code>debug</code></td>
 577         <td><code>true</code></td>
 578         <td>
 579             Runs tests in debug mode.
 580         </td>
 581     </tr>
 582     <tr>
 583         <td><code>log</code></td>
 584         <td><code>true</code></td>
 585         <td>
 586             Loads and logs all specified tests, but does not run them. The test
 587             information appears in <code>STDOUT</code>. Use this to verify combinations of other
 588             filters and test specifications.
 589         </td>
 590     </tr>
 591     <tr>
 592         <td><code>emma</code></td>
 593         <td><code>true</code></td>
 594         <td>
 595             Runs an EMMA code coverage analysis and writes the output to
 596             <code>/data//coverage.ec</code> on the device. To override the file location, use the
 597             <code>coverageFile</code> key that is described in the following entry.
 598             <p class="note">
 599                 <strong>Note:</strong> This option requires an EMMA-instrumented build of the test
 600                 application, which you can generate with the <code>coverage</code> target.
 601             </p>
 602         </td>
 603     </tr>
 604     <tr>
 605         <td><code>coverageFile</code></td>
 606         <td><code>&lt;filename&gt;</code></td>
 607         <td>
 608             Overrides the default location of the EMMA coverage file on the device. Specify this
 609             value as a path and filename in UNIX format. The default filename is described in the
 610             entry for the <code>emma</code> key.
 611         </td>
 612     </tr>
 613 </table>
 614 <strong><code>-e</code> Flag Usage Notes</strong>
 615 <ul>
 616     <li>
 617         <code>am instrument</code> invokes
 618         {@link android.test.InstrumentationTestRunner#onCreate(Bundle)}
 619         with a {@link android.os.Bundle} containing the key-value pairs.
 620     </li>
 621     <li>
 622         The <code>package</code> key takes precedence over the <code>class</code> key. If you
 623         specifiy a package, and then separately specify a class within that package, Android
 624         will run all the tests in the package and ignore the <code>class</code> key.
 625     </li>
 626     <li>
 627         The <code>func</code> key and <code>unit</code> key are mutually exclusive.
 628     </li>
 629 </ul>
 630 <h3 id="RunTestExamples">Usage examples</h3>
 631 <p>
 632 The following sections provide examples of using <code>am instrument</code> to run tests.
 633 They are based on the following structure:</p>
 634 <ul>
 635     <li>
 636         The test package has the Android package name <code>com.android.demo.app.tests</code>
 637     </li>
 638     <li>
 639         There are three test classes:
 640         <ul>
 641             <li>
 642                 <code>UnitTests</code>, which contains the methods
 643                 <code>testPermissions</code> and <code>testSaveState</code>.
 644             </li>
 645             <li>
 646                 <code>FunctionTests</code>, which contains the methods
 647                 <code>testCamera</code>, <code>testXVGA</code>, and <code>testHardKeyboard</code>.
 648             </li>
 649             <li>
 650                 <code>IntegrationTests</code>,
 651                 which contains the method <code>testActivityProvider</code>.
 652             </li>
 653         </ul>
 654     </li>
 655     <li>
 656         The test runner is {@link android.test.InstrumentationTestRunner}.
 657     </li>
 658 </ul>
 659 <h4>Running the entire test package</h4>
 660 <p>
 661     To run all of the test classes in the test package, enter:
 662 </p>
 663 <pre>
 664 $ adb shell am instrument -w com.android.demo.app.tests/android.test.InstrumentationTestRunner
 665 </pre>
 666 <h4>Running all tests in a test case class</h4>
 667 <p>
 668     To run all of the tests in the class <code>UnitTests</code>, enter:
 669 </p>
 670 <pre>
 671 $ adb shell am instrument -w  \
 672 &gt; -e class com.android.demo.app.tests.UnitTests \
 673 &gt; com.android.demo.app.tests/android.test.InstrumentationTestRunner
 674 </pre>
 675 <p>
 676   <code>am instrument</code> gets the value of the <code>-e</code> flag, detects the
 677   <code>class</code> keyword, and runs all the methods in the <code>UnitTests</code> class.
 678 </p>
 679 <h4>Selecting a subset of tests</h4>
 680 <p>
 681     To run all of the tests in <code>UnitTests</code>, and the <code>testCamera</code> method in
 682     <code>FunctionTests</code>, enter:
 683 </p>
 684 <pre>
 685 $ adb shell am instrument -w \
 686 &gt; -e class com.android.demo.app.tests.UnitTests,com.android.demo.app.tests.FunctionTests#testCamera \
 687 &gt; com.android.demo.app.tests/android.test.InstrumentationTestRunner
 688 </pre>
 689 <p>
 690     You can find more examples of the command in the documentation for
 691     {@link android.test.InstrumentationTestRunner}.
 692 </p>