ActivityTestRule
public
class
ActivityTestRule
extends Object
implements
TestRule
java.lang.Object | |
↳ | androidx.test.rule.ActivityTestRule<T extends android.app.Activity> |
This class is deprecated.
use ActivityScenario
or ActivityScenarioRule
instead. They offer a simpler, and safer
way of controlling Activity lifecycles.
Here are some tips to consider when converting to ActivityScenario/Rule
:
- For simple cases where you want to launch the Activity before each test and tear it
down after each test (eg you are using
ActivityTestRule(Class)
), convert directly to ActivityScenarioRule. - If you need control over when to launch the Activity (eg you are using
ERROR(/#ActivityTestRule(Class, false, false))
, use ActivityScenario.launch. Its recommended to wrap the launch in a try-block, so the Activity is closed automatically.try (ActivityScenario.launch(activityClass)) { ... }
- If you need access to the Activity during the test (eg you are calling
getActivity()
provide a Runnable callback toERROR(/androidx.test.core.app.ActivityScenario#onActivity(Runnable))
instead. The callback provided to onActivity will run on the application's main thread, thus ensuring a safer mechanism to access the Activity.
This rule provides functional testing of a single Activity
. When launchActivity
is set to true in the constructor, the Activity under test will be launched before each test
annotated with Test
and before methods annotated with Before
, and it
will be terminated after the test is completed and methods annotated with After
are finished.
The Activity can be manually launched with launchActivity(Intent)
, and manually
finished with finishActivity()
. If the Activity is running at the end of the test, the
test rule will finish it.
During the duration of the test you will be able to manipulate your Activity directly using
the reference obtained from getActivity()
. If the Activity is finished and relaunched,
the reference returned by getActivity()
will always point to the current instance of the
Activity.
Summary
Public constructors | |
---|---|
ActivityTestRule(Class<T> activityClass)
Similar to |
|
ActivityTestRule(Class<T> activityClass, boolean initialTouchMode)
Similar to |
|
ActivityTestRule(Class<T> activityClass, boolean initialTouchMode, boolean launchActivity)
Similar to |
|
ActivityTestRule(SingleActivityFactory<T> activityFactory, boolean initialTouchMode, boolean launchActivity)
Creates an |
|
ActivityTestRule(Class<T> activityClass, String targetPackage, int launchFlags, boolean initialTouchMode, boolean launchActivity)
Creates an |
Public methods | |
---|---|
Statement
|
apply(Statement base, Description description)
|
void
|
finishActivity()
Finishes the currently launched Activity. |
T
|
getActivity()
Returns the reference to the activity under test. |
Instrumentation.ActivityResult
|
getActivityResult()
This method can be used to retrieve the |
T
|
launchActivity(Intent startIntent)
Launches the Activity under test. |
void
|
runOnUiThread(Runnable runnable)
Helper method for running part of a method on the UI thread, blocking until it is complete. |
Protected methods | |
---|---|
void
|
afterActivityFinished()
Override this method to execute any code that should run after the currently launched |
void
|
afterActivityLaunched()
Override this method to execute any code that should run after your |
void
|
beforeActivityLaunched()
Override this method to execute any code that should run before your |
Intent
|
getActivityIntent()
Override this method to set up a custom Intent as if supplied to |
Inherited methods | |
---|---|
Public constructors
ActivityTestRule
public ActivityTestRule (Class<T> activityClass)
Similar to ActivityTestRule(Class, boolean)
but with "touch mode" disabled.
Parameters | |
---|---|
activityClass |
Class : The activity under test. This must be a class in the instrumentation
targetPackage specified in the AndroidManifest.xml |
ActivityTestRule
public ActivityTestRule (Class<T> activityClass, boolean initialTouchMode)
Similar to ActivityTestRule(Class, boolean, boolean)
but defaults to launch the
activity under test once per
Test
method. It is launched before the first Before
method, and terminated after the last After
method.
Parameters | |
---|---|
activityClass |
Class : The activity under test. This must be a class in the instrumentation
targetPackage specified in the AndroidManifest.xml |
initialTouchMode |
boolean : true if the Activity should be placed into "touch mode" when started |
ActivityTestRule
public ActivityTestRule (Class<T> activityClass, boolean initialTouchMode, boolean launchActivity)
Similar to ActivityTestRule(Class, String, int, boolean, boolean)
but defaults to
launch the Activity with the default target package name ERROR(/InstrumentationRegistry#getTargetContext()#getPackageName)
and Intent.FLAG_ACTIVITY_NEW_TASK
launch flag.
Parameters | |
---|---|
activityClass |
Class : The activity under test. This must be a class in the instrumentation
targetPackage specified in the AndroidManifest.xml |
initialTouchMode |
boolean : true if the Activity should be placed into "touch mode" when started |
launchActivity |
boolean : true if the Activity should be launched once per Test method. It
will be launched before the first Before
method, and terminated after the last After
method.
|
ActivityTestRule
public ActivityTestRule (SingleActivityFactory<T> activityFactory, boolean initialTouchMode, boolean launchActivity)
Creates an ActivityTestRule
for the Activity under test.
Parameters | |
---|---|
activityFactory |
SingleActivityFactory : factory to be used for creating Activity instance |
initialTouchMode |
boolean : true if the Activity should be placed into "touch mode" when started |
launchActivity |
boolean : true if the Activity should be launched once per Test method. It
will be launched before the first Before
method, and terminated after the last After
method.
|
ActivityTestRule
public ActivityTestRule (Class<T> activityClass, String targetPackage, int launchFlags, boolean initialTouchMode, boolean launchActivity)
Creates an ActivityTestRule
for the Activity under test.
Parameters | |
---|---|
activityClass |
Class : The activity under test. This must be a class in the instrumentation
targetPackage specified in the AndroidManifest.xml |
targetPackage |
String : The name of the target package that the Activity is started under. This
value is passed down to the start Intent using Intent.setClassName(android.content.Context, String) . Can not be null. |
launchFlags |
int : launch flags to start the Activity under test.
|
initialTouchMode |
boolean : true if the Activity should be placed into "touch mode" when started |
launchActivity |
boolean : true if the Activity should be launched once per Test method. It
will be launched before the first Before
method, and terminated after the last After
method. |
Public methods
apply
public Statement apply (Statement base, Description description)
Parameters | |
---|---|
base |
Statement |
description |
Description |
Returns | |
---|---|
Statement |
finishActivity
public void finishActivity ()
Finishes the currently launched Activity.
Throws | |
---|---|
IllegalStateException |
if the Activity is not running or failed to finish it. |
getActivity
public T getActivity ()
Returns the reference to the activity under test.
The reference to the activity is assigned during the initial creation of the acivity and for
every sinlge ERROR(/Activity#OnResumed())
lifecycle change.
Note: Lifecycle changes happen on the UI thread (not the instrumentation thread where this test code usually executes). Thus, the return value may vary depending on timing.
For example, if the activity is finished and relaunched, the reference returned by this
method will point to the new instance of the activity assuming ERROR(/Activity#OnResumed())
was
called prior to calling this method.
If the activity wasn't created yet or already finished, null
will be returned.
Note: The activity reference is stored in a weak reference which means if the activity under test is detroyed (ex. back button was pressed) then the system no longer holds a strong reference to the acitivty and this refernce may get garbage collected.
Returns | |
---|---|
T |
getActivityResult
public Instrumentation.ActivityResult getActivityResult ()
This method can be used to retrieve the Instrumentation.ActivityResult
of an Activity that has called
Activity.setResult(int)
. Usually, the result is handled in Activity.onActivityResult(int, int, Intent)
of the parent Activity, that has called Activity.startActivityForResult(Intent, int)
.
This method must not be called before Activity.finish
was called or after the
activity was already destroyed.
Note: This method assumes Activity.setResult(int)
is called no later than in Activity.onPause()
.
Returns | |
---|---|
Instrumentation.ActivityResult |
the Instrumentation.ActivityResult that was set most recently |
Throws | |
---|---|
IllegalStateException |
if the activity is not in finishing state. |
launchActivity
public T launchActivity (Intent startIntent)
Launches the Activity under test.
Don't call this method directly, unless you explicitly requested not to lazily launch the
Activity manually using the launchActivity flag in ActivityTestRule(Class, boolean, boolean)
.
Usage:
@Test public void customIntentToStartActivity() { Intent intent = new Intent(Intent.ACTION_PICK); activity = mActivityRule.launchActivity(intent); }Note: Custom start Intents provided through this method will take precedence over default Intents that where created in the constructor and any Intent returned from
getActivityIntent()
. The same override rules documented in getActivityIntent()
apply.
Parameters | |
---|---|
startIntent |
Intent : The Intent that will be used to start the Activity under test. If startIntent is null, the Intent returned by getActivityIntent()
is used. |
Returns | |
---|---|
T |
the Activity launched by this rule. |
runOnUiThread
public void runOnUiThread (Runnable runnable)
Helper method for running part of a method on the UI thread, blocking until it is complete.
Note: In most cases it is simpler to annotate the test method with UiThreadTest
.
Use this method if you need to switch in and out of the UI thread within your method.
Parameters | |
---|---|
runnable |
Runnable : runnable containing test code in the Runnable.run() method |
Throws | |
---|---|
Throwable |
See also:
Protected methods
afterActivityFinished
protected void afterActivityFinished ()
Override this method to execute any code that should run after the currently launched Activity
is finished. This method is called after each test method, including any method
annotated with After
.
Prefer Before
over this method. This method should usually not be overwritten directly in tests
and only be used by subclasses of ActivityTestRule to get notified when the activity is created
and visible but test runs.
afterActivityLaunched
protected void afterActivityLaunched ()
Override this method to execute any code that should run after your Activity
is
launched, but before any test code is run including any method annotated with Before
.
Prefer Before
over this method. This method should usually not be overwritten directly in tests
and only be used by subclasses of ActivityTestRule to get notified when the activity is created
and visible but test runs.
beforeActivityLaunched
protected void beforeActivityLaunched ()
Override this method to execute any code that should run before your Activity
is
created and launched. This method is called before each test method, including any method
annotated with
Before
.
getActivityIntent
protected Intent getActivityIntent ()
Override this method to set up a custom Intent as if supplied to Context.startActivity(Intent)
. Custom Intents provided by this method will take
precedence over default Intents that where created in the constructor but be overridden by any
Intents passed in through launchActivity(Intent)
.
The default Intent (if this method returns null or is not overwritten) is: action = Intent.ACTION_MAIN
flags = Intent.FLAG_ACTIVITY_NEW_TASK
All other intent fields are
null or empty.
If the custom Intent provided by this methods overrides any of the following fields:
- componentName through
Intent.setClassName(String, String)
- launch flags through
Intent.setFlags(int)
These custom values will be used to start the Activity. However, if some of these values are
not set, the default values documented in ActivityTestRule(Class, String, int, boolean, boolean)
are supplemented.
Returns | |
---|---|
Intent |
The Intent as if supplied to Context.startActivity(Intent) .
|