Launching Fragments With Fragmentscenario

Launching Fragments with FragmentScenario — Test Fragments in Isolation

FragmentScenario hosts a single fragment inside an internal EmptyFragmentActivity so the fragment's onCreate / onViewCreated / lifecycle can be exercised without a real screen. Two entry points exist: launchFragmentInContainer<F>() adds the fragment to android.R.id.content (full lifecycle including view), and launchFragment<F>() attaches it with no container (headless). The default theme extends android:Theme.WithActionBar, NOT AppCompat — overriding via themeResId is required for any AppCompat widget. This skill encodes the two artifacts, the theme trap, and the navigation limitation.

When to use this skill

• The user wants to test a single Fragment without launching the full host Activity.
• A test crashes with IllegalArgumentException: You need to use a Theme.AppCompat theme (or descendant) with the design library and the fragment uses AppCompat / Material widgets.
• A test calls findNavController() and crashes with Fragment ... does not have a NavController set.
• The user wants to drive lifecycle (STARTED / RESUMED / DESTROYED) on a fragment for state-change testing.
• The user wants to inject a custom FragmentFactory for a fragment that doesn't have a no-arg constructor.
• The user mentions "headless fragment" or asks why onViewCreated doesn't fire.

When NOT to use this skill

• The host is an Activity, not a Fragment — see ../launching-activities-with-activityscenario/SKILL.md.
• The fragment requires a real navigation stack (NavHostFragment) — FragmentScenario does not provide one; use a custom test host activity that wires up NavHostFragment instead, or TestNavHostController.
• The runner / dependency stack is not yet set up — start with ../../runner/running-instrumented-tests-with-androidjunit4/SKILL.md.
• The fragment hosts Compose content and the test interacts via the Compose tree — see ../../../compose/setup/configuring-test-dependencies/SKILL.md.

Prerequisites

• androidTestImplementation("androidx.fragment:fragment-testing:1.8.x") — the API: FragmentScenario, launchFragmentInContainer, launchFragment, withFragment.
• debugImplementation("androidx.fragment:fragment-testing-manifest:1.8.x") — the manifest entry that declares EmptyFragmentActivity. Android M+ requires this artifact be on debugImplementation (or testImplementation for host tests) so the manifest merger picks up EmptyFragmentActivity.
• The runner stack from ../../runner/running-instrumented-tests-with-androidjunit4/SKILL.md.

Workflow

• 1. Add both artifacts on the right configurations. The two-artifact split is non-negotiable on Android M+:

dependencies {
    androidTestImplementation("androidx.fragment:fragment-testing:1.8.5")
    debugImplementation("androidx.fragment:fragment-testing-manifest:1.8.5")
}

fragment-testing ships the API; fragment-testing-manifest ships only the <activity android:name="androidx.fragment.app.testing.EmptyFragmentActivity"> manifest entry plus the default theme. Without the manifest artifact, launchFragmentInContainer / launchFragment crash with ActivityNotFoundException: EmptyFragmentActivity. From tasks/research/R2-scenario.md lines 568-619.

• 2. Pick the launcher by view requirement.

import androidx.fragment.app.testing.launchFragment
import androidx.fragment.app.testing.launchFragmentInContainer

// In-container — adds at android.R.id.content; full lifecycle including onCreateView/onViewCreated
val s1: FragmentScenario<MyFragment> = launchFragmentInContainer<MyFragment>()

// Headless — containerViewId = 0; onCreateView still runs but the view is not attached to a window
val s2: FragmentScenario<MyHeadlessFragment> = launchFragment<MyHeadlessFragment>()

launchFragmentInContainer uses containerViewId = android.R.id.content (isViewAttachedToWindow == true). launchFragment uses containerViewId = 0 (headless; isViewAttachedToWindow == false). Source: R2 lines 263-389, 683-684.

• 3. Pass fragmentArgs for fragments that read requireArguments().

val args = bundleOf("user_id" to 42, "from_deep_link" to true)
val scenario = launchFragmentInContainer<UserDetailFragment>(fragmentArgs = args)

