Launching Activities With Activityscenario

Launching Activities with ActivityScenario — The Canonical ActivityTestRule Replacement

ActivityScenario is the modern replacement for the deprecated ActivityTestRule. It provides a thread-safe, lifecycle-aware handle to drive an Activity through CREATED / STARTED / RESUMED / DESTROYED, recreate it for configuration-change emulation, and post work onto its UI thread via onActivity { }. The JUnit4 wrapper ActivityScenarioRule calls launch in before and close in after. This skill encodes the canonical FQN trap, the threading rules, and the manifest requirement.

When to use this skill

• The user is starting a new instrumentation test that needs an Activity host.
• The user is migrating from ActivityTestRule (deprecated) and asks for the replacement.
• A test fails with ActivityNotFoundException and the Activity is missing from the test APK manifest.
• A recreate() test "loses" state and the user is debugging remember vs rememberSaveable.
• The user posts an action onto the UI thread and the test deadlocks (onActivity called from the wrong thread).
• A test calls setResult(...) + finish() and wants to read the Activity.RESULT_* back.
• The user mentions Settings.Global.ALWAYS_FINISH_ACTIVITIES ("Don't keep activities") as a way to test recreation — ActivityScenario rejects it.

When NOT to use this skill

• The host is a Fragment, not an Activity — see ../launching-fragments-with-fragmentscenario/SKILL.md.
• The host is androidx.activity.ComponentActivity for Compose tests — createComposeRule() already wraps the scenario; see ../../../compose/setup/configuring-test-dependencies/SKILL.md.
• The runner / dependency stack is not yet set up — start with ../../runner/running-instrumented-tests-with-androidjunit4/SKILL.md.
• The user needs to interact with system UI or another app — see ../../uiautomator/cross-app-tests-with-uiautomator/SKILL.md.
• The user is choosing between host (Robolectric) and device tests — see ../../../compose/setup/setting-up-host-vs-device-tests/SKILL.md.

Prerequisites

• androidTestImplementation("androidx.test:core:1.7.0") for androidx.test.core.app.ActivityScenario.
• androidTestImplementation("androidx.test.ext:junit:1.3.0") for androidx.test.ext.junit.rules.ActivityScenarioRule.
• androidTestImplementation("androidx.test:runner:1.7.0") and testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" from the runner skill.
• The test Activity declared in src/androidTest/AndroidManifest.xml, src/debug/AndroidManifest.xml, or the production manifest.

Workflow

• 1. Pick the launch entry point. All four are static factories on androidx.test.core.app.ActivityScenario:

import androidx.test.core.app.ActivityScenario
import androidx.test.core.app.launchActivity                 // Kotlin reified extension

// Plain class-based launch
val s1: ActivityScenario<MyActivity> = ActivityScenario.launch(MyActivity::class.java)

// Reified inline (KTX)
val s2 = launchActivity<MyActivity>()

// With explicit intent (extras / data uri / action)
val intent = Intent(ApplicationProvider.getApplicationContext(), MyActivity::class.java)
    .putExtra("user_id", 42)
val s3 = ActivityScenario.launch<MyActivity>(intent)

// For activities that call setResult(...) + finish() before reaching RESUMED
val s4 = ActivityScenario.launchActivityForResult(MyActivity::class.java)

launch blocks the caller until the Activity reaches RESUMED. launchActivityForResult blocks until the Activity completes — read scenario.result afterwards. Source: androidx.test.core.app.ActivityScenario (per tasks/research/R2-scenario.md lines 48-93).

• 2. Drive lifecycle with moveToState(Lifecycle.State.*). Allowed targets: CREATED, STARTED, RESUMED, DESTROYED. DESTROYED is terminal — once reached the scenario cannot move back (lines 100-102 of R2):

import androidx.lifecycle.Lifecycle

scenario.moveToState(Lifecycle.State.STARTED)   // pause behind another activity
scenario.moveToState(Lifecycle.State.RESUMED)   // back to foreground
scenario.moveToState(Lifecycle.State.DESTROYED) // terminal — close() is now a no-op

