TestNavigatorState

class TestNavigatorState : NavigatorState

kotlin.Any
   ↳ 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?,
    coroutineDispatcher: CoroutineDispatcher
)

Public functions
open NavBackStackEntry
createBackStackEntry(destination: NavDestination, arguments: Bundle?)
open Unit

This removes the given NavBackStackEntry from the set of the transitions in progress.
open Unit
pop(popUpTo: NavBackStackEntry, saveState: Boolean)

Pop all destinations up to and including popUpTo.
open Unit

Pops all destinations up to and including popUpTo.
open Unit

This prepares the given NavBackStackEntry for transition.
open Unit
push(backStackEntry: NavBackStackEntry)

Adds the given backStackEntry to the backStack.
NavBackStackEntry

Restore a previously saved NavBackStackEntry.

Inherited functions
From androidx.navigation.NavigatorState
abstract NavBackStackEntry
createBackStackEntry(destination: NavDestination, arguments: SavedState?)

Create a new NavBackStackEntry from a given destination and arguments.
open Unit

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

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

Adds the given backStackEntry to the backStack.

Inherited properties
From androidx.navigation.NavigatorState
StateFlow<List<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.
StateFlow<Set<NavBackStackEntry>>

This is the set of currently running transitions.

Public constructors

TestNavigatorState

Added in 2.4.0
TestNavigatorState(
    context: Context? = null,
    coroutineDispatcher: CoroutineDispatcher = Dispatchers.Main.immediate
)

Public functions

createBackStackEntry

Added in 2.4.0
open fun createBackStackEntry(destination: NavDestination, arguments: Bundle?): NavBackStackEntry

markTransitionComplete

open fun markTransitionComplete(entry: NavBackStackEntry): Unit

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

open fun pop(popUpTo: NavBackStackEntry, saveState: Boolean): Unit

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

popWithTransition

open fun popWithTransition(popUpTo: NavBackStackEntry, saveState: Boolean): Unit

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

open fun prepareForTransition(entry: NavBackStackEntry): Unit

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

open fun push(backStackEntry: NavBackStackEntry): Unit

Adds the given backStackEntry to the backStack.

restoreBackStackEntry

Added in 2.4.0
fun restoreBackStackEntry(previouslySavedEntry: NavBackStackEntry): NavBackStackEntry

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