TestNavigatorState

public final class TestNavigatorState extends NavigatorState

java.lang.Object
   ↳ androidx.navigation.NavigatorState
     ↳ androidx.navigation.testing.TestNavigatorState

An implementation of NavigatorState that allows testing a androidx.navigation.Navigator in isolation (i.e., without requiring a androidx.navigation.NavController).

An optional context can be provided to allow for the usages of androidx.lifecycle.AndroidViewModel within the created NavBackStackEntry instances.

The Lifecycle of all NavBackStackEntry instances added to this TestNavigatorState will be updated as they are added and removed from the state. This work is kicked off on the coroutineDispatcher.

Summary

Public constructors
TestNavigatorState(
    Context context,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Public methods
@NonNull NavBackStackEntry
createBackStackEntry(
    @NonNull NavDestination destination,
    Bundle arguments
)
void

This removes the given NavBackStackEntry from the set of the transitions in progress.
void
pop(@NonNull NavBackStackEntry popUpTo, boolean saveState)

Pop all destinations up to and including popUpTo.
void
popWithTransition(@NonNull NavBackStackEntry popUpTo, boolean saveState)

Pops all destinations up to and including popUpTo.
void

This prepares the given NavBackStackEntry for transition.
void
push(@NonNull NavBackStackEntry backStackEntry)

Adds the given backStackEntry to the backStack.
final @NonNull NavBackStackEntry

Restore a previously saved NavBackStackEntry.

Inherited methods
From androidx.navigation.NavigatorState
abstract @NonNull NavBackStackEntry
createBackStackEntry(
    @NonNull NavDestination destination,
    SavedState arguments
)

Create a new NavBackStackEntry from a given destination and arguments.
final @NonNull StateFlow<@NonNull List<@NonNull NavBackStackEntry>>

While the NavController is responsible for the combined back stack across all Navigators, this back stack is specifically the set of destinations associated with this Navigator.
final @NonNull StateFlow<@NonNull Set<@NonNull NavBackStackEntry>>

This is the set of currently running transitions.
void

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation.
void

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation.
void

Adds the given backStackEntry to the backStack.

Public constructors

TestNavigatorState

Added in 2.4.0
public TestNavigatorState(
    Context context,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Public methods

createBackStackEntry

Added in 2.4.0
public @NonNull NavBackStackEntry createBackStackEntry(
    @NonNull NavDestination destination,
    Bundle arguments
)

markTransitionComplete

public void markTransitionComplete(@NonNull NavBackStackEntry entry)

This removes the given NavBackStackEntry from the set of the transitions in progress. This should be called in conjunction with pushWithTransition and popWithTransition as those call are responsible for adding entries to transitionsInProgress.

This should also always be called in conjunction with prepareForTransition to ensure all NavBackStackEntries settle into the proper state.

Failing to call this method could result in entries being prevented from reaching their final Lifecycle.State}.

See also
pushWithTransition
popWithTransition

pop

public void pop(@NonNull NavBackStackEntry popUpTo, boolean saveState)

Pop all destinations up to and including popUpTo. This will remove those destinations from the backStack, saving their state if saveState is true.

popWithTransition

public void popWithTransition(@NonNull NavBackStackEntry popUpTo, boolean saveState)

Pops all destinations up to and including popUpTo. This also adds the given and incoming entry to the set of in progress transitions. Added entries have their Lifecycle held at Lifecycle.State.CREATED until an entry is passed into the markTransitionComplete callback, when they are allowed to go to Lifecycle.State.DESTROYED and have their state cleared.

This will remove those destinations from the backStack, saving their state if saveState is true.

See also
transitionsInProgress
markTransitionComplete
pushWithTransition

prepareForTransition

public void prepareForTransition(@NonNull NavBackStackEntry entry)

This prepares the given NavBackStackEntry for transition. This should be called in conjunction with markTransitionComplete as that is responsible for settling the NavBackStackEntry into its final state.

See also
markTransitionComplete

push

public void push(@NonNull NavBackStackEntry backStackEntry)

Adds the given backStackEntry to the backStack.

restoreBackStackEntry

Added in 2.4.0
public final @NonNull NavBackStackEntry restoreBackStackEntry(@NonNull NavBackStackEntry previouslySavedEntry)

Restore a previously saved NavBackStackEntry. You must have previously called pop with previouslySavedEntry and true.