moveToState cannot be called from the main thread; calling from a @UiThreadTest method or from inside a Looper handler deadlocks because it await(...)s an instrumentation barrier from the test thread (R2 lines 823-828).

• 3. Use recreate() to emulate a configuration change. This runs onSaveInstanceState, destroys the Activity, creates a fresh instance, and runs onRestoreInstanceState. State stored via rememberSaveable / SavedStateHandle / Bundle survives. Plain remember { ... } and bare var fields do not (R2 lines 839-850):

scenario.recreate()
scenario.onActivity { activity ->
    // activity is now a fresh instance
    assertThat(activity.viewModel.count).isEqualTo(2)  // survives if hoisted in the ViewModel
}

If a test asserts that state survives recreate() and finds it gone, the production code probably uses remember, not rememberSaveable.

• 4. Read or mutate the Activity inside onActivity { activity -> }. This block runs on the UI thread, blocks the test thread until done, and is the only legal way to touch fields/views directly:

scenario.onActivity { activity ->
    activity.findViewById<EditText>(R.id.email).setText("test@example.com")
    activity.viewModel.refresh()
}

The activity reference is scoped to the lambda. Never store it past the lambda body — recreate() invalidates it, and close() destroys the instance.

To capture data out of the scope, use a holder (R2 lines 649-658):

var captured: MyActivity? = null
scenario.onActivity { captured = it }
val current: MyActivity = captured!!

• 5. Read Activity.RESULT_* via scenario.result. Only valid for scenarios launched with launchActivityForResult, and only after the Activity has called setResult(...) + finish():

val scenario = ActivityScenario.launchActivityForResult(LoginActivity::class.java)
scenario.onActivity { it.confirmLogin() }       // calls setResult(RESULT_OK) + finish()
val result: Instrumentation.ActivityResult = scenario.result
assertThat(result.resultCode).isEqualTo(Activity.RESULT_OK)

• 6. Prefer the ActivityScenarioRule JUnit4 wrapper for class-scoped activities. Single canonical FQN — androidx.test.ext.junit.rules.ActivityScenarioRule. The package androidx.test.rule does NOT contain ActivityScenarioRule; it only ships the deprecated ActivityTestRule. This is the most common confusion when migrating (R2 line 490):

import androidx.test.ext.junit.rules.ActivityScenarioRule
import org.junit.Rule

@get:Rule
val activityRule = ActivityScenarioRule(LoginActivity::class.java)

@Test
fun loginButtonEnablesAfterEmail() {
    activityRule.scenario.onActivity { it.email = "x@y.z" }
    // ...
}

The rule calls ActivityScenario.launch in before and scenario.close() in after.

• 7. For @Rule(order = N) ordering with Hilt, place Hilt outermost. Lower numbers evaluate outer first (closest to the test method runs last):

@get:Rule(order = 0) val hiltRule = HiltAndroidRule(this)
@get:Rule(order = 1) val activityRule = ActivityScenarioRule(LoginActivity::class.java)

• 8. Declare every test Activity in a manifest the test APK will see. The ui-test-manifest artifact only contributes androidx.activity.ComponentActivity; custom test activities must be declared by the developer in src/androidTest/AndroidManifest.xml or src/debug/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <activity android:name=".MyTestHostActivity" android:exported="true" />
    </application>
</manifest>

Without this, ActivityScenario.launch throws ActivityNotFoundException regardless of what is in production. See ../../../compose/setup/configuring-test-dependencies/SKILL.md for the parallel Compose story.

• 9. Close the scenario. When using ActivityScenarioRule, JUnit calls close() automatically. When launching ad hoc, use Kotlin use { } (the scenario implements java.io.Closeable) per R2 lines 138-150:

ActivityScenario.launch<MyActivity>().use { scenario ->
    scenario.onActivity { /* ... */ }
}

close() drives the activity to DESTROYED regardless of current state and is idempotent — safe to call after moveToState(DESTROYED) (no-op).