1 page.title=Service Testing 2 parent.title=Testing 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ol> 10 <li> 11 <a href="#DesignAndTest">Service Design and Testing</a> 12 </li> 13 <li> 14 <a href="#ServiceTestCase">ServiceTestCase</a> 15 </li> 16 <li> 17 <a href="#MockObjects">Mock object classes</a> 18 </li> 19 <li> 20 <a href="#TestAreas">What to Test</a> 21 </li> 22 </ol> 23 <h2>Key Classes</h2> 24 <ol> 25 <li>{@link android.test.InstrumentationTestRunner}</li> 26 <li>{@link android.test.ServiceTestCase}</li> 27 <li>{@link android.test.mock.MockApplication}</li> 28 <li>{@link android.test.RenamingDelegatingContext}</li> 29 </ol> 30 <h2>Related Tutorials</h2> 31 <ol> 32 <li> 33 <a href="{@docRoot}resources/tutorials/testing/helloandroid_test.html"> 34 Hello, Testing</a> 35 </li> 36 <li> 37 <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a> 38 </li> 39 </ol> 40 <h2>See Also</h2> 41 <ol> 42 <li> 43 <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> 44 Testing in Eclipse, with ADT</a> 45 </li> 46 <li> 47 <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> 48 Testing in Other IDEs</a> 49 </li> 50 </ol> 51 </div> 52 </div> 53 <p> 54 Android provides a testing framework for Service objects that can run them in 55 isolation and provides mock objects. The test case class for Service objects is 56 {@link android.test.ServiceTestCase}. Since the Service class assumes that it is separate 57 from its clients, you can test a Service object without using instrumentation. 58 </p> 59 <p> 60 This document describes techniques for testing Service objects. If you aren't familiar with the 61 Service class, please read the <a href="{@docRoot}guide/topics/fundamentals/services.html"> 62 Services</a> document. If you aren't familiar with Android testing, please read 63 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, 64 the introduction to the Android testing and instrumentation framework. 65 </p> 66 <h2 id="DesignAndTest">Service Design and Testing</h2> 67 <p> 68 When you design a Service, you should consider how your tests can examine the various states 69 of the Service lifecycle. If the lifecycle methods that start up your Service, such as 70 {@link android.app.Service#onCreate() onCreate()} or 71 {@link android.app.Service#onStartCommand(Intent, int, int) onStartCommand()} do not normally 72 set a global variable to indicate that they were successful, you may want to provide such a 73 variable for testing purposes. 74 </p> 75 <p> 76 Most other testing is facilitated by the methods in the {@link android.test.ServiceTestCase} 77 test case class. For example, the {@link android.test.ServiceTestCase#getService()} method 78 returns a handle to the Service under test, which you can test to confirm that the Service is 79 running even at the end of your tests. 80 </p> 81 <h2 id="ServiceTestCase">ServiceTestCase</h2> 82 <p> 83 {@link android.test.ServiceTestCase} extends the JUnit {@link junit.framework.TestCase} class 84 with with methods for testing application permissions and for controlling the application and 85 Service under test. It also provides mock application and Context objects that isolate your 86 test from the rest of the system. 87 </p> 88 <p> 89 {@link android.test.ServiceTestCase} defers initialization of the test environment until you 90 call {@link android.test.ServiceTestCase#startService(Intent) ServiceTestCase.startService()} or 91 {@link android.test.ServiceTestCase#bindService(Intent) ServiceTestCase.bindService()}. This 92 allows you to set up your test environment, particularly your mock objects, before the Service 93 is started. 94 </p> 95 <p> 96 Notice that the parameters to <code>ServiceTestCase.bindService()</code>are different from 97 those for <code>Service.bindService()</code>. For the <code>ServiceTestCase</code> version, 98 you only provide an Intent. Instead of returning a boolean, 99 <code>ServiceTestCase.bindService()</code> returns an object that subclasses 100 {@link android.os.IBinder}. 101 </p> 102 <p> 103 The {@link android.test.ServiceTestCase#setUp()} method for {@link android.test.ServiceTestCase} 104 is called before each test. It sets up the test fixture by making a copy of the current system 105 Context before any test methods touch it. You can retrieve this Context by calling 106 {@link android.test.ServiceTestCase#getSystemContext()}. If you override this method, you must 107 call <code>super.setUp()</code> as the first statement in the override. 108 </p> 109 <p> 110 The methods {@link android.test.ServiceTestCase#setApplication(Application) setApplication()} 111 and {@link android.test.AndroidTestCase#setContext(Context)} setContext()} allow you to set 112 a mock Context or mock Application (or both) for the Service, before you start it. These mock 113 objects are described in <a href="#MockObjects">Mock object classes</a>. 114 </p> 115 <p> 116 By default, {@link android.test.ServiceTestCase} runs the test method 117 {@link android.test.AndroidTestCase#testAndroidTestCaseSetupProperly()}, which asserts that 118 the base test case class successfully set up a Context before running. 119 </p> 120 <h2 id="MockObjects">Mock object classes</h2> 121 <p> 122 <code>ServiceTestCase</code> assumes that you will use a mock Context or mock Application 123 (or both) for the test environment. These objects isolate the test environment from the 124 rest of the system. If you don't provide your own instances of these objects before you 125 start the Service, then {@link android.test.ServiceTestCase} will create its own internal 126 instances and inject them into the Service. You can override this behavior by creating and 127 injecting your own instances before starting the Service 128 </p> 129 <p> 130 To inject a mock Application object into the Service under test, first create a subclass of 131 {@link android.test.mock.MockApplication}. <code>MockApplication</code> is a subclass of 132 {@link android.app.Application} in which all the methods throw an Exception, so to use it 133 effectively you subclass it and override the methods you need. You then inject it into the 134 Service with the 135 {@link android.test.ServiceTestCase#setApplication(Application) setApplication()} method. 136 This mock object allows you to control the application values that the Service sees, and 137 isolates it from the real system. In addition, any hidden dependencies your Service has on 138 its application reveal themselves as exceptions when you run the test. 139 </p> 140 <p> 141 You inject a mock Context into the Service under test with the 142 {@link android.test.AndroidTestCase#setContext(Context) setContext()} method. The mock 143 Context classes you can use are described in more detail in 144 <a href="{@docRoot}guide/topics/testing/testing_android.html#MockObjectClasses"> 145 Testing Fundamentals</a>. 146 </p> 147 <h2 id="TestAreas">What to Test</h2> 148 <p> 149 The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> 150 lists general considerations for testing Android components. 151 Here are some specific guidelines for testing a Service: 152 </p> 153 <ul> 154 <li> 155 Ensure that the {@link android.app.Service#onCreate()} is called in response to 156 {@link android.content.Context#startService(Intent) Context.startService()} or 157 {@link android.content.Context#bindService(Intent,ServiceConnection,int) Context.bindService()}. 158 Similarly, you should ensure that {@link android.app.Service#onDestroy()} is called in 159 response to {@link android.content.Context#stopService(Intent) Context.stopService()}, 160 {@link android.content.Context#unbindService(ServiceConnection) Context.unbindService()}, 161 {@link android.app.Service#stopSelf()}, or 162 {@link android.app.Service#stopSelfResult(int) stopSelfResult()}. 163 </li> 164 <li> 165 Test that your Service correctly handles multiple calls from 166 <code>Context.startService()</code>. Only the first call triggers 167 <code>Service.onCreate()</code>, but all calls trigger a call to 168 <code>Service.onStartCommand()</code>. 169 <p> 170 In addition, remember that <code>startService()</code> calls don't 171 nest, so a single call to <code>Context.stopService()</code> or 172 <code>Service.stopSelf()</code> (but not <code>stopSelf(int)</code>) 173 will stop the Service. You should test that your Service stops at the correct point. 174 </p> 175 </li> 176 <li> 177 Test any business logic that your Service implements. Business logic includes checking for 178 invalid values, financial and arithmetic calculations, and so forth. 179 </li> 180 </ul> 181
