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>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
135classes</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