1page.title=Content Provider Testing 2parent.title=Testing 3parent.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">Content Provider Design and Testing</a> 12 </li> 13 <li> 14 <a href="#ContentProviderTestAPI">The Content Provider Testing API</a> 15 <ol> 16 <li> 17 <a href="#ProviderTestCase2">ProviderTestCase2 </a> 18 </li> 19 <li> 20 <a href="#MockObjects">Mock object classes</a> 21 </li> 22 </ol> 23 </li> 24 <li> 25 <a href="#WhatToTest">What To Test</a> 26 </li> 27 <li> 28 <a href="#NextSteps">Next Steps</a> 29 </li> 30 </ol> 31 <h2>Key Classes</h2> 32 <ol> 33 <li>{@link android.test.InstrumentationTestRunner}</li> 34 <li>{@link android.test.ProviderTestCase2}</li> 35 <li>{@link android.test.IsolatedContext}</li> 36 <li>{@link android.test.mock.MockContentResolver}</li> 37 </ol> 38 <h2>See Also</h2> 39 <ol> 40 <li> 41 <a 42 href="{@docRoot}guide/topics/testing/testing_android.html"> 43 Testing Fundamentals</a> 44 </li> 45 <li> 46 <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> 47 Testing in Eclipse, with ADT</a> 48 </li> 49 <li> 50 <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> 51 Testing in Other IDEs</a> 52 </li> 53 </ol> 54 </div> 55</div> 56<p> 57 Content providers, which store and retrieve data and make it accessible across applications, 58 are a key part of the Android API. As an application developer you're allowed to provide your 59 own public providers for use by other applications. If you do, then you should test them 60 using the API you publish. 61</p> 62<p> 63 This document describes how to test public content providers, although the information is 64 also applicable to providers that you keep private to your own application. If you aren't 65 familiar with content providers or the Android testing framework, please read 66 <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>, 67 the guide to developing content providers, and 68 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>, 69 the introduction to the Android testing and instrumentation framework. 70</p> 71<h2 id="DesignAndTest">Content Provider Design and Testing</h2> 72<p> 73 In Android, content providers are viewed externally as data APIs that provide 74 tables of data, with their internals hidden from view. A content provider may have many 75 public constants, but it usually has few if any public methods and no public variables. 76 This suggests that you should write your tests based only on the provider's public members. 77 A content provider that is designed like this is offering a contract between itself and its 78 users. 79</p> 80<p> 81 The base test case class for content providers, 82 {@link android.test.ProviderTestCase2}, allows you to test your content provider in an 83 isolated environment. Android mock objects such as {@link android.test.IsolatedContext} and 84 {@link android.test.mock.MockContentResolver} also help provide an isolated test environment. 85</p> 86<p> 87 As with other Android tests, provider test packages are run under the control of the test 88 runner {@link android.test.InstrumentationTestRunner}. The section 89 <a href="{@docRoot}guide/topics/testing/testing_android.html#InstrumentationTestRunner"> 90 Running Tests With InstrumentationTestRunner</a> describes the test runner in 91 more detail. The topic <a href="{@docRoot}guide/developing/testing/testing_eclipse.html"> 92 Testing in Eclipse, with ADT</a> shows you how to run a test package in Eclipse, and the 93 topic <a href="{@docRoot}guide/developing/testing/testing_otheride.html"> 94 Testing in Other IDEs</a> 95 shows you how to run a test package from the command line. 96</p> 97<h2 id="ContentProviderTestAPI">Content Provider Testing API</h2> 98<p> 99 The main focus of the provider testing API is to provide an isolated testing environment. This 100 ensures that tests always run against data dependencies set explicitly in the test case. It 101 also prevents tests from modifying actual user data. For example, you want to avoid writing 102 a test that fails because there was data left over from a previous test, and you want to 103 avoid adding or deleting contact information in a actual provider. 104</p> 105<p> 106 The test case class and mock object classes for provider testing set up this isolated testing 107 environment for you. 108</p> 109<h3 id="ProviderTestCase2">ProviderTestCase2</h3> 110<p> 111 You test a provider with a subclass of {@link android.test.ProviderTestCase2}. This base class 112 extends {@link android.test.AndroidTestCase}, so it provides the JUnit testing framework as well 113 as Android-specific methods for testing application permissions. The most important 114 feature of this class is its initialization, which creates the isolated test environment. 115</p> 116<p> 117 The initialization is done in the constructor for {@link android.test.ProviderTestCase2}, which 118 subclasses call in their own constructors. The {@link android.test.ProviderTestCase2} 119 constructor creates an {@link android.test.IsolatedContext} object that allows file and 120 database operations but stubs out other interactions with the Android system. 121 The file and database operations themselves take place in a directory that is local to the 122 device or emulator and has a special prefix. 123</p> 124<p> 125 The constructor then creates a {@link android.test.mock.MockContentResolver} to use as the 126 resolver for the test. The {@link android.test.mock.MockContentResolver} class is described in 127 detail in the section 128 <a href="{@docRoot}guide/topics/testing/testing_android.html#MockObjectClasses">Mock object 129classes</a>. 130</p> 131<p> 132 Lastly, the constructor creates an instance of the provider under test. This is a normal 133 {@link android.content.ContentProvider} object, but it takes all of its environment information 134 from the {@link android.test.IsolatedContext}, so it is restricted to 135 working in the isolated test environment. All of the tests done in the test case class run 136 against this isolated object. 137</p> 138<h3 id="MockObjects">Mock object classes</h3> 139<p> 140 {@link android.test.ProviderTestCase2} uses {@link android.test.IsolatedContext} and 141 {@link android.test.mock.MockContentResolver}, which are standard mock object classes. To 142 learn more about them, please read 143 <a href="{@docRoot}guide/topics/testing/testing_android.html#MockObjectClasses"> 144 Testing Fundamentals</a>. 145</p> 146<h2 id="WhatToTest">What To Test</h2> 147<p> 148 The topic <a href="{@docRoot}guide/topics/testing/what_to_test.html">What To Test</a> 149 lists general considerations for testing Android components. 150 Here are some specific guidelines for testing content providers. 151</p> 152<ul> 153 <li> 154 Test with resolver methods: Even though you can instantiate a provider object in 155 {@link android.test.ProviderTestCase2}, you should always test with a resolver object 156 using the appropriate URI. This ensures that you are testing the provider using the same 157 interaction that a regular application would use. 158 </li> 159 <li> 160 Test a public provider as a contract: If you intent your provider to be public and 161 available to other applications, you should test it as a contract. This includes 162 the following ideas: 163 <ul> 164 <li> 165 Test with constants that your provider publicly exposes. For 166 example, look for constants that refer to column names in one of the provider's 167 data tables. These should always be constants publicly defined by the provider. 168 </li> 169 <li> 170 Test all the URIs offered by your provider. Your provider may offer several URIs, 171 each one referring to a different aspect of the data. The 172 <a href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample, 173 for example, features a provider that offers one URI for retrieving a list of notes, 174 another for retrieving an individual note by it's database ID, and a third for 175 displaying notes in a live folder. 176 </li> 177 <li> 178 Test invalid URIs: Your unit tests should deliberately call the provider with an 179 invalid URI, and look for errors. Good provider design is to throw an 180 IllegalArgumentException for invalid URIs. 181 182 </li> 183 </ul> 184 </li> 185 <li> 186 Test the standard provider interactions: Most providers offer six access methods: 187 query, insert, delete, update, getType, and onCreate(). Your tests should verify that all 188 of these methods work. These are described in more detail in the topic 189 <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. 190 </li> 191 <li> 192 Test business logic: Don't forget to test the business logic that your provider should 193 enforce. Business logic includes handling of invalid values, financial or arithmetic 194 calculations, elimination or combining of duplicates, and so forth. A content provider 195 does not have to have business logic, because it may be implemented by activities that 196 modify the data. If the provider does implement business logic, you should test it. 197 </li> 198</ul> 199<h2 id="NextSteps">Next Steps</h2> 200<p> 201 To learn how to set up and run tests in Eclipse, please refer to <a 202 href="{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in 203 Eclipse, with ADT</a>. If you're not working in Eclipse, refer to <a 204 href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other 205 IDEs</a>. 206</p> 207<p> 208 If you want a step-by-step introduction to testing activities, try one of the 209 testing tutorials: 210</p> 211<ul> 212 <li> 213 The <a 214 href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, 215 Testing</a> tutorial introduces basic testing concepts and procedures in the 216 context of the Hello, World application. 217 </li> 218 <li> 219 The <a 220 href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity 221 Testing</a> tutorial is an excellent follow-up to the Hello, Testing tutorial. 222 It guides you through a more complex testing scenario that you develop against a 223 more realistic activity-oriented application. 224 </li> 225</ul> 226