Skip to content

Commit b16aef1

Browse files
[go_router] Clarify onEnter/redirect ordering, add regression test (#12337)
## What this does Clarifies the `onEnter` doc comment on `RoutingConfig` to explicitly warn that `onEnter` is evaluated once, against the literal navigated-to URI, and is never re-invoked for locations reached only through a `redirect:` chain. Adds a regression test locking in this behavior for the exact scenario reported in flutter/flutter#188014, plus a second test demonstrating the correct workaround (putting the guard inside `redirect:` instead of `onEnter`). ## Why flutter/flutter#188014 reports what looks like a bug: an `onEnter` guard checking for an intermediate redirect target (`/a`, reached via a `redirect:` on `/`) never fires. Tracing the pipeline shows this is actually intended, existing behavior — see the `'onEnter called once when top-level redirect chains'` test (written for the related #178984), which asserts the same ordering. The docs didn't make this ordering/visibility gap explicit though, so it's an easy trap. This PR closes that documentation gap and adds test coverage so the behavior can't silently change without a test failing. ## Related Fixes flutter/flutter#188014 (as a documentation clarification, not a behavior change — see discussion on the issue). ## Pre-Review Checklist > [!IMPORTANT] > This PR was prepared with assistance from an AI agent (Claude). The > code, doc comment, and tests have been reviewed by the author, who > understands the change and takes responsibility for it. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent fd8d150 commit b16aef1

3 files changed

Lines changed: 81 additions & 0 deletions

File tree

‎packages/go_router/lib/src/router.dart‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,21 @@ class RoutingConfig {
9898
/// When a deep link opens the app and `onEnter` returns [Block], GoRouter
9999
/// will stay on the current route or redirect to the initial route.
100100
///
101+
/// [onEnter] is evaluated exactly once per navigation, against the literal
102+
/// URI being navigated to. It runs strictly before both the legacy top-level
103+
/// [redirect] and any [GoRoute.redirect] chains, and is not re-invoked as
104+
/// those redirects resolve intermediate locations. This means `next.uri.path`
105+
/// will never equal a path that is only reached through a redirect callback.
106+
///
107+
/// For example, given a route at `/` that redirects to `/a`, an [onEnter] guard
108+
/// checking if `next` equals `/a` will never match when navigating to `/`,
109+
/// because `next` reflects the pre-redirect target (`/`). If you need to guard
110+
/// a location that only exists as a redirect destination, put that check inside
111+
/// a `redirect` callback instead (top-level or route-level) -- `redirect`
112+
/// callbacks see each resolved hop in the chain as they produce it. Reserve
113+
/// [onEnter] for guarding the literal, user- or app-initiated navigation
114+
/// target (deep links, [GoRouter.go] or [GoRouter.push] calls, etc.).
115+
///
101116
/// Example:
102117
/// ```dart
103118
/// final GoRouter router = GoRouter(
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
changelog: Clarifies `onEnter` documentation regarding evaluation order relative to `redirect:` chains.
2+
version: patch

‎packages/go_router/test/on_enter_test.dart‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1880,6 +1880,70 @@ void main() {
18801880
// onEnter blocked before redirects were evaluated.
18811881
expect(redirectCallCount, redirectCountAfterInit);
18821882
});
1883+
1884+
testWidgets('onEnter cannot guard a location only reachable via redirect:', (
1885+
WidgetTester tester,
1886+
) async {
1887+
// Regression test for https://github.com/flutter/flutter/issues/188014
1888+
//
1889+
// onEnter cannot intercept a location that is only ever reached
1890+
// through a `redirect:` callback (route-level or top-level) -- it is
1891+
// evaluated once, against the literal navigated-to URI, strictly
1892+
// before redirects run. This is documented behavior (see the
1893+
// [RoutingConfig.onEnter] doc comment) and matches the existing
1894+
// 'onEnter called once when top-level redirect chains' test above,
1895+
// but is easy to trip over when onEnter itself tries to branch on an
1896+
// intermediate redirect target.
1897+
final seenNextPaths = <String>[];
1898+
router = GoRouter(
1899+
initialLocation: '/',
1900+
onEnter:
1901+
(
1902+
BuildContext context,
1903+
GoRouterState current,
1904+
GoRouterState next,
1905+
GoRouter goRouter,
1906+
) async {
1907+
seenNextPaths.add(next.uri.path);
1908+
if (next.uri.path == '/a') {
1909+
return Block.then(() => goRouter.go('/b'));
1910+
}
1911+
return const Allow();
1912+
},
1913+
routes: <RouteBase>[
1914+
GoRoute(path: '/', redirect: (_, _) => '/a'),
1915+
GoRoute(path: '/a', builder: (_, _) => const Text('A')),
1916+
GoRoute(path: '/b', builder: (_, _) => const Text('B')),
1917+
],
1918+
);
1919+
1920+
await tester.pumpWidget(MaterialApp.router(routerConfig: router));
1921+
await tester.pumpAndSettle();
1922+
1923+
expect(seenNextPaths, equals(<String>['/']));
1924+
expect(router.routerDelegate.currentConfiguration.uri.toString(), '/a');
1925+
expect(find.text('A'), findsOneWidget);
1926+
expect(find.text('B'), findsNothing);
1927+
});
1928+
1929+
testWidgets('workaround: guard the redirect target inside redirect: instead', (
1930+
WidgetTester tester,
1931+
) async {
1932+
router = GoRouter(
1933+
initialLocation: '/',
1934+
routes: <RouteBase>[
1935+
GoRoute(path: '/', redirect: (_, _) => '/a'),
1936+
GoRoute(path: '/a', redirect: (_, _) => '/b', builder: (_, _) => const Text('A')),
1937+
GoRoute(path: '/b', builder: (_, _) => const Text('B')),
1938+
],
1939+
);
1940+
1941+
await tester.pumpWidget(MaterialApp.router(routerConfig: router));
1942+
await tester.pumpAndSettle();
1943+
1944+
expect(router.routerDelegate.currentConfiguration.uri.toString(), '/b');
1945+
expect(find.text('B'), findsOneWidget);
1946+
});
18831947
});
18841948
});
18851949
}

0 commit comments

Comments
 (0)