ServiceTestRule
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 |
Public methods | |
---|---|
Statement
|
apply(Statement base, Description description)
|
IBinder
|
bindService(Intent intent)
Works just like |
IBinder
|
bindService(Intent intent, ServiceConnection connection, int flags)
Binds the service under test, in the same way as if it were started by |
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 |
void
|
unbindService()
Unbinds the service under test that was previously bound by a call to |
static
ServiceTestRule
|
withTimeout(long timeout, TimeUnit timeUnit)
Factory method to create a |
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
| |
From
interface
org.junit.rules.TestRule
|
Public constructors
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 |
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. |
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!