FragmentScenario

public final class FragmentScenario<F extends Fragment> implements Closeable

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.

Parameters
<F extends Fragment>

The Fragment class being tested
See also
ActivityScenario

a scenario API for Activity

Summary

Nested types
public fun interface FragmentScenario.FragmentAction<F extends Fragment>

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

Public methods
void

Finishes the managed fragments and cleans up device's state.
static final @NonNull FragmentScenario<@NonNull F>
<F extends Fragment> launch(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    FragmentFactory factory
)

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 final @NonNull FragmentScenario<@NonNull F>
<F extends Fragment> launch(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    @StyleRes int themeResId,
    FragmentFactory factory
)

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 final @NonNull FragmentScenario<@NonNull F>
<F extends Fragment> launch(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    @StyleRes int themeResId,
    @NonNull Lifecycle.State initialState,
    FragmentFactory factory
)

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 final @NonNull FragmentScenario<@NonNull F>
<F extends Fragment> launchInContainer(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    FragmentFactory factory
)

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 final @NonNull FragmentScenario<@NonNull F>
<F extends Fragment> launchInContainer(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    @StyleRes int themeResId,
    FragmentFactory factory
)

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 final @NonNull FragmentScenario<@NonNull F>
<F extends Fragment> launchInContainer(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    @StyleRes int themeResId,
    @NonNull Lifecycle.State initialState,
    FragmentFactory factory
)

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.
final @NonNull FragmentScenario<@NonNull F>

Moves Fragment state to a new state.
final @NonNull FragmentScenario<@NonNull F>

Runs a given action on the current Activity's main thread.
final @NonNull FragmentScenario<@NonNull F>

Recreates the host Activity.

Extension functions
final @NonNull T
<F extends Fragment, T extends Object> FragmentScenarioKt.withFragment(
    @NonNull FragmentScenario<@NonNull F> receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull F, @NonNull T> block
)

Run block using FragmentScenario.onFragment, returning the result of the block.

Public methods

close

Added in 1.4.0
public void close()

Finishes the managed fragments and cleans up device's state. This method blocks execution until the host activity becomes Lifecycle.State.DESTROYED.

launch

Added in 1.3.0
public static final @NonNull FragmentScenario<@NonNull F> <F extends Fragment> launch(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    FragmentFactory factory
)

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
@NonNull Class<@NonNull F> fragmentClass

a fragment class to instantiate
Bundle fragmentArgs

a bundle to passed into fragment
FragmentFactory factory

a fragment factory to use or null to use default factory

launch

Added in 1.3.0
public static final @NonNull FragmentScenario<@NonNull F> <F extends Fragment> launch(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    @StyleRes int themeResId,
    FragmentFactory factory
)

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
@NonNull Class<@NonNull F> fragmentClass

a fragment class to instantiate
Bundle fragmentArgs

a bundle to passed into fragment
@StyleRes int themeResId

a style resource id to be set to the host activity's theme
FragmentFactory factory

a fragment factory to use or null to use default factory

launch

Added in 1.3.0
public static final @NonNull FragmentScenario<@NonNull F> <F extends Fragment> launch(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    @StyleRes int themeResId,
    @NonNull Lifecycle.State initialState,
    FragmentFactory factory
)

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
@NonNull Class<@NonNull F> fragmentClass

a fragment class to instantiate
Bundle fragmentArgs

a bundle to passed into fragment
@StyleRes int themeResId

a style resource id to be set to the host activity's theme
@NonNull Lifecycle.State initialState

The initial Lifecycle.State. Passing in DESTROYED will result in an IllegalArgumentException.
FragmentFactory factory

a fragment factory to use or null to use default factory

launchInContainer

Added in 1.3.0
public static final @NonNull FragmentScenario<@NonNull F> <F extends Fragment> launchInContainer(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    FragmentFactory factory
)

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
@NonNull Class<@NonNull F> fragmentClass

a fragment class to instantiate
Bundle fragmentArgs

a bundle to passed into fragment
FragmentFactory factory

a fragment factory to use or null to use default factory

launchInContainer

Added in 1.3.0
public static final @NonNull FragmentScenario<@NonNull F> <F extends Fragment> launchInContainer(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    @StyleRes int themeResId,
    FragmentFactory factory
)

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
@NonNull Class<@NonNull F> fragmentClass

a fragment class to instantiate
Bundle fragmentArgs

a bundle to passed into fragment
@StyleRes int themeResId

a style resource id to be set to the host activity's theme
FragmentFactory factory

a fragment factory to use or null to use default factory

launchInContainer

Added in 1.3.0
public static final @NonNull FragmentScenario<@NonNull F> <F extends Fragment> launchInContainer(
    @NonNull Class<@NonNull F> fragmentClass,
    Bundle fragmentArgs,
    @StyleRes int themeResId,
    @NonNull Lifecycle.State initialState,
    FragmentFactory factory
)

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
@NonNull Class<@NonNull F> fragmentClass

a fragment class to instantiate
Bundle fragmentArgs

a bundle to passed into fragment
@StyleRes int themeResId

a style resource id to be set to the host activity's theme
@NonNull Lifecycle.State initialState

The initial Lifecycle.State. Passing in DESTROYED will result in an IllegalArgumentException.
FragmentFactory factory

a fragment factory to use or null to use default factory

moveToState

Added in 1.1.0
public final @NonNull FragmentScenario<@NonNull F> moveToState(@NonNull Lifecycle.State newState)

Moves Fragment state to a new state.

If a new state and current state are the same, this method does nothing. It accepts all Lifecycle.States. 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

Added in 1.1.0
public final @NonNull FragmentScenario<@NonNull F> onFragment(@NonNull FragmentScenario.FragmentAction<@NonNull F> action)

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

Added in 1.1.0
public final @NonNull FragmentScenario<@NonNull F> recreate()

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.

Extension functions

FragmentScenarioKt.withFragment

public final @NonNull T <F extends Fragment, T extends Object> FragmentScenarioKt.withFragment(
    @NonNull FragmentScenario<@NonNull F> receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull F, @NonNull T> block
)

Run block using FragmentScenario.onFragment, returning the result of the block.

If any exceptions are raised while running block, they are rethrown.