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).

Patterns

Pattern: WRONG vs RIGHT — ActivityTestRule (deprecated) vs ActivityScenarioRule

// WRONG
import androidx.test.rule.ActivityTestRule
@Rule
public ActivityTestRule<MyActivity> rule = new ActivityTestRule<>(MyActivity.class);
// WRONG because: ActivityTestRule is @Deprecated at rules-1.7.0/.../ActivityTestRule.java:85.
// Its launch is racy with main-thread state, and lifecycle control is ad hoc.

// RIGHT
import androidx.test.ext.junit.rules.ActivityScenarioRule
@get:Rule
val rule = ActivityScenarioRule(MyActivity::class.java)

Pattern: WRONG vs RIGHT — ActivityScenarioRule import path (the FQN trap)

// WRONG
import androidx.test.rule.ActivityScenarioRule        // class does not exist!
// WRONG because: androidx.test:rules ships only the deprecated ActivityTestRule, not
// ActivityScenarioRule. The IDE auto-completes neither — the import is unresolved.

// RIGHT
import androidx.test.ext.junit.rules.ActivityScenarioRule
// Lives in androidx.test.ext:junit. This is the SINGLE canonical FQN.

Pattern: WRONG vs RIGHT — calling launch / moveToState from the main thread

// WRONG
@Test @UiThreadTest
fun launchOnUiThread() {
    val scenario = ActivityScenario.launch(MyActivity::class.java)  // deadlocks
}
// WRONG because: launch / moveToState / onActivity / close all await an instrumentation
// barrier on the test thread. From the UI thread the barrier never fires (R2 lines 823-828).

// RIGHT
@Test
fun launchFromTestThread() {
    val scenario = ActivityScenario.launch(MyActivity::class.java)
    scenario.onActivity { activity ->
        // UI-thread work goes here, NOT a recursive moveToState/launch
    }
}

Pattern: WRONG vs RIGHT — capturing the activity reference past the lambda

// WRONG
var leaked: MyActivity? = null
scenario.onActivity { leaked = it }
scenario.recreate()
leaked!!.someField   // stale reference; underlying instance is gone

// RIGHT
scenario.onActivity { activity ->
    activity.someField = "new value"
}
// or: re-acquire after recreate()
scenario.recreate()
scenario.onActivity { activity ->
    assertThat(activity.someField).isEqualTo("new value (restored from saved state)")
}

Pattern: WRONG vs RIGHT — relying on "Don't keep activities" for recreate testing

// WRONG
// Toggle Settings.Global.ALWAYS_FINISH_ACTIVITIES to force recreation between activities.
// WRONG because: ActivityScenario does not honor "Don't keep activities" — its barrier
// model expects deterministic transitions. Use scenario.recreate() instead.

// RIGHT
scenario.recreate()  // deterministic onSaveInstanceState → destroy → create → onRestoreInstanceState

Mandatory rules

• MUST import ActivityScenarioRule from androidx.test.ext.junit.rules. The package androidx.test.rule does NOT contain it.
• MUST NOT use ActivityTestRule for new tests — it is @Deprecated. The lint and codemods replace it.
• MUST NOT call ActivityScenario.launch, moveToState, or close from the main thread. They block on an instrumentation barrier that only fires off the UI thread.
• MUST NOT store the activity reference returned by onActivity past the lambda body. recreate() and close() invalidate it.
• MUST NOT rely on Settings.Global.ALWAYS_FINISH_ACTIVITIES to force recreation — ActivityScenario rejects it. Use scenario.recreate().
• MUST declare custom test activities in src/androidTest/AndroidManifest.xml or src/debug/AndroidManifest.xml. The ui-test-manifest artifact only contributes androidx.activity.ComponentActivity.
• MUST call moveToState(Lifecycle.State.DESTROYED) or close() (or use ActivityScenarioRule, which does it automatically) — leaks confuse subsequent tests.
• PREFERRED: use ActivityScenarioRule for class-scoped Activity tests; use ActivityScenario.launch(...).use { } for tests that need fine-grained launch timing.
• PREFERRED: order @get:Rule(order = 0) for Hilt and order = 1 (or higher) for ActivityScenarioRule so Hilt installs before the Activity is launched.

Verification

• grep -r "androidx.test.rule.ActivityScenarioRule" src/ returns nothing — only androidx.test.ext.junit.rules.ActivityScenarioRule is imported.
• grep -r "ActivityTestRule" src/ returns nothing for new code.
• Every custom test Activity is declared in src/androidTest/AndroidManifest.xml or src/debug/AndroidManifest.xml.
• Tests that call scenario.recreate() use rememberSaveable / SavedStateHandle / onSaveInstanceState-backed state for anything that should survive.
• No @UiThreadTest method calls launch / moveToState / close directly.
• ./gradlew :<module>:connectedDebugAndroidTest runs without ActivityNotFoundException or Cannot run onActivity since Activity is not alive.
• Tests that assert on Activity.RESULT_* use launchActivityForResult (not plain launch).

References

• Android Developers — Test your app's activities (ActivityScenario): https://developer.android.com/guide/components/activities/testing
• Android Developers — AndroidX Test guide: https://developer.android.com/training/testing/instrumented-tests/androidx-test-libraries/rules
• AndroidX Test release notes: https://developer.android.com/jetpack/androidx/releases/test
• androidx.test.core.app.ActivityScenario — launch, launchActivityForResult, moveToState, recreate, onActivity, state, result, close. See tasks/research/R2-scenario.md lines 48-160.
• junit-1.3.0/androidx/test/ext/junit/rules/ActivityScenarioRule.java — the canonical JUnit4 wrapper.
• rules-1.7.0/androidx/test/rule/ActivityTestRule.java lines 85-86 — @Deprecated; the deprecation Javadoc explicitly redirects to ActivityScenario.
• tasks/research/R2-scenario.md — full ActivityScenario + FragmentScenario report. Lines 813-919 enumerate every common pitfall (main-thread launch, DESTROYED terminal, recreate() + remember, etc.).
• docs/CORPUS.md Section H.3 — ActivityScenario API surface and JUnit4 wrapper FQN.
• tasks/research/R1-androidx-test-core.md lines 477-535 — the dual-ActivityScenarioRule confusion and the canonical FQN.