import java.io.File;
/**
- * This TestCase class provides a framework for isolated testing of a single
- * ContentProvider. It uses a {@link android.test.mock.MockContentResolver} to
- * access the provider, restricts the provider to an isolated area of the
- * filesystem (for safely creating & modifying databases & files), and injects
- * {@link android.test.IsolatedContext} to isolate the ContentProvider from the
- * rest of the running system.
- *
- * <p>This environment is created automatically by {@link #setUp} and {@link
- * #tearDown}.
+ * This test case class provides a framework for testing a single
+ * {@link ContentProvider} and for testing your app code with an
+ * isolated content provider. Instead of using the system map of
+ * providers that is based on the manifests of other applications, the test
+ * case creates its own internal map. It then uses this map to resolve providers
+ * given an authority. This allows you to inject test providers and to null out
+ * providers that you do not want to use.
+ * <p>
+ * This test case also sets up the following mock objects:
+ * </p>
+ * <ul>
+ * <li>
+ * An {@link android.test.IsolatedContext} that stubs out Context methods that might
+ * affect the rest of the running system, while allowing tests to do real file and
+ * database work.
+ * </li>
+ * <li>
+ * A {@link android.test.mock.MockContentResolver} that provides the functionality of a
+ * regular content resolver, but uses {@link IsolatedContext}. It stubs out
+ * {@link ContentResolver#notifyChange(Uri, ContentObserver, boolean)} to
+ * prevent the test from affecting the running system.
+ * </li>
+ * <li>
+ * An instance of the provider under test, running in an {@link IsolatedContext}.
+ * </li>
+ * </ul>
+ * <p>
+ * This framework is set up automatically by the base class' {@link #setUp()} method. If you
+ * override this method, you must call the super method as the first statement in
+ * your override.
+ * </p>
+ * <p>
+ * In order for their tests to be run, concrete subclasses must provide their own
+ * constructor with no arguments. This constructor must call
+ * {@link #ProviderTestCase2(Class, String)} as its first operation.
+ * </p>
+ * For more information on content provider testing, please see
+ * <a href="{@docRoot}guide/topics/testing/provider_testing.html">Content Provider Testing</a>.
*/
public abstract class ProviderTestCase2<T extends ContentProvider> extends AndroidTestCase {
@Override
public File getDir(String name, int mode) {
- // name the directory so the directory will be seperated from
+ // name the directory so the directory will be separated from
// one created through the regular Context
return getContext().getDir("mockcontext2_" + name, mode);
}
}
-
+ /**
+ * Constructor.
+ *
+ * @param providerClass The class name of the provider under test
+ * @param providerAuthority The provider's authority string
+ */
public ProviderTestCase2(Class<T> providerClass, String providerAuthority) {
mProviderClass = providerClass;
mProviderAuthority = providerAuthority;
}
- /**
- * The content provider that will be set up for use in each test method.
- */
private T mProvider;
+ /**
+ * Returns the content provider created by this class in the {@link #setUp()} method.
+ * @return T An instance of the provider class given as a parameter to the test case class.
+ */
public T getProvider() {
return mProvider;
}
+ /**
+ * Sets up the environment for the test fixture.
+ * <p>
+ * Creates a new
+ * {@link android.test.mock.MockContentResolver}, a new IsolatedContext
+ * that isolates the provider's file operations, and a new instance of
+ * the provider under test within the isolated environment.
+ * </p>
+ *
+ * @throws Exception
+ */
@Override
protected void setUp() throws Exception {
super.setUp();
mResolver = new MockContentResolver();
final String filenamePrefix = "test.";
- RenamingDelegatingContext targetContextWrapper = new RenamingDelegatingContext(
- new MockContext2(), // The context that most methods are delegated to
+ RenamingDelegatingContext targetContextWrapper = new
+ RenamingDelegatingContext(
+ new MockContext2(), // The context that most methods are
+ //delegated to
getContext(), // The context that file methods are delegated to
filenamePrefix);
mProviderContext = new IsolatedContext(mResolver, targetContextWrapper);
mResolver.addProvider(mProviderAuthority, getProvider());
}
+ /**
+ * Gets the {@link MockContentResolver} created by this class during initialization. You
+ * must use the methods of this resolver to access the provider under test.
+ *
+ * @return A {@link MockContentResolver} instance.
+ */
public MockContentResolver getMockContentResolver() {
return mResolver;
}
+ /**
+ * Gets the {@link IsolatedContext} created by this class during initialization.
+ * @return The {@link IsolatedContext} instance
+ */
public IsolatedContext getMockContext() {
return mProviderContext;
}
+ /**
+ * <p>
+ * Creates a new content provider of the same type as that passed to the test case class,
+ * with an authority name set to the authority parameter, and using an SQLite database as
+ * the underlying data source. The SQL statement parameter is used to create the database.
+ * This method also creates a new {@link MockContentResolver} and adds the provider to it.
+ * </p>
+ * <p>
+ * Both the new provider and the new resolver are put into an {@link IsolatedContext}
+ * that uses the targetContext parameter for file operations and a {@link MockContext}
+ * for everything else. The IsolatedContext prepends the filenamePrefix parameter to
+ * file, database, and directory names.
+ * </p>
+ * <p>
+ * This is a convenience method for creating a "mock" provider that can contain test data.
+ * </p>
+ *
+ * @param targetContext The context to use as the basis of the IsolatedContext
+ * @param filenamePrefix A string that is prepended to file, database, and directory names
+ * @param providerClass The type of the provider being tested
+ * @param authority The authority string to associated with the test provider
+ * @param databaseName The name assigned to the database
+ * @param databaseVersion The version assigned to the database
+ * @param sql A string containing the SQL statements that are needed to create the desired
+ * database and its tables. The format is the same as that generated by the
+ * <a href="http://www.sqlite.org/sqlite.html">sqlite3</a> tool's <code>.dump</code> command.
+ * @return ContentResolver A new {@link MockContentResolver} linked to the provider
+ *
+ * @throws IllegalAccessException
+ * @throws InstantiationException
+ */
public static <T extends ContentProvider> ContentResolver newResolverWithContentProviderFromSql(
Context targetContext, String filenamePrefix, Class<T> providerClass, String authority,
String databaseName, int databaseVersion, String sql)
/**
* This test case provides a framework in which you can test Service classes in
* a controlled environment. It provides basic support for the lifecycle of a
- * Service, and hooks by which you can inject various dependencies and control
+ * Service, and hooks with which you can inject various dependencies and control
* the environment in which your Service is tested.
*
* <p><b>Lifecycle Support.</b>
- * Every Service is designed to be accessed within a specific sequence of
- * calls. <insert link to Service lifecycle doc here>.
- * In order to support the lifecycle of a Service, this test case will make the
- * following calls at the following times.
+ * A Service is accessed with a specific sequence of
+ * calls, as documented in the section
+ * <a href="http://developer.android.com/guide/topics/fundamentals.html#servlife">
+ * Service lifecycle</a> in the Developer Guide. In order to support the lifecycle of a Service,
+ * <code>ServiceTestCase</code> enforces this protocol:
*
- * <ul><li>The test case will not call onCreate() until your test calls
- * {@link #startService} or {@link #bindService}. This gives you a chance
- * to set up or adjust any additional framework or test logic before
- * onCreate().</li>
- * <li>When your test calls {@link #startService} or {@link #bindService}
- * the test case will call onCreate(), and then call the corresponding entry point in your service.
- * It will record any parameters or other support values necessary to support the lifecycle.</li>
- * <li>After your test completes, the test case {@link #tearDown} function is
- * automatically called, and it will stop and destroy your service with the appropriate
- * calls (depending on how your test invoked the service.)</li>
+ * <ul>
+ * <li>
+ * The {@link #setUp()} method is called before each test method. The base implementation
+ * gets the system context. If you override <code>setUp()</code>, you must call
+ * <code>super.setUp()</code> as the first statement in your override.
+ * </li>
+ * <li>
+ * The test case waits to call {@link android.app.Service#onCreate()} until one of your
+ * test methods calls {@link #startService} or {@link #bindService}. This gives you an
+ * opportunity to set up or adjust any additional framework or test logic before you test
+ * the running service.
+ * </li>
+ * <li>
+ * When one of your test methods calls {@link #startService ServiceTestCase.startService()}
+ * or {@link #bindService ServiceTestCase.bindService()}, the test case calls
+ * {@link android.app.Service#onCreate() Service.onCreate()} and then calls either
+ * {@link android.app.Service#startService(Intent) Service.startService(Intent)} or
+ * {@link android.app.Service#bindService(Intent, ServiceConnection, int)
+ * Service.bindService(Intent, ServiceConnection, int)}, as appropriate. It also stores
+ * values needed to track and support the lifecycle.
+ * </li>
+ * <li>
+ * After each test method finishes, the test case calls the {@link #tearDown} method. This
+ * method stops and destroys the service with the appropriate calls, depending on how the
+ * service was started. If you override <code>tearDown()</code>, your must call the
+ * <code>super.tearDown()</code> as the last statement in your override.
+ * </li>
* </ul>
- *
- * <p><b>Dependency Injection.</b>
- * Every service has two inherent dependencies, the {@link android.content.Context Context} in
- * which it runs, and the {@link android.app.Application Application} with which it is associated.
- * This framework allows you to inject modified, mock, or isolated replacements for these
- * dependencies, and thus perform a true unit test.
- *
- * <p>If simply run your tests as-is, your Service will be injected with a fully-functional
- * Context, and a generic {@link android.test.mock.MockApplication MockApplication} object.
- * You can create and inject alternatives to either of these by calling
- * {@link AndroidTestCase#setContext(Context) setContext()} or
- * {@link #setApplication setApplication()}. You must do this <i>before</i> calling
- * startService() or bindService(). The test framework provides a
- * number of alternatives for Context, including {link android.test.mock.MockContext MockContext},
- * {@link android.test.RenamingDelegatingContext RenamingDelegatingContext}, and
- * {@link android.content.ContextWrapper ContextWrapper}.
+ *
+ * <p>
+ * <strong>Dependency Injection.</strong>
+ * A service has two inherent dependencies, its {@link android.content.Context Context} and its
+ * associated {@link android.app.Application Application}. The ServiceTestCase framework
+ * allows you to inject modified, mock, or isolated replacements for these dependencies, and
+ * thus perform unit tests with controlled dependencies in an isolated environment.
+ * </p>
+ * <p>
+ * By default, the test case is injected with a full system context and a generic
+ * {@link android.test.mock.MockApplication MockApplication} object. You can inject
+ * alternatives to either of these by invoking
+ * {@link AndroidTestCase#setContext(Context) setContext()} or
+ * {@link #setApplication setApplication()}. You must do this <em>before</em> calling
+ * startService() or bindService(). The test framework provides a
+ * number of alternatives for Context, including
+ * {link android.test.mock.MockContext MockContext},
+ * {@link android.test.RenamingDelegatingContext RenamingDelegatingContext},
+ * {@link android.content.ContextWrapper ContextWrapper}, and
+ * {@link android.test.IsolatedContext}.
*/
public abstract class ServiceTestCase<T extends Service> extends AndroidTestCase {
private Context mSystemContext;
private Application mApplication;
+ /**
+ * Constructor
+ * @param serviceClass The type of the service under test.
+ */
public ServiceTestCase(Class<T> serviceClass) {
mServiceClass = serviceClass;
}
private int mServiceId;
/**
- * @return Returns the actual service under test.
+ * @return An instance of the service under test. This instance is created automatically when
+ * a test calls {@link #startService} or {@link #bindService}.
*/
public T getService() {
return mService;
}
/**
- * This will do the work to instantiate the Service under test. After this, your test
- * code must also start and stop the service.
+ * Gets the current system context and stores it.
+ *
+ * Extend this method to do your own test initialization. If you do so, you
+ * must call <code>super.setUp()</code> as the first statement in your override. The method is
+ * called before each test method is executed.
*/
@Override
protected void setUp() throws Exception {
super.setUp();
-
+
// get the real context, before the individual tests have a chance to muck with it
mSystemContext = getContext();
}
-
+
/**
- * Create the service under test and attach all injected dependencies (Context, Application) to
- * it. This will be called automatically by {@link #startService} or by {@link #bindService}.
- * If you wish to call {@link AndroidTestCase#setContext(Context) setContext()} or
- * {@link #setApplication setApplication()}, you must do so before calling this function.
+ * Creates the service under test and attaches all injected dependencies
+ * (Context, Application) to it. This is called automatically by {@link #startService} or
+ * by {@link #bindService}.
+ * If you need to call {@link AndroidTestCase#setContext(Context) setContext()} or
+ * {@link #setApplication setApplication()}, do so before calling this method.
*/
protected void setupService() {
mService = null;
getApplication(),
null // mocked services don't talk with the activity manager
);
-
+
assertNotNull(mService);
-
+
mServiceId = new Random().nextInt();
mServiceAttached = true;
}
-
+
/**
- * Start the service under test, in the same way as if it was started by
- * {@link android.content.Context#startService Context.startService()}, providing the
- * arguments it supplied. If you use this method to start the service, it will automatically
- * be stopped by {@link #tearDown}.
- *
- * @param intent The Intent as if supplied to {@link android.content.Context#startService}.
+ * Starts the service under test, in the same way as if it were started by
+ * {@link android.content.Context#startService(Intent) Context.startService(Intent)} with
+ * an {@link android.content.Intent} that identifies a service.
+ * If you use this method to start the service, it is automatically stopped by
+ * {@link #tearDown}.
+ *
+ * @param intent An Intent that identifies a service, of the same form as the Intent passed to
+ * {@link android.content.Context#startService(Intent) Context.startService(Intent)}.
*/
protected void startService(Intent intent) {
if (!mServiceAttached) {
setupService();
}
assertNotNull(mService);
-
+
if (!mServiceCreated) {
mService.onCreate();
mServiceCreated = true;
}
mService.onStartCommand(intent, 0, mServiceId);
-
+
mServiceStarted = true;
}
-
- /**
- * Start the service under test, in the same way as if it was started by
- * {@link android.content.Context#bindService Context.bindService()}, providing the
- * arguments it supplied.
- *
- * Return the communication channel to the service. May return null if
- * clients can not bind to the service. The returned
- * {@link android.os.IBinder} is usually for a complex interface
- * that has been <a href="{@docRoot}guide/developing/tools/aidl.html">described using
- * aidl</a>.
- *
- * Note: In order to test with this interface, your service must implement a getService()
- * method, as shown in samples.ApiDemos.app.LocalService.
- * @param intent The Intent as if supplied to {@link android.content.Context#bindService}.
- *
- * @return Return an IBinder for making further calls into the Service.
+ /**
+ * <p>
+ * Starts the service under test, in the same way as if it were started by
+ * {@link android.content.Context#bindService(Intent, ServiceConnection, int)
+ * Context.bindService(Intent, ServiceConnection, flags)} with an
+ * {@link android.content.Intent} that identifies a service.
+ * </p>
+ * <p>
+ * Notice that the parameters are different. You do not provide a
+ * {@link android.content.ServiceConnection} object or the flags parameter. Instead,
+ * you only provide the Intent. The method returns an object whose type is a
+ * subclass of {@link android.os.IBinder}, or null if the method fails. An IBinder
+ * object refers to a communication channel between the application and
+ * the service. The flag is assumed to be {@link android.content.Context#BIND_AUTO_CREATE}.
+ * </p>
+ * <p>
+ * See <a href="{@docRoot}guide/developing/tools/aidl.html">Designing a Remote Interface
+ * Using AIDL</a> for more information about the communication channel object returned
+ * by this method.
+ * </p>
+ * Note: To be able to use bindService in a test, the service must implement getService()
+ * method. An example of this is in the ApiDemos sample application, in the
+ * LocalService demo.
+ *
+ * @param intent An Intent object of the form expected by
+ * {@link android.content.Context#bindService}.
+ *
+ * @return An object whose type is a subclass of IBinder, for making further calls into
+ * the service.
*/
protected IBinder bindService(Intent intent) {
if (!mServiceAttached) {
setupService();
}
assertNotNull(mService);
-
+
if (!mServiceCreated) {
mService.onCreate();
mServiceCreated = true;
// no extras are expected by unbind
mServiceIntent = intent.cloneFilter();
IBinder result = mService.onBind(intent);
-
+
mServiceBound = true;
return result;
}
-
+
/**
- * This will make the necessary calls to stop (or unbind) the Service under test, and
- * call onDestroy(). Ordinarily this will be called automatically (by {@link #tearDown}, but
- * you can call it directly from your test in order to check for proper shutdown behaviors.
+ * Makes the necessary calls to stop (or unbind) the service under test, and
+ * calls onDestroy(). Ordinarily this is called automatically (by {@link #tearDown}, but
+ * you can call it directly from your test in order to check for proper shutdown behavior.
*/
protected void shutdownService() {
if (mServiceStarted) {
mService.onDestroy();
}
}
-
+
/**
- * Shuts down the Service under test. Also makes sure all resources are cleaned up and
- * garbage collected before moving on to the next
- * test. Subclasses that override this method should make sure they call super.tearDown()
- * at the end of the overriding method.
- *
+ * <p>
+ * Shuts down the service under test. Ensures all resources are cleaned up and
+ * garbage collected before moving on to the next test. This method is called after each
+ * test method.
+ * </p>
+ * <p>
+ * Subclasses that override this method must call <code>super.tearDown()</code> as their
+ * last statement.
+ * </p>
+ *
* @throws Exception
*/
@Override
shutdownService();
mService = null;
- // Scrub out members - protects against memory leaks in the case where someone
+ // Scrub out members - protects against memory leaks in the case where someone
// creates a non-static inner class (thus referencing the test case) and gives it to
// someone else to hold onto
scrubClass(ServiceTestCase.class);
super.tearDown();
}
-
+
/**
- * Set the application for use during the test. If your test does not call this function,
- * a new {@link android.test.mock.MockApplication MockApplication} object will be generated.
- *
- * @param application The Application object that will be injected into the Service under test.
+ * Sets the application that is used during the test. If you do not call this method,
+ * a new {@link android.test.mock.MockApplication MockApplication} object is used.
+ *
+ * @param application The Application object that is used by the service under test.
+ *
+ * @see #getApplication()
*/
public void setApplication(Application application) {
mApplication = application;
}
/**
- * Return the Application object being used by the Service under test.
- *
- * @return Returns the application object.
- *
+ * Returns the Application object in use by the service under test.
+ *
+ * @return The application object.
+ *
* @see #setApplication
*/
public Application getApplication() {
return mApplication;
}
-
+
/**
- * Return a real (not mocked or instrumented) system Context that can be used when generating
- * Mock or other Context objects for your Service under test.
- *
- * @return Returns a reference to a normal Context.
+ * Returns the real system context that is saved by {@link #setUp()}. Use it to create
+ * mock or other types of context objects for the service under test.
+ *
+ * @return A normal system context.
*/
public Context getSystemContext() {
return mSystemContext;
}
+ /**
+ * Tests that {@link #setupService()} runs correctly and issues an
+ * {@link junit.framework.Assert#assertNotNull(String, Object)} if it does.
+ * You can override this test method if you wish.
+ *
+ * @throws Exception
+ */
public void testServiceTestCaseSetUpProperly() throws Exception {
setupService();
assertNotNull("service should be launched successfully", mService);
OSDN Git Service
