The general syntax of the am instrument command is:
am instrument [flags] <test_package>/<runner_class>
The main input parameters to am instrument are described in the following table:
Parameter Value Description
<test_package> The Android package name of the test application.
The value of the package attribute of the manifest element in the test application's manifest file.
<runner_class> The class name of the instrumented test runner you are using.
This is usually InstrumentationTestRunner.
The flags for am instrument are described in the following table:
Page 4 of 7 Testing In Other IDEs | Android Developers
9/7/2010
file://V:\android-sdk-windows\docs\guide\developing\testing\testing_otheride.html
Flag Value Description
-w (none) Forces am instrument 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.
-r (none) 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 -e perf true (documented in the section Instrument options).
-e <test_options> Provides testing options , in the form of key-value pairs. The am instrument tool passes these to the specified instrumentation class via its onCreate() method. You can specify multiple occurrences of -e <test_options. The keys and values are described in the next table.
The only instrumentation class that understands these key-value pairs is
InstrumentationTestRunner (or a subclass). Using them with any other class has no effect.
Instrument options
The am instrument tool passes testing options to InstrumentationTestRunner or a subclass in the form of key-value pairs, using the -e flag, with this syntax:
-e <key> <value>
Where applicable, a <key> may have multiple values separated by a comma (,). For example, this invocation of InstrumentationTestRunner provides multiple values for the package key:
$ adb shell am instrument -w -e package
com.android.test.package1,com.android.test.package2 com.android.test/android.test.InstrumentationTestRunner
The following table describes the key-value pairs and their result. Please review the Usage Notes following the table.
Page 5 of 7 Testing In Other IDEs | Android Developers
9/7/2010
file://V:\android-sdk-windows\docs\guide\developing\testing\testing_otheride.html
Key Value Description
package <Java_package_name> The fully-qualified Java 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 Android package name; a test application has a single Android package name but may have several Java packages within it.
class <class_name> The fully-qualified Java class name for one of the test case classes. Only this test case class is executed.
<class_name>#method name
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.
func true Runs all test classes that extend InstrumentationTestCase.
unit true Runs all test classes that do not extend either
InstrumentationTestCase or PerformanceTestCase.
size [small | medium |
large]
Runs a test method annotated by size. The annotations are
@SmallTest, @MediumTest, and @LargeTest.
perf true Runs all test classes that implement PerformanceTestCase.
When you use this option, also specify the -r flag for am instrument, so that the output is kept in raw format and not re-formatted as test results.
debug true Runs tests in debug mode.
log true Loads and logs all specified tests, but does not run them. The
test information appears in STDOUT. Use this to verify combinations of other filters and test specifications.
emma true Runs an EMMA code coverage analysis and writes the output
to /data//coverage.ec on the device. To override the file location, use the coverageFile key that is described in the following entry.
Note: This option requires an EMMA-instrumented build of the test application, which you can generate with the coverage target.
coverageFile <filename> 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 emma key.
-e Flag Usage Notes
am instrument invokes onCreate(Bundle) with a Bundle containing the key-value pairs.
•
The package key takes precedence over the class 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 class key.
•
The func key and unit key are mutually exclusive.
•
Instrument examples
Here are some examples of using am instrument to run tests. They are based on the following structure:
The test application has the Android package name com.android.demo.app.tests
•
There are three test classes:
•
UnitTests, which contains the methods testPermissions and testSaveState.
◦
Page 6 of 7 Testing In Other IDEs | Android Developers
9/7/2010
file://V:\android-sdk-windows\docs\guide\developing\testing\testing_otheride.html
↑ Go to top FunctionTests, which contains the methods testCamera, testXVGA, and testHardKeyboard.
◦
IntegrationTests, which contains the method testActivityProvider.
◦
The test runner is InstrumentationTestRunner.
•
Running the Entire Test Application
To run all of the test classes in the test application, enter:
$ adb shell am instrument -w
com.android.demo.app.tests/android.test.InstrumentationTestRunner
Running All Tests in a Test Case Class To run all of the tests in the class UnitTests, enter:
$ adb shell am instrument -w \
-e class com.android.demo.app.tests.UnitTests \
com.android.demo.app.tests/android.test.InstrumentationTestRunner
am instrument gets the value of the -e flag, detects the class keyword, and runs all the methods in the UnitTests class.
Selecting a Subset of Tests
To run all of the tests in UnitTests, and the testCamera method in FunctionTests, enter:
$ adb shell am instrument -w \ -e class
com.android.demo.app.tests.UnitTests,com.android.demo.app.tests.FunctionTests#testCam era \
com.android.demo.app.tests/android.test.InstrumentationTestRunner
You can find more examples of the command in the documentation for InstrumentationTestRunner.
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 2.2 r1 - 14 May 2010 15:20
Site Terms of Service - Privacy Policy - Brand Guidelines
Page 7 of 7 Testing In Other IDEs | Android Developers
9/7/2010
file://V:\android-sdk-windows\docs\guide\developing\testing\testing_otheride.html