Summary: Ctors | Methods | Protected Methods | Inherited Methods | [Expand All]

ServiceTestRule

This package is part of the Android support library which is no longer maintained. The support library has been superseded by AndroidX which is part of Jetpack. We recommend using the AndroidX libraries in all new projects. You should also consider migrating existing projects to AndroidX. To find the AndroidX class that maps to this deprecated class, see the AndroidX support library class mappings.

public class ServiceTestRule
extends Object implements TestRule

java.lang.Object
↳	android.support.test.rule.ServiceTestRule

---

A JUnit rule that provides a simplified mechanism to start and shutdown your service before and after the duration of your test. It also guarantees that the service is successfully connected when starting (or binding to) a service. The service can be started (or bound) using one of the helper methods. It will automatically be stopped (or unbound) after the test completes and any methods annotated with After are finished.

Note: This rule doesn't support IntentService because it's automatically destroyed when onHandleIntent(android.content.Intent) finishes all outstanding commands. So there is no guarantee to establish a successful connection in a timely manner.

Usage:

 @Rule
 public final ServiceTestRule mServiceRule = new ServiceTestRule();

 @Test
 public void testWithStartedService() {
     mServiceRule.startService(
         new Intent(InstrumentationRegistry.getTargetContext(), MyService.class));
     //do something
 }

 @Test
 public void testWithBoundService() {
     IBinder binder = mServiceRule.bindService(
         new Intent(InstrumentationRegistry.getTargetContext(), MyService.class));
     MyService service = ((MyService.LocalBinder) binder).getService();
     assertTrue("True wasn't returned", service.doSomethingToReturnTrue());
 }
 

This API is currently in beta.

Summary

Public constructors
ServiceTestRule() Creates a ServiceTestRule with a default timeout of 5 seconds

Public methods
Statement	apply(Statement base, Description description)
IBinder	bindService(Intent intent) Works just like bindService(android.content.Intent, android.content.ServiceConnection, int) except uses an internal ServiceConnection to guarantee successful bound.
IBinder	bindService(Intent intent, ServiceConnection connection, int flags) Binds 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	startService(Intent intent) Starts the service under test and blocks until the service is connected, in the same way as if it were started by Context.startService(Intent) with an Intent that identifies a service.
void	unbindService() Unbinds the service under test that was previously bound by a call to bindService(android.content.Intent) or bindService(android.content.Intent, android.content.ServiceConnection, int).
static ServiceTestRule	withTimeout(long timeout, TimeUnit timeUnit) Factory method to create a ServiceTestRule with a custom timeout

Protected methods
void	afterService() Override this method to do your own service specific clean up after the service is shutdown.
void	beforeService() Override this method to do your own service specific initialization before starting or binding to the service.

Inherited methods
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait(long arg0, int arg1) final void wait(long arg0) final void wait()
From interface org.junit.rules.TestRule abstract Statement apply(Statement arg0, Description arg1)

Public constructors

ServiceTestRule

ServiceTestRule ()

Creates a ServiceTestRule with a default timeout of 5 seconds

Public methods

apply

Statement apply (Statement base, 
                Description description)

Parameters
base	Statement
description	Description

Returns
Statement

bindService

IBinder bindService (Intent intent)

Works just like bindService(android.content.Intent, android.content.ServiceConnection, int) except uses an internal ServiceConnection to guarantee successful bound. The operation option flag defaults to BIND_AUTO_CREATE

Parameters
intent	Intent

Returns
IBinder

Throws
TimeoutException

See also:

• bindService(android.content.Intent, android.content.ServiceConnection, int)

bindService

IBinder bindService (Intent intent, 
                ServiceConnection connection, 
                int flags)

Binds 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. However, it waits for onServiceConnected(android.content.ComponentName, android.os.IBinder) to be called before returning.

Parameters
intent	Intent: Identifies the service to connect to. The Intent may specify either an explicit component name, or a logical description (action, category, etc) to match an IntentFilter published by a service.
connection	ServiceConnection: Receives information as the service is started and stopped. This must be a valid ServiceConnection object; it must not be null.
flags	int: Operation options for the binding. May be 0, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, BIND_NOT_FOREGROUND, BIND_ABOVE_CLIENT, BIND_ALLOW_OOM_MANAGEMENT, or BIND_WAIVE_PRIORITY.

Returns
IBinder	An object whose type is a subclass of IBinder, for making further calls into the service.

Throws
SecurityException	if the called doesn't have permission to bind to the given service.
TimeoutException	if timed out waiting for a successful connection with the service.

See also:

• BIND_AUTO_CREATE
• BIND_DEBUG_UNBIND
• BIND_NOT_FOREGROUND

startService

void startService (Intent intent)

Starts the service under test and blocks until the service is connected, 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 at the end of the test run. However, it also attempts to bind to the service and waits for onServiceConnected(android.content.ComponentName, android.os.IBinder) to be called to ensure successful connection.

Note: This method only supports services that allow clients to bind to them. In other words, if your service onBind(Intent) method returns null then a TimeoutException will be thrown.

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

Throws
SecurityException	if you do not have permission to bind to the given service.
TimeoutException	if timed out waiting for a successful connection with the service.

unbindService

void unbindService ()

Unbinds the service under test that was previously bound by a call to bindService(android.content.Intent) or bindService(android.content.Intent, android.content.ServiceConnection, int). You normally do not need to call this method since your service will automatically be stopped and unbound at the end of each test method.

withTimeout

ServiceTestRule withTimeout (long timeout, 
                TimeUnit timeUnit)

Factory method to create a ServiceTestRule with a custom timeout

Parameters
timeout	long: the amount of time to wait for a service to connect.
timeUnit	TimeUnit: the time unit representing how the timeout parameter should be interpreted

Returns
ServiceTestRule	a ServiceTestRule with the desired timeout

Protected methods

afterService

void afterService ()

Override this method to do your own service specific clean up after the service is shutdown. The method is called after each test method is executed including any method annotated with After and after necessary calls to stop (or unbind) the service under test were called.

beforeService

void beforeService ()

Override this method to do your own service specific initialization before starting or binding to the service. The method is called before each test method is executed including any method annotated with Before. Do not start or bind to a service from here!

• Classes

  • ActivityTestRule
  • DisableOnAndroidDebug
  • GrantPermissionRule
  • ServiceTestRule
  • UiThreadTestRule