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