• 4. For AppCompat / Material fragments, override themeResId to an AppCompat theme. The default theme FragmentScenarioEmptyFragmentActivityTheme extends android:Theme.WithActionBar (the platform Holo theme), NOT Theme.AppCompat. AppCompat widgets crash at inflation with You need to use a Theme.AppCompat theme (or descendant) with the design library. From R2 lines 466-501:

val scenario = launchFragmentInContainer<MyAppCompatFragment>(
    themeResId = R.style.Theme_MyApp,    // any AppCompat / Material theme
)

EmptyFragmentActivity.setTheme is called BEFORE super.onCreate, so the override applies before any fragment view inflation runs (R2 lines 490-501).

• 5. Inject a FragmentFactory for non-default-constructor fragments. Both launchers accept a factory: FragmentFactory? parameter (R2 lines 263-323). The factory is stored in a FragmentFactoryHolderViewModel keyed off the EmptyFragmentActivity's ViewModelStore, which means it survives recreate():

class MyFragment(private val repo: UserRepository) : Fragment() { /* ... */ }

val factory = object : FragmentFactory() {
    override fun instantiate(classLoader: ClassLoader, className: String): Fragment {
        return when (loadFragmentClass(classLoader, className)) {
            MyFragment::class.java -> MyFragment(FakeUserRepository())
            else -> super.instantiate(classLoader, className)
        }
    }
}
val scenario = launchFragmentInContainer<MyFragment>(factory = factory)

Or use the no-factory inline overload that accepts a single-instance trailing lambda:

val scenario = launchFragmentInContainer { MyFragment(FakeUserRepository()) }

• 6. Drive lifecycle with moveToState and inspect with onFragment. Same semantics as ActivityScenario:

import androidx.lifecycle.Lifecycle

scenario.moveToState(Lifecycle.State.STARTED)        // pause
scenario.onFragment { fragment ->                    // UI thread
    assertThat(fragment.someState).isEqualTo("ready")
}
scenario.recreate()                                  // configuration-change emulation
scenario.moveToState(Lifecycle.State.DESTROYED)      // terminal

initialState = Lifecycle.State.DESTROYED is rejected with IllegalArgumentException: Cannot set initial Lifecycle state to DESTROYED for FragmentScenario — the require(...) at fragment-testing/src/main/.../FragmentScenario.kt:496-498 (R2 lines 699-718). Launch with CREATED and then moveToState(DESTROYED) instead.

• 7. Capture cross-thread state via withFragment { } instead of holder fields. withFragment is the suspending/return-value variant of onFragment that propagates exceptions and return values cleanly (R2 lines 670-680):

val viewLifecycleOwner = scenario.withFragment { viewLifecycleOwner }
val isAdded = scenario.withFragment { isAdded }

• 8. Recognize the findNavController() limitation. EmptyFragmentActivity does NOT install a NavHostFragment. findNavController() from a hosted fragment throws IllegalStateException: Fragment ... does not have a NavController set (R2 lines 852-874). Workarounds:

// Option A: TestNavHostController on the fragment view before onStart
launchFragmentInContainer {
    MyFragment().also { fragment ->
        fragment.viewLifecycleOwnerLiveData.observeForever { vlo ->
            if (vlo != null) {
                val testNav = TestNavHostController(ApplicationProvider.getApplicationContext())
                testNav.setGraph(R.navigation.my_graph)
                Navigation.setViewNavController(fragment.requireView(), testNav)
            }
        }
    }
}

// Option B: write a custom test host Activity that hosts NavHostFragment, declared in
// src/androidTest/AndroidManifest.xml, and use ActivityScenarioRule on it instead.

• 9. Close the scenario. FragmentScenario is Closeable:

launchFragmentInContainer<MyFragment>().use { scenario ->
    scenario.onFragment { /* ... */ }
}

close() drives the Activity to DESTROYED. Calling onFragment after DESTROYED throws IllegalStateException: The fragment has been removed from the FragmentManager already. (FragmentScenario.kt:308-310, R2 lines 815-821).