ProviderTestRule

public class ProviderTestRule
extends Object implements TestRule

java.lang.Object
   ↳ androidx.test.rule.provider.ProviderTestRule


A TestRule to test ContentProviders, with additional APIs to enable easy initialization such as restoring database from a file, running database commands passed in as a String or a file. By default, all permissions are granted when they are checked in ContentProviders under test, method revokePermission(String) can be used to revoke specific permissions to test the cases when they are denied in ContentProviders.

Note: The database related methods ProviderTestRule.Builder.setDatabaseFile(String, File), ProviderTestRule.Builder.setDatabaseCommands(String, String...), ProviderTestRule.Builder.setDatabaseCommandsFile(String, File) and runDatabaseCommands(String, String...) should only be used when ContentProvider under test is implemented based on SQLiteDatabase.

If more than one database related methods are used for a ContentProvider under test, the execution order of restoring database from file and running database commands are independent of the order those methods are called. If all methods are used, when setting up the ContentProvider for test, the execution order is as follows:

  1. Restore database from file passed in via ProviderTestRule.Builder.setDatabaseFile(String, File)
  2. Run database commands passed in via ProviderTestRule.Builder.setDatabaseCommands(String, String...)
  3. Run database commands from file passed in via ProviderTestRule.Builder.setDatabaseCommandsFile(String, File)

If the ContentProvider under test is not implemented based on SQLiteDatabase, or is implemented based on SQLiteDatabase but no extra database initialization workloads are needed, the rule can be created by simply using Builder(Class,String).

Usage example:

 @Rule
 public ProviderTestRule mProviderRule =
     new ProviderTestRule.Builder(MyContentProvider.class, MyContentProvider.AUTHORITY).build();

 @Test
 public void verifyContentProviderContractWorks() {
     ContentResolver resolver = mProviderRule.getResolver();
     // perform some database (or other) operations
     Uri uri = resolver.insert(testUrl, testContentValues);
     // perform some assertions on the resulting URI
     assertNotNull(uri);
 }
 

Alternatively, if the ContentProvider under test is based on SQLiteDatabase, then all database related methods can be used. However, the database name argument passed in via these methods must match the actual database name used by the ContentProvider under test.

Usage example:

 @Rule
 public ProviderTestRule mProviderRule =
     new ProviderTestRule.Builder(MyContentProvider.class, MyContentProvider.AUTHORITY)
         .setDatabaseCommands(DATABASE_NAME, INSERT_ONE_ENTRY_CMD, INSERT_ANOTHER_ENTRY_CMD)
         .build();

 @Test
 public void verifyTwoEntriesInserted() {
     ContentResolver resolver = mProviderRule.getResolver();
     // two entries are already inserted by rule, we can directly perform assertions to verify
     Cursor c = null;
     try {
       c = resolver.query(URI_TO_QUERY_ALL, null, null, null, null);
       assertNotNull(c);
       assertEquals(2, c.getCount());
     } finally {
       if (c != null && !c.isClosed()) {
         c.close();
       }
     }
 }
 

This API is currently in beta.

Summary

Nested classes

class ProviderTestRule.Builder

A Builder to ease ProviderTestRule creation. 

Public methods

Statement apply(Statement base, Description description)
ContentResolver getResolver()

Get the isolated ContentResolver that should be used for testing of the ContentProviders.

void revokePermission(String permission)

Revoke permission anytime during the tests.

void runDatabaseCommands(String dbName, String... dbCmds)

Run database commands anytime during the tests, after the rule is created.

Protected methods

void afterProviderCleanedUp()

Override this method to execute any code that should run after provider is cleaned up.

void beforeProviderSetup()

Override this method to execute any code that should run before provider is set up.

Inherited methods

Public methods

apply

public Statement apply (Statement base, 
                Description description)

Parameters
base Statement

description Description

Returns
Statement

getResolver

public ContentResolver getResolver ()

Get the isolated ContentResolver that should be used for testing of the ContentProviders.

Returns
ContentResolver the isolated ContentResolver created by this ProviderTestRule.

revokePermission

public void revokePermission (String permission)

Revoke permission anytime during the tests. The default return value of the following methods is PackageManager.PERMISSION_GRANTED. After a specific permission is revoked, the value returned becomes PackageManager.PERMISSION_DENIED when calling the methods with the revoked permission. After a test, the return values are restored to PackageManager.PERMISSION_GRANTED.

Consequentially, calling the following methods with the revoked permission will throw a SecurityException.

Parameters
permission String

runDatabaseCommands

public void runDatabaseCommands (String dbName, 
                String... dbCmds)

Run database commands anytime during the tests, after the rule is created.

Parameters
dbName String: The name of the underlying database used by the ContentProvider under test.

dbCmds String: The SQL commands to run during tests. Each command will be passed to SQLiteDatabase.execSQL(String) to execute.

Protected methods

afterProviderCleanedUp

protected void afterProviderCleanedUp ()

Override this method to execute any code that should run after provider is cleaned up. This method is called after each test method, including any method annotated with After.

beforeProviderSetup

protected void beforeProviderSetup ()

Override this method to execute any code that should run before provider is set up. This method is called before each test method, including any method annotated with Before.