FragmentScenario

Kotlin |Java

class FragmentScenario<F : Fragment!>

kotlin.Any
↳	androidx.fragment.app.testing.FragmentScenario

FragmentScenario provides API to start and drive a Fragment's lifecycle state for testing. It works with arbitrary fragments and works consistently across different versions of the Android framework.

FragmentScenario only supports androidx.fragment.app.Fragment. If you are using a deprecated fragment class such as android.support.v4.app.Fragment or android.app.Fragment, please update your code to androidx.fragment.app.Fragment.

If your testing Fragment has a dependency to specific theme such as Theme.AppCompat, use the theme ID parameter in #launch method.

Summary

Nested classes
abstract	FragmentAction FragmentAction interface should be implemented by any class whose instances are intended to be executed by the main thread.

Public methods
static FragmentScenario<F>	launch(@NonNull fragmentClass: Class<F>) Launches a Fragment hosted by an empty FragmentActivity and waits for it to reach the resumed state.
static FragmentScenario<F>	launch(@NonNull fragmentClass: Class<F>, @Nullable fragmentArgs: Bundle?) Launches a Fragment with given arguments hosted by an empty FragmentActivity and waits for it to reach the resumed state.
static FragmentScenario<F>	launch(@NonNull fragmentClass: Class<F>, @Nullable fragmentArgs: Bundle?, @Nullable factory: FragmentFactory?) Launches a Fragment with given arguments hosted by an empty FragmentActivity using the given FragmentFactory and waits for it to reach the resumed state.
static FragmentScenario<F>	launch(@NonNull fragmentClass: Class<F>, @Nullable fragmentArgs: Bundle?, @StyleRes themeResId: Int, @Nullable factory: FragmentFactory?) Launches a Fragment with given arguments hosted by an empty FragmentActivity themed by themeResId, using the given FragmentFactory and waits for it to reach the resumed state.
static FragmentScenario<F>	launch(@NonNull fragmentClass: Class<F>, @Nullable fragmentArgs: Bundle?, @StyleRes themeResId: Int, @NonNull initialState: Lifecycle.State, @Nullable factory: FragmentFactory?) Launches a Fragment with given arguments hosted by an empty FragmentActivity themed by themeResId, using the given FragmentFactory and waits for it to reach initialState.
static FragmentScenario<F>	launchInContainer(@NonNull fragmentClass: Class<F>) Launches a Fragment in the Activity's root view container android.R.id.content, hosted by an empty FragmentActivity and waits for it to reach the resumed state.
static FragmentScenario<F>	launchInContainer(@NonNull fragmentClass: Class<F>, @Nullable fragmentArgs: Bundle?) Launches a Fragment in the Activity's root view container android.R.id.content, with given arguments hosted by an empty FragmentActivity and waits for it to reach the resumed state.
static FragmentScenario<F>	launchInContainer(@NonNull fragmentClass: Class<F>, @Nullable fragmentArgs: Bundle?, @Nullable factory: FragmentFactory?) Launches a Fragment in the Activity's root view container android.R.id.content, with given arguments hosted by an empty FragmentActivity using the given FragmentFactory and waits for it to reach the resumed state.
static FragmentScenario<F>	launchInContainer(@NonNull fragmentClass: Class<F>, @Nullable fragmentArgs: Bundle?, @StyleRes themeResId: Int, @Nullable factory: FragmentFactory?) Launches a Fragment in the Activity's root view container android.R.id.content, with given arguments hosted by an empty FragmentActivity themed by themeResId, using the given FragmentFactory and waits for it to reach the resumed state.
static FragmentScenario<F>	launchInContainer(@NonNull fragmentClass: Class<F>, @Nullable fragmentArgs: Bundle?, @StyleRes themeResId: Int, @NonNull initialState: Lifecycle.State, @Nullable factory: FragmentFactory?) Launches a Fragment in the Activity's root view container android.R.id.content, with given arguments hosted by an empty FragmentActivity themed by themeResId, using the given FragmentFactory and waits for it to reach initialState.
FragmentScenario<F>	moveToState(@NonNull newState: Lifecycle.State) Moves Fragment state to a new state.
FragmentScenario<F>	onFragment(@NonNull action: FragmentScenario.FragmentAction<F>) Runs a given action on the current Activity's main thread.
FragmentScenario<F>	recreate() Recreates the host Activity.

Extension functions
From androidx.fragment.app.testing T FragmentScenario<F>.withFragment(crossinline block: F.() -> T) Run block using FragmentScenario.onFragment, returning the result of the block.

Public methods

launch

@NonNull static fun <F : Fragment!> launch(@NonNull fragmentClass: Class<F>): FragmentScenario<F>

Launches a Fragment hosted by an empty FragmentActivity and waits for it to reach the resumed state.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate

launch

@NonNull static fun <F : Fragment!> launch(
    @NonNull fragmentClass: Class<F>, 
    @Nullable fragmentArgs: Bundle?
): FragmentScenario<F>

Launches a Fragment with given arguments hosted by an empty FragmentActivity and waits for it to reach the resumed state.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate
fragmentArgs	Bundle?: a bundle to passed into fragment

launch

@NonNull static fun <F : Fragment!> launch(
    @NonNull fragmentClass: Class<F>, 
    @Nullable fragmentArgs: Bundle?, 
    @Nullable factory: FragmentFactory?
): FragmentScenario<F>

