ActivityScenario

public final class ActivityScenario
extends Object

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, and after ON_STOP. ActivityScenario always moves the Activity's state to the second one. 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().

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:
   ActivityScenario scenario = ActivityScenario.launch(MyActivity.class);
   scenario.onActivity(activity -> {
     assertThat(activity.getSomething()).isEqualTo("something");
   });

 Before:
   ActivityController controller = Robolectric.buildActivity(MyActivity.class);
   controller.create().start().resume();
   controller.get();          // Returns resumed activity.
   controller.pause().get();  // Returns paused activity.
   controller.stop().get();   // Returns stopped activity.
   controller.destroy();      // Destroys activity.

 After:
   ActivityScenario scenario = ActivityScenario.launch(MyActivity.class);
   scenario.onActivity(activity -> {});  // Your activity is resumed.
   scenario.moveTo(State.STARTED);
   scenario.onActivity(activity -> {});  // Your activity is paused.
   scenario.moveTo(State.CREATED);
   scenario.onActivity(activity -> {});  // Your activity is stopped.
   scenario.moveTo(State.DESTROYED);     // Your activity is destroyed and finished.
 

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

static <A extends Activity> ActivityScenario<A> launch(Class<A> activityClass)

Launches an activity of a given class and constructs ActivityScenario with the activity.

ActivityScenario<A> moveToState(Lifecycle.State newState)

Moves Activity state to a new state.

ActivityScenario<A> onActivity(ActivityAction<A> action)

Runs a given action on the current Activity's main thread.

ActivityScenario<A> recreate()

Recreates the Activity.

Inherited methods

From class java.lang.Object

Public methods

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.

Normally this would be RESUMED, but may be another state.

This method cannot be called from the main thread except in Robolectric tests.

Parameters
activityClass Class

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

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.

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.

Throwing an exception from action makes the Activity to crash. You can inspect the exception in logcat outputs.

This method cannot be called from the main thread except in Robolectric tests.

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