diff options
Diffstat (limited to 'docs/html/guide/developing/instrumentation/inst-testing.jd')
| -rw-r--r-- | docs/html/guide/developing/instrumentation/inst-testing.jd | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/docs/html/guide/developing/instrumentation/inst-testing.jd b/docs/html/guide/developing/instrumentation/inst-testing.jd new file mode 100644 index 0000000..09b0196 --- /dev/null +++ b/docs/html/guide/developing/instrumentation/inst-testing.jd @@ -0,0 +1,236 @@ + +page.title=Instrumentation Testing +@jd:body + +<p>Sometimes you may want to manually interact with your applications to verify that a particular feature or behavior is working properly; why not automate this verification with a JUnit TestCase that can instrument applications?</p> +<p>Instrumentation testing allows you to verify a particular feature or behavior with an automated JUnit TestCase. You can launch activities and providers within an application, send key events, and make assertions about various UI elements.</p> + +This document provides an overview of how to use instrumentation on Android and covers these topics: + +<ul> +<li><a href="#androidInstrumentationTestingClasses">Classes</a></li> +<li><a href="#androidInstrumentationTestingRunning">Running Tests</a></li> +<li><a href="#androidInstrumentationTestingCreating">Creating Tests</a></li> +<li><a href="#androidInstrumentationAliases">Aliases for Running Framework Instrumentation Tests</a></li> +</ul> + + + + +<a name="androidInstrumentationTestingClasses"></a><h2>Classes</h2> + +<p> The following classes help glue together <code>Instrumentation</code> with JUnit testing. </p> +<table> + <tr> + <th scope="col">Class</th> + <th scope="col">Description</th></tr> + <tr> + <td valign="top"><code>InstrumentationTestCase</code></td> + <td valign="top"> + <p>This extends the standard JUnit <code>TestCase</code> and offers access to an <code>Instrumentation</code> class. Write tests inside your instrumentation class any way you see fit. For example, your test might launch activities and send key events. For this to work properly, the instrumentation needs to be injected into the test case.</p> + </td> + </tr> + <tr> + <td valign="top"><code>InstrumentationTestRunner</code></td> + <td valign="top">The instrumentation test runner is an instrumentation that runs instrumentation test cases and injects itself into each test case. Instrumentation test cases need to be grouped together with an instrumentation test runner with the appropriate target package.</td> + </tr> + <tr> + <td valign="top"><code>InstrumentationTestSuite</code></td> + <td valign="top">The instrumentation test suite is a simple extension of the standard JUnit <code>TestSuite</code> that keeps a member <code>Instrumentation</code> variable on hand to inject into each <code>TestCase</code> before running them. It is used by <code>InstrumentationTestRunner</code>.</td> + </tr> +</table> +<p> Three additional base classes extend <code>InstrumentationTestCase</code> to allow you to test <code>Activity</code> and <code>Provider</code> classes:</p> +<table> + <tr> + <th scope="col">Class</th> + <th scope="col">Description</th> + </tr> + <tr> + <td valign="top"><code>ActivityTestCase</code></td> + <td valign="top"><p>This class can be used to write tests for a specific activity. An activity is launched in its <code>setUp()</code> method and finished with <code>tearDown</code>. If you write a test case that extends <code>ActivityTestCase</code>, you can write tests that access the activity using <code>getActivity()</code> and assume it has been set up properly.</p></td> + </tr> + <tr> + <td valign="top"><code>SingleLaunchActivityTestCase</code></td> + <td valign="top">This class is similar to <code>ActivityTestCase</code> except that the activity is launched once per class instead of every time the test case calls setup. </td> + </tr> + <tr> + <td valign="top"><code>ProviderTestCase</code></td> + <td valign="top">This class is similar to <code>ActivityTestCase</code> except that it will setup, tear down, and provide access to the <code>Provider</code> of your choice.</td> + </tr> +</table> + + +<a name="androidInstrumentationTestingRunning"></a><h2>Running Tests</h2> + +<p> To run your tests, use the <code>am instrument</code> command with your <code>InstrumentationTestRunner</code> as its argument. Results are printed as a result of the instrumentation. For example, the following snippet displays the output after running the framework tests with one test failing (note the unusual syntax caused by how instrumentations are run via <code>am</code>):</p> +<pre class="prettify"> +$ adb shell am instrument -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner +INSTRUMENTATION_RESULT: test results:=.......F....... +Time: 6.837 +There was 1 failure: +1) testSetUpConditions(com.google.android.frameworktest.tests.focus.RequestFocusTest)junit.framework.AssertionFailedError: requestFocus() should work from onCreate. + at com.google.android.frameworktest.tests.focus.RequestFocusTest.testSetUpConditions(RequestFocusTest.java:66) + at java.lang.reflect.Method.invokeNative(Native Method) + at android.test.InstrumentationTestSuite.runTest(InstrumentationTestSuite.java:73) + at android.test.InstrumentationTestSuite.runTest(InstrumentationTestSuite.java:73) + at android.test.InstrumentationTestRunner.onStart(InstrumentationTestRunner.java:151) + at android.app.Instrumentation$InstrumentationThread.run(Instrumentation.java:1088) + +FAILURES!!! +Tests run: 14, Failures: 1, Errors: 0 + +<RETURN> to continue + +INSTRUMENTATION_CODE: -1 +$ +</pre> + + +<a name="androidInstrumentationTestingRunningAll"></a><h3>All Tests</h3> + +<pre class="prettify"> +$ adb shell am instrument -w MyInstrumentationTestRunner +</pre> + + +<a name="androidInstrumentationTestingRunningSingleTestCase"></a><h3>A Single Test Case</h3> + +<pre class="prettify"> +$ adb shell am instrument \ + -e class MyInstrumentationTestCase \ + -w MyInstrumentationTestRunner +</pre> + + +<a name="androidInstrumentationTestingRunningSingleTest"></a><h3>A Single Test</h3> + +<pre class="prettify"> +$ adb shell am instrument \ + -e class MyInstrumentationTestCase#myTestMethod \ + -w MyInstrumentationTestRunner +</pre> + + +<a name="androidInstrumentationTestingCreating"></a><h2>Creating Tests</h2> + + + +<a name="androidInstrumentationTestingCreatingTestRunner"></a> + +<h3>New Instrumentation TestRunner</h3> + +<pre> +public class FrameworkInstrumentationTestRunner extends InstrumentationTestRunner { + + @Override + public TestSuite getAllTests() { + InstrumentationTestSuite suite = new InstrumentationTestSuite(this); + + suite.addTestSuite(FocusAfterRemovalTest.class); + suite.addTestSuite(RequestFocusTest.class); + suite.addTestSuite(RequestRectangleVisibleTest.class); + return suite; + } + + @Override + public ClassLoader getLoader() { + return FrameworkInstrumentationTestRunner.class.getClassLoader(); + } +} +</pre> + +<p> Next, in an appropriate <code>AndroidManifest.xml</code>, define the instrumentation for the derived class with the appropriate <code>android:targetPackage</code> set. For example, the snippet below defines the instrumentation runner for the framework tests.</p> + +<pre> +<uses-permission android:name="android.permission.RUN_INSTRUMENTATION" /> + +<instrumentation android:name="android.tests.FrameworkInstrumentationTestRunner" + android:targetPackage="com.google.android.frameworktest" + android:label="framework instrumentation test runner" /> +</pre> + + +<a name="androidInstrumentationTestingCreatingTestCase"></a> + +<h3>New InstrumentationTestCase</h3> + +<p> To create a new test case, write a class that extends <code>InstrumentationTestCase</code> in the same application archive as your test runner. The following snippet illustrates an example <code>ActivityTestCase</code> that tests an activity named <code>MyActivity</code>.</p> +<pre> +public class ButtonPressTest extends ActivityTestCase<MyActivity> { + + Button mLeftButton; + + public ButtonPressTest() { + super("com.example", MyActivity.class); + } + + @Override + public void setUp() throws Exception { + super.setUp(); + mLeftButton = (Button) getActivity().findViewById(R.id.leftButton); + } + + public void testFocusMovesToRight() throws Exception { + assertTrue(mLeftButton.hasFocus()); + getInstrumentation().sendCharacterSync(KeyEvent.KEYCODE_DPAD_RIGHT); + + Button rightButton = (Button) getActivity().findViewById(R.id.rightButton); + assertTrue(rightButton.hasFocus()); + } + + // could have several more tests... +} +</pre> + + +<a name="androidInstrumentationAliases"></a><h2>Aliases for Running Framework Instrumentation Tests</h2> + +<pre class="prettify"> +# compiles and installs FrameworkTests +alias deploytests="(cd tests/FrameworkTests/ && mm) && adb install out/target/product/dream/system/app/FrameworkTest.apk" + +# runs all of FrameworkTests unit tests +alias runtests="adb shell am instrument -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner" + +# runtest TEST: runs a single unit test, for instance runtest view.VisibilityTest +# -- for convenience, you don't have to type the com.google.android.frameworktest.tests. +function runtest { + adb shell am instrument -e class com.google.android.frameworktest.tests.$1 -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner +} + +# debugtest TEST: runs a single unit test in debug mode, for instance runtest view.VisibilityTest +function debugtest { + adb shell am instrument -e debug true -e class com.google.android.frameworktest.tests.$1 -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner +} +</pre> + + +<p><span class="lh2"><a name="androidFooter"></a></span> + + </div> + </div> + <!-- end gc-pagecontent --> + </div> + <!-- end gooey wrapper --> + </div> + <!-- end codesearchresults --> + <div id="gc-footer" dir="ltr"> + <div class="text"> ©2008 Google<!-- - <a href="/">Code Home</a> - <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> - <a href="http://www.google.com/privacy.html">Privacy Policy</a> - <a href="/more">Site Directory</a> --></div> + </div> + <!-- end gc-footer --> +</div> +<!-- end gc-containter --> +<script src="http://www.google-analytics.com/ga.js" type="text/javascript"> +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-18071-1"); + pageTracker._setAllowAnchor(true); + pageTracker._initData(); + pageTracker._trackPageview(); + } catch(e) {} +</script> +<div id="jd-build-id"> v0.3 - 9 June 2008</div> +</div></div></div></body> +</html> + |