to top
Android APIs
public abstract class

ServiceTestCase

extends AndroidTestCase
java.lang.Object
   ↳ junit.framework.Assert
     ↳ junit.framework.TestCase
       ↳ android.test.AndroidTestCase
         ↳ android.test.ServiceTestCase<T extends android.app.Service>

Class Overview

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 with which you can inject various dependencies and control the environment in which your Service is tested.

Developer Guides

For more information about application testing, read the Testing developer guide.

Lifecycle Support. A Service is accessed with a specific sequence of calls, as described in the Services document. In order to support the lifecycle of a Service, ServiceTestCase enforces this protocol:

Dependency Injection. A service has two inherent dependencies, its Context and its associated 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.

By default, the test case is injected with a full system context and a generic MockApplication object. You can inject alternatives to either of these by invoking setContext() or setApplication(). You must do this before calling startService() or bindService(). The test framework provides a number of alternatives for Context, including MockContext, RenamingDelegatingContext, ContextWrapper, and IsolatedContext.

Summary

[Expand]
Inherited Fields
From class android.test.AndroidTestCase
Public Constructors
ServiceTestCase(Class<T> serviceClass)
Constructor
Public Methods
Application getApplication()
Returns the Application object in use by the service under test.
T getService()
Context getSystemContext()
Returns the real system context that is saved by setUp().
void setApplication(Application application)
Sets the application that is used during the test.
void testServiceTestCaseSetUpProperly()
Tests that setupService() runs correctly and issues an assertNotNull(String, Object) if it does.
Protected Methods
IBinder bindService(Intent intent)

Starts the service under test, in the same way as if it were started by Context.bindService(Intent, ServiceConnection, flags) with an Intent that identifies a service.

void setUp()
Gets the current system context and stores it.
void setupService()
Creates the service under test and attaches all injected dependencies (Context, Application) to it.
void shutdownService()
Makes the necessary calls to stop (or unbind) the service under test, and calls onDestroy().
void startService(Intent intent)
Starts the service under test, in the same way as if it were started by Context.startService(Intent) with an Intent that identifies a service.
void tearDown()

Shuts down the service under test.

[Expand]
Inherited Methods
From class android.test.AndroidTestCase
From class junit.framework.TestCase
From class junit.framework.Assert
From class java.lang.Object
From interface junit.framework.Test

Public Constructors

public ServiceTestCase (Class<T> serviceClass)

Added in API level 1

Constructor

Parameters
serviceClass The type of the service under test.

Public Methods

public Application getApplication ()

Added in API level 1

Returns the Application object in use by the service under test.

Returns
  • The application object.

public T getService ()

Added in API level 1

Returns

public Context getSystemContext ()

Added in API level 1

Returns the real system context that is saved by setUp(). Use it to create mock or other types of context objects for the service under test.

Returns
  • A normal system context.

public void setApplication (Application application)

Added in API level 1

Sets the application that is used during the test. If you do not call this method, a new MockApplication object is used.

Parameters
application The Application object that is used by the service under test.
See Also

public void testServiceTestCaseSetUpProperly ()

Added in API level 1

Tests that setupService() runs correctly and issues an assertNotNull(String, Object) if it does. You can override this test method if you wish.

Throws
Exception

Protected Methods

protected IBinder bindService (Intent intent)

Added in API level 1

Starts the service under test, in the same way as if it were started by Context.bindService(Intent, ServiceConnection, flags) with an Intent that identifies a service.

Notice that the parameters are different. You do not provide a ServiceConnection object or the flags parameter. Instead, you only provide the Intent. The method returns an object whose type is a subclass of 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 BIND_AUTO_CREATE.

See Designing a Remote Interface Using AIDL for more information about the communication channel object returned by this method.

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.

Parameters
intent An Intent object of the form expected by bindService(Intent, ServiceConnection, int).
Returns
  • An object whose type is a subclass of IBinder, for making further calls into the service.

protected void setUp ()

Added in API level 1

Gets the current system context and stores it. Extend this method to do your own test initialization. If you do so, you must call super.setUp() as the first statement in your override. The method is called before each test method is executed.

Throws
Exception

protected void setupService ()

Added in API level 1

Creates the service under test and attaches all injected dependencies (Context, Application) to it. This is called automatically by startService(Intent) or by bindService(Intent). If you need to call setContext() or setApplication(), do so before calling this method.

protected void shutdownService ()

Added in API level 1

Makes the necessary calls to stop (or unbind) the service under test, and calls onDestroy(). Ordinarily this is called automatically (by tearDown(), but you can call it directly from your test in order to check for proper shutdown behavior.

protected void startService (Intent intent)

Added in API level 1

Starts the service under test, in the same way as if it were started by Context.startService(Intent) with an Intent that identifies a service. If you use this method to start the service, it is automatically stopped by tearDown().

Parameters
intent An Intent that identifies a service, of the same form as the Intent passed to Context.startService(Intent).

protected void tearDown ()

Added in API level 1

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.

Subclasses that override this method must call super.tearDown() as their last statement.

Throws
Exception