# ActivityScenario

Artifact: [androidx.test:core](https://developer.android.com/jetpack/androidx/releases/test) [View Source](https://cs.android.com/search?q=file:androidx/test/core/app/ActivityScenario.java+class:androidx.test.core.app.ActivityScenario)

*** ** * ** ***

<br />

```
class ActivityScenario<A : Activity?> : AutoCloseable, Closeable
```

<br />

*** ** * ** ***

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 `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State` extensively. If you are unfamiliar with `https://developer.android.com/reference/kotlin/androidx/lifecycle/package-summary` components, please read [lifecycle](https://developer.android.com/topic/libraries/architecture/lifecycle#lc) before starting.

It is crucial to understand the difference between `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State` and `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.Event`.

`https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#moveToState(androidx.lifecycle.Lifecycle.State)` allows you to transition your Activity's state to `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#CREATED`, `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#STARTED`, `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#RESUMED`, or `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#DESTROYED`. There are two paths for an Activity to reach `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#CREATED`: after `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.Event#ON_CREATE` happens but before `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.Event#ON_START`, or after `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.Event#ON_STOP`. ActivityScenario always moves the Activity's state using the second path. The same applies to `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#STARTED`.

`https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#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 `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#recreate()`.

ActivityScenario does't clean up device state automatically and may leave the activity keep running after the test finishes. Call `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#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 `https://developer.android.com/reference/kotlin/androidx/test/ext/junit/rules/ActivityScenarioRule`.

This class is a replacement of ActivityController in Robolectric and ActivityTestRule in ATSL.

Following are the example of common use cases.

```kotlin
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 types |
|---|
| `interface https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario.ActivityAction<A : https://developer.android.com/reference/android/app/Activity.html?>` ActivityAction interface should be implemented by any class whose instances are intended to be executed by the main thread. |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#close()()` Finishes the managed activity and cleans up device's state. |
| `https://developer.android.com/reference/android/app/Instrumentation.ActivityResult.html!` | `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#getResult()()` Waits for the activity to be finished and returns the activity result. |
| `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State!` | `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#getState()()` Returns the current activity state. |
| `java-static https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | `<A : https://developer.android.com/reference/android/app/Activity.html?> https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launch(java.lang.Class<A>)(activityClass: https://developer.android.com/reference/java/lang/Class.html<A!>!)` Launches an activity of a given class and constructs ActivityScenario with the activity. |
| `java-static https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | `<A : https://developer.android.com/reference/android/app/Activity.html?> https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launch(android.content.Intent)(startActivityIntent: https://developer.android.com/reference/android/content/Intent.html!)` Launches an activity by a given intent and constructs ActivityScenario with the activity. |
| `java-static https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | `<A : https://developer.android.com/reference/android/app/Activity.html?> https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launch(java.lang.Class<A>,android.os.Bundle)(activityClass: https://developer.android.com/reference/java/lang/Class.html<A!>!, activityOptions: https://developer.android.com/reference/android/os/Bundle.html?)` |
| `java-static https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | `<A : https://developer.android.com/reference/android/app/Activity.html?> https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launch(android.content.Intent,android.os.Bundle)(startActivityIntent: https://developer.android.com/reference/android/content/Intent.html!, activityOptions: https://developer.android.com/reference/android/os/Bundle.html?)` Launches an activity by a given intent and activity options and constructs ActivityScenario with the activity. |
| `java-static https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>` | `<A : https://developer.android.com/reference/android/app/Activity.html?> https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launchActivityForResult(java.lang.Class<A>)(activityClass: https://developer.android.com/reference/java/lang/Class.html<A!>)` Launches an activity of a given class and constructs ActivityScenario with the activity. |
| `java-static https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>` | `<A : https://developer.android.com/reference/android/app/Activity.html?> https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launchActivityForResult(android.content.Intent)(startActivityIntent: https://developer.android.com/reference/android/content/Intent.html)` Launches an activity by a given intent and constructs ActivityScenario with the activity. |
| `java-static https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>` | `<A : https://developer.android.com/reference/android/app/Activity.html?> https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launchActivityForResult(java.lang.Class<A>,android.os.Bundle)( activityClass: https://developer.android.com/reference/java/lang/Class.html<A!>, activityOptions: https://developer.android.com/reference/android/os/Bundle.html? )` Launches an activity of a given class and activity options and constructs ActivityScenario with the activity. |
| `java-static https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>` | `<A : https://developer.android.com/reference/android/app/Activity.html?> https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launchActivityForResult(android.content.Intent,android.os.Bundle)( startActivityIntent: https://developer.android.com/reference/android/content/Intent.html, activityOptions: https://developer.android.com/reference/android/os/Bundle.html? )` Launches an activity by a given intent and constructs ActivityScenario with the activity. |
| `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#moveToState(androidx.lifecycle.Lifecycle.State)(newState: https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State!)` Moves Activity state to a new state. |
| `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#onActivity(androidx.test.core.app.ActivityScenario.ActivityAction<A>)(action: https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario.ActivityAction<A!>!)` Runs a given `action` on the current Activity's main thread. |
| `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#recreate()()` Recreates the Activity. |

## Public functions

### close

```
fun close(): Unit
```

Finishes the managed activity and cleans up device's state. This method blocks execution until the activity becomes `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#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:

````kotlin
           Option 1, use try-with-resources:

 try (ActivityScenario<MyActivity> scenario = ActivityScenario.launch(MyActivity.class)) {
   // Your test code goes here.
 }

 Option 2, use ActivityScenarioRule:
@Rule
          
     
      
```kotlin
 public ActivityScenarioRule<MyActivity> rule = new ActivityScenarioRule<>(MyActivity.class);
```

     
@Test
          
     
      
```kotlin
 public void myTest() {
   ActivityScenario<MyActivity> scenario = rule.getScenario();
   // Your test code goes here.
 }
```

     
        
````

### getResult

```
fun getResult(): Instrumentation.ActivityResult!
```

Waits for the activity to be finished and returns the activity result.

ActivityScenario.launchActivityForResult() must be used to launch an Activity before this method is called.

Note: This method doesn't call `https://developer.android.com/reference/android/app/Activity.html#finish()`. The activity must be finishing or finished otherwise this method will throws runtime exception after the timeout.

```kotlin
Example:
  ActivityScenario<MyActivity> scenario =
     ActivityScenario.launchActivityForResult(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 |
|---|---|
| `https://developer.android.com/reference/android/app/Instrumentation.ActivityResult.html!` | activity result of the activity that managed by this scenario class. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | when you call this method with an Activity that was not started by `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launchActivityForResult(java.lang.Class<A>)` |

### getState

```
fun getState(): Lifecycle.State!
```

Returns the current activity state. The possible states are `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#CREATED`, `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#STARTED`, `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#RESUMED`, and `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#DESTROYED`.

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

### launch

```
java-static fun <A : Activity?> launch(activityClass: Class<A!>!): ActivityScenario<A!>!
```

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 `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#RESUMED` but can be in another state. For instance, if your activity calls `https://developer.android.com/reference/android/app/Activity.html#finish()` from your `https://developer.android.com/reference/android/app/Activity.html#onCreate(android.os.Bundle)`, the state is `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#DESTROYED` when this method returns.

If you need to supply parameters to the start activity intent, use `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launch(android.content.Intent)`.

If you need to get the activity result, use `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launchActivityForResult(java.lang.Class<A>)`.

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

| Parameters |
|---|---|
| `activityClass: https://developer.android.com/reference/java/lang/Class.html<A!>!` | an activity class to launch |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | ActivityScenario which you can use to make further state transitions |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/AssertionError.html` | if the lifecycle state transition never completes within the timeout |

### launch

```
java-static fun <A : Activity?> launch(startActivityIntent: Intent!): ActivityScenario<A!>!
```

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 `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#RESUMED` but can be in another state. For instance, if your activity calls `https://developer.android.com/reference/android/app/Activity.html#finish()` from your `https://developer.android.com/reference/android/app/Activity.html#onCreate(android.os.Bundle)`, the state is `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#DESTROYED` when this method returns.

If you need to get the activity result, use `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launchActivityForResult(android.content.Intent)`.

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

| Parameters |
|---|---|
| `startActivityIntent: https://developer.android.com/reference/android/content/Intent.html!` | an intent to start the activity |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>!` | ActivityScenario which you can use to make further state transitions |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/AssertionError.html` | if the lifecycle state transition never completes within the timeout |

### launch

```
java-static fun <A : Activity?> launch(activityClass: Class<A!>!, activityOptions: Bundle?): ActivityScenario<A!>!
```

| Parameters |
|---|---|
| `activityClass: https://developer.android.com/reference/java/lang/Class.html<A!>!` | an activity class to launch |
| `activityOptions: https://developer.android.com/reference/android/os/Bundle.html?` | an activity options bundle to be passed along with the intent to start activity. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launch(java.lang.Class<A>)` |   |

### launch

```
java-static fun <A : Activity?> launch(startActivityIntent: Intent!, activityOptions: Bundle?): ActivityScenario<A!>!
```

Launches an activity by a given intent and activity options and constructs ActivityScenario with the activity. @see #launch(Intent)

| Parameters |
|---|---|
| `startActivityIntent: https://developer.android.com/reference/android/content/Intent.html!` | an intent to start the activity |
| `activityOptions: https://developer.android.com/reference/android/os/Bundle.html?` | an activity options bundle to be passed along with the intent to start activity. |

### launchActivityForResult

```
java-static fun <A : Activity?> launchActivityForResult(activityClass: Class<A!>): ActivityScenario<A!>
```

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 `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#RESUMED` but can be in another state. For instance, if your activity calls `https://developer.android.com/reference/android/app/Activity.html#finish()` from your `https://developer.android.com/reference/android/app/Activity.html#onCreate(android.os.Bundle)`, the state is `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#DESTROYED` when this method returns. Broadcasts activity result.

If you need to supply parameters to the start activity intent, use `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario#launchActivityForResult(android.content.Intent)`.

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

| Parameters |
|---|---|
| `activityClass: https://developer.android.com/reference/java/lang/Class.html<A!>` | an activity class to launch |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>` | ActivityScenario which you can use to make further state transitions |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/AssertionError.html` | if the lifecycle state transition never completes within the timeout |

### launchActivityForResult

```
java-static fun <A : Activity?> launchActivityForResult(startActivityIntent: Intent): ActivityScenario<A!>
```

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 `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#RESUMED` but can be in another state. For instance, if your activity calls `https://developer.android.com/reference/android/app/Activity.html#finish()` from your `https://developer.android.com/reference/android/app/Activity.html#onCreate(android.os.Bundle)`, the state is `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#DESTROYED` when this method returns. Broadcasts activity result.

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

If you are using AndroidX based activities, use androidx.activity.result.ActivityResult instead of this method. See https://developer.android.com/training/basics/intents/result#test

| Parameters |
|---|---|
| `startActivityIntent: https://developer.android.com/reference/android/content/Intent.html` | an intent to start the activity |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/core/app/ActivityScenario<A!>` | ActivityScenario which you can use to make further state transitions |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/AssertionError.html` | if the lifecycle state transition never completes within the timeout |

### launchActivityForResult

```
java-static fun <A : Activity?> launchActivityForResult(
    activityClass: Class<A!>,
    activityOptions: Bundle?
): ActivityScenario<A!>
```

Launches an activity of a given class and activity options and constructs ActivityScenario with the activity. @see #launchActivityForResult(Class)

| Parameters |
|---|---|
| `activityClass: https://developer.android.com/reference/java/lang/Class.html<A!>` | an activity class to launch |
| `activityOptions: https://developer.android.com/reference/android/os/Bundle.html?` | an activity options bundle to be passed along with the intent to start activity. |

### launchActivityForResult

```
java-static fun <A : Activity?> launchActivityForResult(
    startActivityIntent: Intent,
    activityOptions: Bundle?
): ActivityScenario<A!>
```

Launches an activity by a given intent and constructs ActivityScenario with the activity. @see #launchActivityForResult(Intent)

| Parameters |
|---|---|
| `startActivityIntent: https://developer.android.com/reference/android/content/Intent.html` | an intent to start the activity |
| `activityOptions: https://developer.android.com/reference/android/os/Bundle.html?` | an activity options bundle to be passed along with the intent to start activity. |

### moveToState

```
fun moveToState(newState: Lifecycle.State!): ActivityScenario<A!>!
```

Moves Activity state to a new state.

If a new state and current state are the same, it does nothing. It accepts `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#CREATED`, `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#STARTED`, `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#RESUMED`, and `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#DESTROYED`.

`https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#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 `https://developer.android.com/reference/java/lang/AssertionError.html` 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.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if unsupported `newState` is given |
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if Activity is destroyed, finished or finishing |
| `https://developer.android.com/reference/java/lang/AssertionError.html` | if Activity never becomes requested state |

### onActivity

```
fun onActivity(action: ActivityScenario.ActivityAction<A!>!): ActivityScenario<A!>!
```

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.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if Activity is destroyed, finished or finishing |

### recreate

```
fun recreate(): ActivityScenario<A!>!
```

Recreates the Activity.

A current Activity will be destroyed after its data is saved into `https://developer.android.com/reference/android/os/Bundle.html` with `https://developer.android.com/reference/android/app/Activity.html#onSaveInstanceState(android.os.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.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if Activity is destroyed, finished or finishing |
| `https://developer.android.com/reference/java/lang/AssertionError.html` | if Activity never be re-created |