ActivityScenario
public
final
class
ActivityScenario
extends Object
implements
AutoCloseable,
Closeable
java.lang.Object | |
↳ | androidx.test.core.app.ActivityScenario<A extends android.app.Activity> |
ActivityScenario provides APIs to start and drive an Activity's lifecycle state for testing. It works with arbitrary activities and works consistently across different versions of the Android framework.
The ActivityScenario API uses Lifecycle.State
extensively. If you are unfamiliar with android.arch.lifecycle
components, please read lifecycle
before starting. It is crucial to understand the difference between Lifecycle.State
and Lifecycle.Event
.
moveToState(State)
allows you to transition your Activity's state to
CREATED
, STARTED
, RESUMED
, or DESTROYED
.
There are two paths for an Activity to reach CREATED
: after ON_CREATE
happens but before ON_START
, or after ON_STOP
. ActivityScenario
always moves the Activity's state using the second path. The same applies to STARTED
.
DESTROYED
is the terminal state. You cannot move your Activity to other state
once it reaches to that state. If you want to test recreation of Activity instance, use recreate()
.
ActivityScenario does't clean up device state automatically and may leave the activity keep
running after the test finishes. Call close()
in your test to clean up the state or use
try-with-resources statement. This is optional but highly recommended to improve the stability of
your tests. Also, consider using ActivityScenarioRule
.
This class is a replacement of ActivityController in Robolectric and ActivityTestRule in ATSL.
Following are the example of common use cases.
Before:
MyActivity activity = Robolectric.setupActivity(MyActivity.class);
assertThat(activity.getSomething()).isEqualTo("something");
After:
try(ActivityScenario<MyActivity> scenario = ActivityScenario.launch(MyActivity.class)) {
scenario.onActivity(activity -> {
assertThat(activity.getSomething()).isEqualTo("something");
});
}
Before:
ActivityController<MyActivity> controller = Robolectric.buildActivity(MyActivity.class);
controller.create().start().resume(); // Moves the activity state to State.RESUMED.
controller.pause(); // Moves the activity state to State.STARTED. (ON_PAUSE is an event).
controller.stop(); // Moves the activity state to State.CREATED. (ON_STOP is an event).
controller.destroy(); // Moves the activity state to State.DESTROYED.
After:
try(ActivityScenario<MyActivity> scenario = ActivityScenario.launch(MyActivity.class)) {
scenario.moveToState(State.RESUMED); // Moves the activity state to State.RESUMED.
scenario.moveToState(State.STARTED); // Moves the activity state to State.STARTED.
scenario.moveToState(State.CREATED); // Moves the activity state to State.CREATED.
scenario.moveToState(State.DESTROYED); // Moves the activity state to State.DESTROYED.
}
Summary
Nested classes | |
---|---|
interface |
ActivityScenario.ActivityAction<A extends Activity>
ActivityAction interface should be implemented by any class whose instances are intended to be executed by the main thread. |
Public methods | |
---|---|
void
|
close()
Finishes the managed activity and cleans up device's state. |
Instrumentation.ActivityResult
|
getResult()
Waits for the activity to be finished and returns the activity result. |
Lifecycle.State
|
getState()
Returns the current activity state. |
static
<A extends Activity>
ActivityScenario<A>
|
launch(Class<A> activityClass)
Launches an activity of a given class and constructs ActivityScenario with the activity. |
static
<A extends Activity>
ActivityScenario<A>
|
launch(Class<A> activityClass, Bundle activityOptions)
|
static
<A extends Activity>
ActivityScenario<A>
|
launch(Intent startActivityIntent)
Launches an activity by a given intent and constructs ActivityScenario with the activity. |
static
<A extends Activity>
ActivityScenario<A>
|
launch(Intent startActivityIntent, Bundle activityOptions)
|
ActivityScenario<A>
|
moveToState(Lifecycle.State newState)
Moves Activity state to a new state. |
ActivityScenario<A>
|
onActivity(ActivityAction<A> action)
Runs a given |
ActivityScenario<A>
|
recreate()
Recreates the Activity. |
Inherited methods | |
---|---|
![]()
java.lang.Object
| |
![]()
java.lang.AutoCloseable
| |
![]()
java.io.Closeable
|
Public methods
close
void close ()
Finishes the managed activity and cleans up device's state. This method blocks execution until
the activity becomes DESTROYED
.
It is highly recommended to call this method after you test is done to keep the device state clean although this is optional.
You may call this method more than once. If the activity has been finished already, this method does nothing.
Avoid calling this method directly. Consider one of the following options instead:
Option 1, use try-with-resources: try (ActivityScenario<MyActivity> scenario = ActivityScenario.launch(MyActivity.class)) { // Your test code goes here. } Option 2, use ActivityScenarioRule:
@Rulepublic ActivityScenarioRule<MyActivity> rule = new ActivityScenarioRule<>(MyActivity.class);
@Testpublic void myTest() { ActivityScenario<MyActivity> scenario = rule.getScenario(); // Your test code goes here. }
getResult
Instrumentation.ActivityResult getResult ()
Waits for the activity to be finished and returns the activity result.
Note: This method doesn't call finish()
. The activity must be finishing or
finished otherwise this method will throws runtime exception after the timeout.
Example:
ActivityScenario<MyActivity> scenario = ActivityScenario.launch(MyActivity.class);
// Let's say MyActivity has a button that finishes itself.
onView(withId(R.id.finish_button)).perform(click());
assertThat(scenario.getResult().getResultCode()).isEqualTo(Activity.RESULT_OK);
Returns | |
---|---|
Instrumentation.ActivityResult |
activity result of the activity that managed by this scenario class. |
getState
Lifecycle.State getState ()
Returns the current activity state. The possible states are CREATED
, STARTED
, RESUMED
, and DESTROYED
.
This method cannot be called from the main thread except in Robolectric tests.
Returns | |
---|---|
Lifecycle.State |
launch
ActivityScenario<A> launch (Class<A> activityClass)
Launches an activity of a given class and constructs ActivityScenario with the activity. Waits
for the lifecycle state transitions to be complete. Typically the initial state of the activity
is RESUMED
but can be in another state. For instance, if your activity calls
finish()
from your onCreate(Bundle)
, the state is DESTROYED
when this method returns.
If you need to supply parameters to the start activity intent, use launch(Intent)
.
This method cannot be called from the main thread except in Robolectric tests.
Parameters | |
---|---|
activityClass |
Class : an activity class to launch |
Returns | |
---|---|
ActivityScenario<A> |
ActivityScenario which you can use to make further state transitions |
Throws | |
---|---|
AssertionError |
if the lifecycle state transition never completes within the timeout |
launch
ActivityScenario<A> launch (Class<A> activityClass, Bundle activityOptions)
Parameters | |
---|---|
activityClass |
Class |
activityOptions |
Bundle : an activity options bundle to be passed along with the intent to start
activity.
|
Returns | |
---|---|
ActivityScenario<A> |
See also:
launch
ActivityScenario<A> launch (Intent startActivityIntent)
Launches an activity by a given intent and constructs ActivityScenario with the activity. Waits
for the lifecycle state transitions to be complete. Typically the initial state of the activity
is RESUMED
but can be in another state. For instance, if your activity calls
finish()
from your onCreate(Bundle)
, the state is DESTROYED
when this method returns.
This method cannot be called from the main thread except in Robolectric tests.
Parameters | |
---|---|
startActivityIntent |
Intent : an intent to start the activity |
Returns | |
---|---|
ActivityScenario<A> |
ActivityScenario which you can use to make further state transitions |
Throws | |
---|---|
AssertionError |
if the lifecycle state transition never completes within the timeout |
launch
ActivityScenario<A> launch (Intent startActivityIntent, Bundle activityOptions)
Parameters | |
---|---|
startActivityIntent |
Intent |
activityOptions |
Bundle : an activity options bundle to be passed along with the intent to start
activity.
|
Returns | |
---|---|
ActivityScenario<A> |
See also:
moveToState
ActivityScenario<A> moveToState (Lifecycle.State newState)
Moves Activity state to a new state.
If a new state and current state are the same, it does nothing. It accepts CREATED
, STARTED
, RESUMED
, and DESTROYED
.
DESTROYED
is the terminal state. You cannot move the state to other state
after the activity reaches that state.
The activity must be at the top of the back stack (excluding internal facilitator activities
started by this library), otherwise AssertionError
may be thrown. If the activity
starts another activity (such as DialogActivity), make sure you close these activities and
bring back the original activity foreground before you call this method.
This method cannot be called from the main thread except in Robolectric tests.
Parameters | |
---|---|
newState |
Lifecycle.State |
Returns | |
---|---|
ActivityScenario<A> |
Throws | |
---|---|
IllegalArgumentException |
if unsupported newState is given |
IllegalStateException |
if Activity is destroyed, finished or finishing |
AssertionError |
if Activity never becomes requested state |
onActivity
ActivityScenario<A> onActivity (ActivityAction<A> action)
Runs a given action
on the current Activity's main thread.
Note that you should never keep Activity reference passed into your action
because
it can be recreated at anytime during state transitions.
Parameters | |
---|---|
action |
ActivityAction |
Returns | |
---|---|
ActivityScenario<A> |
Throws | |
---|---|
IllegalStateException |
if Activity is destroyed, finished or finishing |
recreate
ActivityScenario<A> recreate ()
Recreates the Activity.
A current Activity will be destroyed after its data is saved into Bundle
with onSaveInstanceState(Bundle)
, then it creates a new Activity with the
saved Bundle. After this method call, it is ensured that the Activity state goes back to the
same state as its previous state.
This method cannot be called from the main thread except in Robolectric tests.
Returns | |
---|---|
ActivityScenario<A> |
Throws | |
---|---|
IllegalStateException |
if Activity is destroyed, finished or finishing |
AssertionError |
if Activity never be re-created |
Interfaces
Classes
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2021-02-24 UTC.