docs/html/tools/testing/contentprovider_testing.jd

page.title=Content Provider Testing
parent.title=Testing
parent.link=index.html
@jd:body

<div id="qv-wrapper">
  <div id="qv">
  <h2>In this document</h2>
  <ol>
    <li>
        <a href="#DesignAndTest">Content Provider Design and Testing</a>
    </li>
    <li>
      <a href="#ContentProviderTestAPI">The Content Provider Testing API</a>
      <ol>
        <li>
          <a href="#ProviderTestCase2">ProviderTestCase2 </a>
        </li>
        <li>
          <a href="#MockObjects">Mock object classes</a>
        </li>
      </ol>
    </li>
    <li>
        <a href="#WhatToTest">What To Test</a>
    </li>
    <li>
        <a href="#NextSteps">Next Steps</a>
    </li>
  </ol>
  <h2>Key Classes</h2>
    <ol>
      <li>{@link android.test.InstrumentationTestRunner}</li>
      <li>{@link android.test.ProviderTestCase2}</li>
      <li>{@link android.test.IsolatedContext}</li>
      <li>{@link android.test.mock.MockContentResolver}</li>
    </ol>
  <h2>Related Tutorials</h2>
    <ol>
        <li>
            <a href="{@docRoot}tools/testing/activity_test.html">Activity Testing Tutorial</a>
        </li>
    </ol>
  <h2>See Also</h2>
      <ol>
        <li>
          <a
          href="{@docRoot}tools/testing/testing_android.html">
          Testing Fundamentals</a>
        </li>
        <li>
          <a href="{@docRoot}tools/testing/testing_eclipse.html">
          Testing From Eclipse with ADT</a>
        </li>
        <li>
          <a href="{@docRoot}tools/testing/testing_otheride.html">
          Testing From Other IDEs</a>
        </li>
      </ol>
  </div>
</div>
<p>
    Content providers, which store and retrieve data and make it accessible across applications,
    are a key part of the Android API. As an application developer you're allowed to provide your
    own public providers for use by other applications. If you do, then you should test them
    using the API you publish.
</p>
<p>
    This document describes how to test public content providers, although the information is
    also applicable to providers that you keep private to your own application. If you aren't
    familiar with content  providers or the Android testing framework, please read
    <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>,
    the guide to developing content providers, and
    <a href="{@docRoot}tools/testing/testing_android.html">Testing Fundamentals</a>,
    the introduction to the Android testing and instrumentation framework.
</p>
<h2 id="DesignAndTest">Content Provider Design and Testing</h2>
<p>
    In Android, content providers are viewed externally as data APIs that provide
    tables of data, with their internals hidden from view. A content provider may have many
    public constants, but it usually has few if any public methods and no public variables.
    This suggests that you should write your tests based only on the provider's public members.
    A content provider that is designed like this is offering a contract between itself and its
    users.
</p>
<p>
    The base test case class for content providers,
    {@link android.test.ProviderTestCase2}, allows you to test your content provider in an
    isolated environment. Android mock objects such as {@link android.test.IsolatedContext} and
    {@link android.test.mock.MockContentResolver} also help provide an isolated test environment.
</p>
<p>
    As with other Android tests, provider test packages are run under the control of the test
    runner {@link android.test.InstrumentationTestRunner}. The section
    <a href="{@docRoot}tools/testing/testing_android.html#InstrumentationTestRunner">
    Running Tests With InstrumentationTestRunner</a> describes the test runner in
    more detail. The topic <a href="{@docRoot}tools/testing/testing_eclipse.html">
    Testing From Eclipse with ADT</a> shows you how to run a test package in Eclipse, and the
    topic <a href="{@docRoot}tools/testing/testing_otheride.html">
    Testing From Other IDEs</a>
    shows you how to run a test package from the command line.
</p>
<h2 id="ContentProviderTestAPI">Content Provider Testing API</h2>
<p>
    The main focus of the provider testing API is to provide an isolated testing environment. This
    ensures that tests always run against data dependencies set explicitly in the test case. It
    also prevents tests from modifying actual user data. For example, you want to avoid writing
    a test that fails because there was data left over from a previous test, and you want to
    avoid adding or deleting contact information in a actual provider.
</p>
<p>
    The test case class and mock object classes for provider testing set up this isolated testing
    environment for you.
