🏠 Overview › ✅ Implementation Tasks ›✅ epic-navigation-and-gesture-accessibility-foundation-task-007

Write integration tests for GoRouter route configuration

epic-navigation-and-gesture-accessibility-foundation-task-007 — Write integration tests verifying that: all five StatefulShellRoute branches are reachable by name, PopScope is active and swipe-back is suppressed on each branch, route metadata lookup returns correct labels and flags for each declared route, and navigation between branches does not lose the previously active sub-route.

high priority medium complexity testing pending testing specialist Tier 3

Acceptance Criteria

Test file `test/navigation/navigation_route_config_integration_test.dart` exists and all tests pass with `flutter test`
Test: navigating to each of the five tab root paths places the correct screen widget in the tree
Test: `PopScope` is present in the widget tree for every branch — found via `find.byType(PopScope)` — with `canPop == false`
Test: `Navigator.maybePop(context)` returns `false` when called on the root of any branch (swipe suppression verified programmatically)
Test: switching from Home tab to Contacts tab and back to Home preserves any previously pushed sub-route on the Home branch
Test: `routeMetadataFor` returns the correct `semanticsLabel` and `suppressSwipeBack: true` for each of the five tab roots
Test: deep-link path `/work/task/1` activates the Work tab and renders the task detail screen
All tests are hermetic — no network calls, no Supabase client initialized — using mock providers
Tests run in under 30 seconds in CI (no `flutter drive` / device required — use `flutter test` with `WidgetTester`)
Test results are deterministic — no flakiness due to animation timers (use `pumpAndSettle` with timeout or `pump` with explicit durations)

Technical Requirements

frameworks
Flutter
flutter_test
GoRouter test utilities
Riverpod (ProviderContainer for override)
data models
RouteMetadata
RouteConstants
performance requirements
Each test case completes in under 5 seconds
No real async I/O — all Supabase and auth providers overridden with fakes
security requirements
No real credentials or API keys in test setup — use fake auth provider returning a mock user
ui components
MockNavigationShell (minimal stub for StatefulShellRoute shell widget)
Fake tab screen widgets for each branch to avoid pulling in full feature dependencies

Execution Context

Execution Tier
Tier 3

Tier 3 - 413 tasks

Can start after Tier 2 completes

Implementation Notes

The most complex test is state preservation across tab switches. Use `StatefulShellRoute`'s `navigatorKey` per branch to access each branch's `Navigator` state independently. To test `PopScope`, find the `PopScope` widget via `tester.widget(find.byType(PopScope).first)` and assert `canPop == false`. For swipe-back simulation, dispatch a `BackButtonEvent` via `HardwareKeyboard` or call `Navigator.maybePop` and await the future — assert it returns `false`.

Avoid testing internal GoRouter state; test only observable widget tree outcomes. Use `addTearDown(router.dispose)` in each test to prevent router state leaking between tests. Consider a shared `buildTestApp(GoRouter router)` helper that wraps `ProviderScope` + `MaterialApp.router` to reduce boilerplate across test cases.

Testing Requirements

Use `flutter_test` exclusively — no `integration_test` package required (avoids needing a connected device). Structure tests in a `group('NavigationRouteConfig', ...)` block with sub-groups per concern: `group('branch reachability', ...)`, `group('PopScope suppression', ...)`, `group('state preservation', ...)`, `group('route metadata', ...)`. Use `ProviderScope` with `overrides` to inject fake auth and repository providers. Use `GoRouter`'s `WidgetsApp` or `MaterialApp.router` in test pump.

For the state preservation test: push a detail route on branch 0, call `shellNavigator.goBranch(1)`, then `shellNavigator.goBranch(0)`, assert original sub-route widget is still in the tree. Minimum: 10 distinct test cases covering all stated acceptance criteria.

Component
Navigation Route Configuration
infrastructure medium
Dependencies (1)
Annotate every route declaration in NavigationRouteConfig with its RouteMetadata: semanticsLabel for screen-reader announcement on navigation, suppressSwipeBack=true for all routes, and a semanticsIdentifier used by the accessibility audit runner. Ensure metadata is accessible at runtime via a routeMetadataFor(location) lookup function so the NavigationAccessibilityService can read it without coupling to GoRouter internals. epic-navigation-and-gesture-accessibility-foundation-task-006
Epic Risks (2)
high impact medium prob technical

StatefulShellRoute branch navigator state can interact unexpectedly with GoRouter's imperative navigation (go, push, replace), causing state snapshots to desync from actual route stacks. This could manifest as a user returning to a tab and seeing a different screen than expected, breaking the core motor-fatigue promise.

Mitigation & Contingency

Mitigation: Write integration tests that simulate cross-tab navigation with nested pushes before any UI layer is built. Pin go_router to a tested minor version and review the StatefulShellRoute changelog before upgrading.

Contingency: If branch navigator state consistently desyncs, fall back to a manual stack snapshot strategy using a custom NavigatorObserver that records and replays navigation events independently of StatefulShellRoute internals.

medium impact medium prob technical

Persisted navigation stacks in shared_preferences can become stale or corrupt if route paths are renamed during development, causing app crashes or infinite redirect loops on cold start for users who have an old snapshot.

Mitigation & Contingency

Mitigation: Version the persisted schema with a format key. On app start, validate that all stored route paths exist in the current route config before restoring; silently discard invalid entries rather than crashing.

Contingency: Implement a safe-mode cold start that skips state restoration after a detected crash (via a dirty-launch flag written at startup and cleared on successful first frame), falling back to the default root tab.

Quick Links
All Tasks Execution Plan