{% setvar book_path %}/reference/kotlin/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

ServiceTestRule

class 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 android.app.IntentService because it's automatically destroyed when onHandleIntent 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

Creates a ServiceTestRule with a default timeout of 5 seconds

Public functions
Statement
apply(base: Statement, description: Description)
IBinder
bindService(intent: Intent)

Works just like bindService except uses an internal android.content.ServiceConnection to guarantee successful bound.
IBinder
bindService(intent: Intent, connection: ServiceConnection, flags: Int)

Binds the service under test, in the same way as if it were started by Context.bindService(Intent, ServiceConnection, flags) with an android.content.Intent that identifies a service.
Unit
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 android.content.Intent that identifies a service.
Unit

Unbinds the service under test that was previously bound by a call to or bindService.
ServiceTestRule
withTimeout(timeout: Long, timeUnit: TimeUnit)

Factory method to create a ServiceTestRule with a custom timeout

Public constructors

ServiceTestRule

ServiceTestRule()

Creates a ServiceTestRule with a default timeout of 5 seconds

Public functions

apply

fun apply(base: Statement, description: Description): Statement

bindService

fun bindService(intent: Intent): IBinder

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

See also
bindService

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

bindService

fun bindService(intent: Intent, connection: ServiceConnection, flags: Int): IBinder

Binds the service under test, in the same way as if it were started by Context.bindService(Intent, ServiceConnection, flags) with an android.content.Intent that identifies a service. However, it waits for onServiceConnected 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 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, , , , , , or .
Returns
IBinder

An object whose type is a subclass of IBinder, for making further calls into the service.
Throws
java.lang.SecurityException

if the called doesn't have permission to bind to the given service.
java.util.concurrent.TimeoutException

if timed out waiting for a successful connection with the service.
See also
Context

android.content.Context#BIND_AUTO_CREATE
Context

android.content.Context#BIND_DEBUG_UNBIND
Context

android.content.Context#BIND_NOT_FOREGROUND

startService

fun startService(intent: Intent): Unit

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 android.content.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 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 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
java.lang.SecurityException

if you do not have permission to bind to the given service.
java.util.concurrent.TimeoutException

if timed out waiting for a successful connection with the service.

unbindService

fun unbindService(): Unit

Unbinds the service under test that was previously bound by a call to or bindService. 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

fun withTimeout(timeout: Long, timeUnit: TimeUnit): ServiceTestRule

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