TestNavigatorState

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
)
android

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

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

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

Pop all destinations up to and including popUpTo.
android
open Unit

Pops all destinations up to and including popUpTo.
android
open Unit

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

Adds the given backStackEntry to the backStack.
android
NavBackStackEntry

Restore a previously saved NavBackStackEntry.
android

Inherited functions
From androidx.navigation.NavigatorState
open Unit

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

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

Adds the given backStackEntry to the backStack.
android

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.
android
StateFlow<Set<NavBackStackEntry>>

This is the set of currently running transitions.
android

Public constructors

TestNavigatorState

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

Public functions

createBackStackEntry

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

Create a new NavBackStackEntry from a given destination and arguments.

markTransitionComplete

android 
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

android 
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

android 
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

android 
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

android 
open fun push(backStackEntry: NavBackStackEntry): Unit

Adds the given backStackEntry to the backStack.

restoreBackStackEntry

android
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.