</p>
<h3 id="ProviderTestCase2">ProviderTestCase2</h3>
<p>
    You test a provider with a subclass of {@link android.test.ProviderTestCase2}. This base class
    extends {@link android.test.AndroidTestCase}, so it provides the JUnit testing framework as well
    as Android-specific methods for testing application permissions. The most important
    feature of this class is its initialization, which creates the isolated test environment.
</p>
<p>
    The initialization is done in the constructor for {@link android.test.ProviderTestCase2}, which
    subclasses call in their own constructors. The {@link android.test.ProviderTestCase2}
    constructor creates an {@link android.test.IsolatedContext} object that allows file and
    database operations but stubs out other interactions with the Android system.
    The file and database operations themselves take place in a directory that is local to the
    device or emulator and has a special prefix.
</p>
<p>
    The constructor then creates a {@link android.test.mock.MockContentResolver} to use as the
    resolver for the test. The {@link android.test.mock.MockContentResolver} class is described in
    detail in the section
    <a href="{@docRoot}tools/testing/testing_android.html#MockObjectClasses">Mock object
classes</a>.
</p>
<p>
    Lastly, the constructor creates an instance of the provider under test. This is a normal
    {@link android.content.ContentProvider} object, but it takes all of its environment information
    from the {@link android.test.IsolatedContext}, so it is restricted to
    working in the isolated test environment. All of the tests done in the test case class run
    against this isolated object.
</p>
<h3 id="MockObjects">Mock object classes</h3>
<p>
    {@link android.test.ProviderTestCase2} uses {@link android.test.IsolatedContext} and
    {@link android.test.mock.MockContentResolver}, which are standard mock object classes. To
    learn more about them, please read
    <a href="{@docRoot}tools/testing/testing_android.html#MockObjectClasses">
    Testing Fundamentals</a>.
</p>
<h2 id="WhatToTest">What To Test</h2>
<p>
    The topic <a href="{@docRoot}tools/testing/what_to_test.html">What To Test</a>
    lists general considerations for testing Android components.
    Here are some specific guidelines for testing content providers.
</p>
<ul>
    <li>
        Test with resolver methods: Even though you can instantiate a provider object in
        {@link android.test.ProviderTestCase2}, you should always test with a resolver object
        using the appropriate URI. This ensures that you are testing the provider using the same
        interaction that a regular application would use.
    </li>
    <li>
        Test a public provider as a contract: If you intent your provider to be public and
        available to other applications, you should test it as a contract. This includes
        the following ideas:
        <ul>
            <li>
                Test with constants that your provider publicly exposes. For
                example, look for constants that refer to column names in one of the provider's
                data tables. These should always be constants publicly defined by the provider.
            </li>
            <li>
                Test all the URIs offered by your provider. Your provider may offer several URIs,
                each one referring to a different aspect of the data. The
                <a href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample,
                for example, features a provider that offers one URI for retrieving a list of notes,
                another for retrieving an individual note by it's database ID, and a third for
                displaying notes in a live folder.
            </li>
            <li>
                Test invalid URIs: Your unit tests should deliberately call the provider with an
                invalid URI, and look for errors. Good provider design is to throw an
                IllegalArgumentException for invalid URIs.

            </li>
        </ul>
    </li>
    <li>
        Test the standard provider interactions: Most providers offer six access methods:
        query, insert, delete, update, getType, and onCreate(). Your tests should verify that all
        of these methods work. These are described in more detail in the topic
        <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.
    </li>
    <li>
        Test business logic: Don't forget to test the business logic that your provider should
        enforce. Business logic includes handling of invalid values, financial or arithmetic
        calculations, elimination or combining of duplicates, and so forth. A content provider
        does not have to have business logic, because it may be implemented by activities that
        modify the data. If the provider does implement business logic, you should test it.
    </li>
</ul>
<h2 id="NextSteps">Next Steps</h2>
<p>
    To learn how to set up and run tests in Eclipse, please refer to 
<a href="{@docRoot}tools/testing/testing_eclipse.html">Testing from Eclipse with ADT</a>.
    If you're not working in Eclipse, refer to 
<a href="{@docRoot}tools/testing/testing_otheride.html">Testing From Other IDEs</a>.
</p>
<p>
    If you want a step-by-step introduction to testing activities, try the 
    <a href="{@docRoot}tools/testing/activity_test.html">Activity Testing Tutorial</a>, which
    guides you through a testing scenario that you develop against an activity-oriented application.
</p>