Launches a Fragment with given arguments hosted by an empty FragmentActivity using the given FragmentFactory and waits for it to reach the resumed state.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate
fragmentArgs	Bundle?: a bundle to passed into fragment
factory	FragmentFactory?: a fragment factory to use or null to use default factory

launch

@NonNull static fun <F : Fragment!> launch(
    @NonNull fragmentClass: Class<F>, 
    @Nullable fragmentArgs: Bundle?, 
    @StyleRes themeResId: Int, 
    @Nullable factory: FragmentFactory?
): FragmentScenario<F>

Launches a Fragment with given arguments hosted by an empty FragmentActivity themed by themeResId, using the given FragmentFactory and waits for it to reach the resumed state.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate
fragmentArgs	Bundle?: a bundle to passed into fragment
themeResId	Int: a style resource id to be set to the host activity's theme
factory	FragmentFactory?: a fragment factory to use or null to use default factory

launch

@NonNull static fun <F : Fragment!> launch(
    @NonNull fragmentClass: Class<F>, 
    @Nullable fragmentArgs: Bundle?, 
    @StyleRes themeResId: Int, 
    @NonNull initialState: Lifecycle.State, 
    @Nullable factory: FragmentFactory?
): FragmentScenario<F>

Launches a Fragment with given arguments hosted by an empty FragmentActivity themed by themeResId, using the given FragmentFactory and waits for it to reach initialState.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate
fragmentArgs	Bundle?: a bundle to passed into fragment
themeResId	Int: a style resource id to be set to the host activity's theme
initialState	Lifecycle.State: The initial Lifecycle.State. This must be one of CREATED, STARTED, and RESUMED.
factory	FragmentFactory?: a fragment factory to use or null to use default factory

launchInContainer

@NonNull static fun <F : Fragment!> launchInContainer(@NonNull fragmentClass: Class<F>): FragmentScenario<F>

Launches a Fragment in the Activity's root view container android.R.id.content, hosted by an empty FragmentActivity and waits for it to reach the resumed state.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate

launchInContainer

@NonNull static fun <F : Fragment!> launchInContainer(
    @NonNull fragmentClass: Class<F>, 
    @Nullable fragmentArgs: Bundle?
): FragmentScenario<F>

Launches a Fragment in the Activity's root view container android.R.id.content, with given arguments hosted by an empty FragmentActivity and waits for it to reach the resumed state.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate
fragmentArgs	Bundle?: a bundle to passed into fragment

launchInContainer

@NonNull static fun <F : Fragment!> launchInContainer(
    @NonNull fragmentClass: Class<F>, 
    @Nullable fragmentArgs: Bundle?, 
    @Nullable factory: FragmentFactory?
): FragmentScenario<F>

Launches a Fragment in the Activity's root view container android.R.id.content, with given arguments hosted by an empty FragmentActivity using the given FragmentFactory and waits for it to reach the resumed state.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate
fragmentArgs	Bundle?: a bundle to passed into fragment
factory	FragmentFactory?: a fragment factory to use or null to use default factory

launchInContainer

@NonNull static fun <F : Fragment!> launchInContainer(
    @NonNull fragmentClass: Class<F>, 
    @Nullable fragmentArgs: Bundle?, 
    @StyleRes themeResId: Int, 
    @Nullable factory: FragmentFactory?
): FragmentScenario<F>

Launches a Fragment in the Activity's root view container android.R.id.content, with given arguments hosted by an empty FragmentActivity themed by themeResId, using the given FragmentFactory and waits for it to reach the resumed state.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate
fragmentArgs	Bundle?: a bundle to passed into fragment
themeResId	Int: a style resource id to be set to the host activity's theme
factory	FragmentFactory?: a fragment factory to use or null to use default factory

launchInContainer

@NonNull static fun <F : Fragment!> launchInContainer(
    @NonNull fragmentClass: Class<F>, 
    @Nullable fragmentArgs: Bundle?, 
    @StyleRes themeResId: Int, 
    @NonNull initialState: Lifecycle.State, 
    @Nullable factory: FragmentFactory?
): FragmentScenario<F>

Launches a Fragment in the Activity's root view container android.R.id.content, with given arguments hosted by an empty FragmentActivity themed by themeResId, using the given FragmentFactory and waits for it to reach initialState.

This method cannot be called from the main thread.

Parameters
fragmentClass	Class<F>: a fragment class to instantiate
fragmentArgs	Bundle?: a bundle to passed into fragment
themeResId	Int: a style resource id to be set to the host activity's theme
initialState	Lifecycle.State: The initial Lifecycle.State. This must be one of CREATED, STARTED, and RESUMED.
factory	FragmentFactory?: a fragment factory to use or null to use default factory

moveToState

@NonNull fun moveToState(@NonNull newState: Lifecycle.State): FragmentScenario<F>

Moves Fragment state to a new state.

If a new state and current state are the same, this method does nothing. It accepts CREATED, STARTED, RESUMED, and DESTROYED. DESTROYED is a terminal state. You cannot move to any other state after the Fragment reaches that state.

This method cannot be called from the main thread.

onFragment

@NonNull fun onFragment(@NonNull action: FragmentScenario.FragmentAction<F>): FragmentScenario<F>

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

Note that you should never keep Fragment reference passed into your action because it can be recreated at anytime during state transitions.

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

This method cannot be called from the main thread.

recreate

@NonNull fun recreate(): FragmentScenario<F>

Recreates the host Activity.

After this method call, it is ensured that the Fragment state goes back to the same state as its previous state.

This method cannot be called from the main thread.