TestNavigatorState

public final class TestNavigatorState extends NavigatorState

Object
   ↳ NavigatorState
     ↳ 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 fields

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 List<@NonNull NavBackStackEntry>>

This is the set of currently running transitions.

Public constructors

TestNavigatorState(
    @Nullable Context context,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Public methods

@NonNull NavBackStackEntry
createBackStackEntry(
    @NonNull NavDestination destination,
    @Nullable Bundle arguments
)

Create a new NavBackStackEntry from a given destination and 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
push(@NonNull NavBackStackEntry backStackEntry)

Adds the given backStackEntry to the backStack.

final @NonNull NavBackStackEntry

Restore a previously saved NavBackStackEntry.

Inherited methods

From class NavigatorState
@CallSuper 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 fields

backStack

@NonNull
public final @NonNull StateFlow<@NonNull List<@NonNull NavBackStackEntry>> backStack

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.

Changing the back stack must be done via push and pop.

transitionsInProgress

@NonNull
public final @NonNull StateFlow<@NonNull List<@NonNull NavBackStackEntry>> transitionsInProgress

This is the set of currently running transitions. Use this set to retrieve the entry and call markTransitionComplete once the transition is complete.

Public constructors

TestNavigatorState

public final TestNavigatorState(
    @Nullable Context context,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Public methods

createBackStackEntry

@NonNull
public NavBackStackEntry createBackStackEntry(
    @NonNull NavDestination destination,
    @Nullable Bundle arguments
)

Create a new NavBackStackEntry from a given destination and arguments.

markTransitionComplete

@NonNull
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.

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

pop

@NonNull
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

@NonNull
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.

push

@NonNull
public void push(@NonNull NavBackStackEntry backStackEntry)

Adds the given backStackEntry to the backStack.

restoreBackStackEntry

@NonNull
public final NavBackStackEntry restoreBackStackEntry(@NonNull NavBackStackEntry previouslySavedEntry)

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