TestNavigatorState

Artifact: androidx.navigation:navigation-testing

Added in 2.4.0

Kotlin |Java

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 )` Create a new `NavBackStackEntry` from a given `destination` and `arguments`.
`void`	`markTransitionComplete(@NonNull NavBackStackEntry entry)` 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`	`prepareForTransition(@NonNull NavBackStackEntry entry)` This prepares the given `NavBackStackEntry` for transition.
`void`	`push(@NonNull NavBackStackEntry backStackEntry)` Adds the given `backStackEntry` to the `backStack`.
`final @NonNull NavBackStackEntry`	`restoreBackStackEntry(@NonNull NavBackStackEntry previouslySavedEntry)` Restore a previously saved `NavBackStackEntry`.

Inherited methods

From androidx.navigation.NavigatorState

`final @NonNull StateFlow<@NonNull List<@NonNull NavBackStackEntry>>`	`getBackStack()` 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>>`	`getTransitionsInProgress()` This is the set of currently running transitions.
`void`	`@CallSuper onLaunchSingleTop(@NonNull NavBackStackEntry backStackEntry)` Informational callback indicating that the given `backStackEntry` has been affected by a `NavOptions.shouldLaunchSingleTop` operation.
`void`	`@CallSuper onLaunchSingleTopWithTransition( @NonNull NavBackStackEntry backStackEntry )` Informational callback indicating that the given `backStackEntry` has been affected by a `NavOptions.shouldLaunchSingleTop` operation.
`void`	`pushWithTransition(@NonNull NavBackStackEntry backStackEntry)` Adds the given `backStackEntry` to the `backStack`.

Public constructors

TestNavigatorState

Added in 2.4.0

public TestNavigatorState(
    Context context,
    @NonNull CoroutineDispatcher coroutineDispatcher
)

Public methods

Added in 2.4.0

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

Create a new NavBackStackEntry from a given destination and arguments.

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`

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.

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`

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`

public void push(@NonNull NavBackStackEntry backStackEntry)

Adds the given backStackEntry to the backStack.

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.