fespalier-testing
Testing an app built with fespalier — package:fespalier/testing.dart (pumpRouter and currentLocation), booting the generated router at any location, deep links, typed navigation, not-found views and u
SKILL.mdskills/fespalier-testing/SKILL.md
GitHubfespalier-testing
Verified against fespalier
589cf391(2026-10-08), release v0.13.0. These skills ship in the fespalier repository, and CI checks them against its code on every change. Version-sensitive claims say the release they became true in; if your app pins another fespalier, trust that release's code over this page. See Versions.
package:fespalier/testing.dart has pumpRouter and currentLocation, motionOf and pumpTransition (since 0.19.0), and, around them, sendPlatformLink(tester, Uri) (since 0.12.0: a warm platform link, as the engine sends it, pumped until idle; see the platform links section of the fespalier-routing skill), RecordingTelemetry, TestRouteScope (since 0.11.0, for an observe.dart hook that takes a RouteScope) and the fsp test pieces smokeTestRoute and findRoutePage. It is a separate library, so
package:fespalier/fespalier.dart never imports flutter_test; the package lists
flutter_test (an SDK package) as a dependency, which your app already has as a dev
dependency.
import 'package:fespalier/testing.dart';
testWidgets('shows a product', (tester) async {
final container = await pumpRouter(
tester,
AppRoutes.router(initialLocation: '/products/2'),
overrides: [apiProvider.overrideWithValue(FakeApi())],
);
expect(find.byType(ProductPage), findsOneWidget);
expect(currentLocation(tester), '/products/2');
// navigate with typed routes from any widget under the router
ProductsRoute().go(tester.element(find.byType(ProductPage)));
await tester.pumpAndSettle();
expect(currentLocation(tester), '/products');
});
- Signed-in routes (since 0.9.0). With
package:fespalier_auth,overrides: fakeAuth(signedInAs: ...)(frompackage:fespalier_auth/testing.dart) signs a test in, or out with no argument, on aFakeAuthBackendand aMemoryTokenStore: nostartup(), no network, no timer. Call it inside the test body, where the fake clock starts;tokenLifetime:plustester.pump(const Duration(minutes: 6))ages the session. See "Signed-in routes" inreferences/recipes.md. - Flagged routes (since 0.9.0). With
package:fespalier_flags,overrides: [flagSource.overrideWithValue(FakeFlags({'labs': true}))](frompackage:fespalier_flags/testing.dart) turns a flag on for apumpRoutertest;flags.set('labs', false)thenawait tester.pump()takes the app off the flagged route.FakeFlags.strictfails a test on a key typo. Seereferences/recipes.mdandfespalier-guards(its feature-flags page). - A cache on disk (since 0.9.0). With
package:fespalier_storage,setUp(fakePrefsStore)(frompackage:fespalier_storage/testing.dart) makes shared_preferences an in-memory store, twoPrefsDataStorage.open()s in one test are a restart, andmemoryBox()is a Hive box in memory. WithoutfakePrefsStore(),open()isnulland nothing is saved. Seereferences/recipes.mdandfespalier-data(its storage page). - Reconnects and offline banners (since 0.9.0). With
package:fespalier_connectivity,connectivitySource.overrideWithValue(FakeConnectivity())(frompackage:fespalier_connectivity/testing.dart) inpumpRouter's overrides;fake.offline()thenfake.online()is a reconnect. A widget test that reaches the plugin fails (while activating platform stream on channel dev.fluttercommunity.plus/connectivity_status). Seereferences/recipes.mdandfespalier-data. - Translated routes (since 0.10.0). With
package:fespalier_tolgee,overrides: fakeTranslations(bundled: {...}, remote: FakeTranslations.strict())(frompackage:fespalier_tolgee/testing.dart) andapp: (router) => App(router: router):pumpRouter's default app has noTranslationScope, socontext.trthrows there.FakeTranslations.strict()fails the test on a key nobody has; a fetch lands on the nextpump. Seefespalier-i18n(itstesting.mdpage). - Offline and queued writes (since 0.10.0). With
package:fespalier_cratestack,crateStackTestOverrides(transport: FakeCrateStackTransport()..on('op', ...))(frompackage:fespalier_cratestack/testing.dart):transport.offline = truequeues an intent, thendrain()sends it once;loseAnswer('op')replays under the same key without running twice;ManualSyncTicker.tick()is the app's tick andFakeRowServeris the row server. The fakes are allFuture.values: a pending timer is your own ticker. Seefespalier-offline(itstesting.mdpage). - DPoP proofs (since 0.9.0). With
package:fespalier_sign_keypair,FakeDpopSigner(frompackage:fespalier_sign_keypair/testing.dart) is a software key from a fixed scalar (the same on every run, no platform), andverifyDpopProofis what a fake server checks every proof with. See "DPoP proofs" inreferences/recipes.md. - Window size (since 0.9.0). With
package:fespalier_adaptive, Flutter's default 800 x 600 test window is a rail; settester.view.physicalSize(anddevicePixelRatio = 1, andaddTearDown(tester.view.reset)) for a bar (under 600) or a drawer (1200 and up). See "An adaptive layout" inreferences/recipes.md. - HTTP without a network (since 0.9.0). With
package:fespalier_dioorpackage:fespalier_http(thepackage:httphalf, since 0.15.0;FakeHttpClientandFakeHttpCredentialsare inpackage:fespalier_http/testing.dart), a fakeHttpClientAdapterunder Dio and aMockClientunderpackage:httpanswer with no network. Dio's chain starts withTimer.run: use a plaintest(),pumpAndSettle(), orpump(Duration.zero)(a barepump()does not run it). AMockClientdoes not abort by itself: its handler racesabortTrigger. Give the retriers zero delays, and count what the adapter saw: a write must be sent once. Seereferences/http.md. - Hooks and telemetry (since 0.8.1). An
observe.darthook fires at the end of the first frame that shows a change, soawait tester.pump()before asserting what it did;RecordingTelemetryis aFespalierTelemetrythat keeps lines for a test (FespalierTelemetry.installinsetUp,install(null)intearDown). Both are infespalier-observability. pumpRouter(tester, router, {overrides, container, settle, retry, disposeRouter, app})wraps the router in aProviderScopeand Flutter'sMaterialApp.router, pumps, and returns theProviderContainer(forcontainer.read(...)).settle(default on) pumps until nothing is scheduled; turn it off to look at a loading view, thenpumpthe time you want.- Pass your own
containerinstead ofoverridesto share one with code outside the tree (it is yours to dispose); passing both is an assertion. retrydefaults to no retries: a failingdata.dartshowserror.dartat once and leaves no timer. PassProviderContainer.defaultRetry(or your function) to test the app's policy.- It disposes the router when the test ends (since 0.5.0; on 0.4.x and earlier
LeakTestingreported theGoRouterDelegateas not disposed). A test that keeps its ownaddTearDown(router.dispose)before the call passesdisposeRouter: false(since 0.6.0): those teardowns run afterpumpRouter's, and a seconddisposethrows. Build one router per test. app:(since 0.8.1) is aWidget Function(GoRouter router)that builds what goes around the router in place of the plainMaterialApp.router. With the generatedmain()(thefespalierskill'sapp-mainpage) passapp: AppMain.app: a page is then tested inlib/app/app.dart's theme, localizations andbuilder:.startup()does not run inpumpRouter: pass what it would override asoverrides. To boot all of it, pumpAppMain.root()yourself (await tester.pumpWidget(AppMain.root(router: () => AppRoutes.router(initialLocation: '/x'))), thenpumpAndSettle; astartup()that awaits real I/O needstester.runAsync). The router is disposed with the tree. Astartup()that throws is reported toFlutterError.onError, which fails the test untiltester.takeException()takes it; then the splash witherrorandretryis on screen.AppMain.run()can be awaited in a test to check azone(); pump afterwards.- Deferred routes (since 0.7.0). A route with
const deferred = true;has itspage.dartimporteddeferred as, whoseloadLibrary()completes only on the real event loop, which a widget test'spumpnever runs.pumpRoutertherefore loads every deferred route's code first, inrunAsync, and the page is in the first settled frame like an eager one's. A test that pumps a router of its own (MaterialApp.routerinpumpWidget) must do it itself, before:await tester.runAsync(AppRoutes.loadDeferred);. Forget it, and a debug build throws aFlutterErrorthat says so (pitfalls.md) instead of hanging. The loading view of a real deferred page can't be seen in a widget test: useDeferredLibrary(() => completer.future, 'x/page.dart', loadsInFakeAsync: true)in aDeferredView. - Guards: return synchronously when you can. Any
Future, evenFuture.value(...), costs a frame, so a cold deep link shows a blank first frame before the page.
motionOf(tester, {of})(since 0.19.0) is thePageMotion(fade,slide,none,material,cupertino,dialog,sheet,fullscreenDialog,custom,sharedAxis,fadeThrough) the root navigator's top page was tagged with byTransitions.*, or null for a page of the app's own.of:is a finder for a widget on the page you mean (a page inside a tab).pumpTransition(tester, {at = 1, of})(since 0.19.0) runs the transition a navigation just started: one pump, thenattimes the route's duration (its reverse duration while popping, and a popping route is no longer the top, so passof:for the leaving page).at: 1ends it (one millisecond past, where the controller sayscompleted),at: 0.5leaves it animating for a mid-flight assertion. Call it right afterrouter.go(...), once per transition; nopumpAndSettle. A page inside a layout or a tab needsof:(the root navigator's top route is the layout's, already complete: a debug assertion says so); anof:that finds no widget, or several, is aStateError.currentLocation(tester)is where the router is, as a string (/products/2?tab=info). It followsgo,popand, since 0.4.0,push(the pushed location, the top of the stack). On 0.3.0 and earlier it did not follow apush: there, readrouter.routerDelegate.currentConfiguration.last.matchedLocation.- The DevTools hooks run in widget tests (a test is a debug build; since 0.7.0):
AppRoutes.router()attaches its router to the extension's support, which adds one listener and a short history, and the generated guards,data.dartproviders and actions report to it (traceGuard,traceData, an action'ssite). They return what they are given, so a sync guard stays sync and aFutureis the sameFuture; the only additions are anonDisposecallback per provider build and a sidethenthat records how aFutureended. It starts no timer, schedules no frame, reads no provider and listens to no stream, so it cannot leave a timer pending or change apumpAndSettle; run the tests with--dart-define=fespalier.devtools=falseto compile it out. - One router per test: a router remembers where it went. Build it in the test
(
AppRoutes.router(initialLocation: ...)), not in a sharedfinal. - Boot once per test when fakes use
Future.delayed: a second boot leaves the first tree's timers behind (A Timer is still pending even after the widget tree was disposed). Aforloop that declares onetestWidgetsper location is the easy way. - Import files from
$folders with the dollar escaped:import 'package:my_app/app/products/\$id/page.dart';.
What to test, and how
| You want to check | Do |
|---|---|
| A URL opens its page | pumpRouter(..., AppRoutes.router(initialLocation: '/products/2')), find.byType(ProductPage) |
| Not found | /nope or an unparsable segment (/products/abc): the page is never built, guards that read segments are skipped |
| Loading, then data | settle: false, await tester.pump(), find.byType(ProductLoading), then pump(delay) |
| An error view | a fake that throws: error.dart shows at once (no retries in pumpRouter) |
| A backend fake | override the provider your data() reads: overrides: [apiProvider.overrideWithValue(FakeApi())] |
| Typed navigation | ProductRoute(id: 1).go(tester.element(find.byType(ProductsPage))), then pumpAndSettle |
| A guard | c.read(session.notifier).signIn() through the returned container, then navigate (or pumpAndSettle: a Ref guard that watches moves by itself) |
A signed-in route (0.9.0, fespalier_auth) |
overrides: fakeAuth(signedInAs: const AuthUser(id: 'ada')); signed out: fakeAuth(), and the route lands on /sign-in?from=... |
HTTP or a retry (0.9.0, fespalier_dio, fespalier_http) |
a fake HttpClientAdapter or MockClient, no network; count what it saw, zero delays for retriers (references/http.md) |
A flagged route (0.9.0, fespalier_flags) |
overrides: [flagSource.overrideWithValue(FakeFlags({'labs': true}))]; flags.set('labs', false), then pump(): the app leaves it |
| A restart over a disk cache (0.9.0) | setUp(fakePrefsStore), then two PrefsDataStorage.open()s; the 2nd pumpRouter(settle: false) shows the saved value |
| A reconnect or an offline banner (0.9.0) | connectivitySource.overrideWithValue(FakeConnectivity()); fake.offline() then fake.online(), then pump() |
A translated route (0.10.0, fespalier_tolgee) |
overrides: fakeTranslations(bundled: ..., remote: FakeTranslations.strict()) and app: (router) => App(router: router); see fespalier-i18n |
A queued write or a sync (0.10.0, fespalier_cratestack) |
crateStackTestOverrides(transport: fake); fake.offline = true, then drain(); ManualSyncTicker.tick(); see fespalier-offline |
A network image (0.9.0, fespalier_image) |
overrides: [imageCdnProvider.overrideWithValue(fakes.cdn(yourCdn))] with FakeImages(image: image); fakes.requested is every URL asked for; see recipes.md |
Sentry events and breadcrumbs (0.9.0, fespalier_sentry) |
RecordingSentry() and FespalierTelemetry.install(FespalierSentry(hub: sentry.hub)); await tester.pump(), then sentry.lines(), sentry.sent(), sentry.breadcrumbs; see recipes.md |
| Locations, matches, data providers | plain test(): .location, locationFor, AppRoutes.dataAt(uri), AppRoutes.match(uri) |
A WidgetRef (prefetch, refresh) |
tester.element(find.byType(SomeConsumerWidget)) as WidgetRef |
| An action (a write, since 0.5.0) | container.read(XRoute.action(1).notifier).call(input); see fespalier-data |
| Restoration | your own app widget building the router in State, restartAndRestore() |
| Scroll restoration (0.8.1) | play the browser with pushRouteInformation and the state the app reported; a location alone starts at the top (pitfalls.md) |
| A deferred route (0.7.0) | pumpRouter loads it; with your own router, await tester.runAsync(AppRoutes.loadDeferred) before pumpWidget (pitfalls.md) |
| Aging data, a resume, a reconnect, a cache (0.8.1) | pump(Duration) ages by the fake clock; handleAppLifecycleStateChanged; reconnectSignal.notifier.fire(); a shared MemoryDataStorage (pitfalls.md) |
A RouteLink hover (0.5.0) |
a mouse createGesture, moveTo, pump; container.exists(XRoute.data(...)) (pitfalls.md) |
Full compiled tests for all of these are in
references/recipes.md; the traps, each of which cost a test
run while these skills were written, are in
references/pitfalls.md.
Widget tests for logic and states; Maestro for real devices, the web and journeys across
routes. Maestro reads the accessibility tree and cannot see a Key, so (since 0.7.0)
semantics_ids: true gives every page a Semantics(identifier: 'route:<pattern>') that is in the
tree only when the route's own page is built, and fsp maestro writes a smoke flow per route that
waits for it. The identifier contract, the test that proves it
(find.bySemanticsIdentifier, with the handle disposed in the test body) and the traps (hash URLs,
maestro test .maestro skipping routes/, the web reload under a guard flow, the semantics tree
staying on in a web build) are in references/maestro.md.
A smoke test per route, for free (since 0.8.1). fsp test writes
test/routes/routes_test.dart: one testWidgets per route that opens it at a sample URL with
pumpRouter and waits, on the fake clock, until its page is on screen. Provider overrides and the app
around the router come from a setup.dart you own. package:fespalier/testing.dart has the pieces:
smokeTestRoute, findRoutePage(pattern), pumpRouter(app:) and an Override export. The setup file, the
skips, the failure message and the traps are in
references/route-smoke-tests.md.
test: a11y: true (since 0.16.0) also has each of those tests check Flutter's accessibility guidelines (tap
targets, semantic labels, text contrast) once the page is on screen: smokeTestRoute(guidelines: routeA11yGuidelines). It checks the whole screen, so an unlabeled IconButton in the shared app bar fails every
route; the same page has the list form and the failures.
To watch a running app rather than assert on it (since 0.8.1), fsp telemetry starts OpenObserve (and
Grafana with --grafana) in Docker with four dashboards over fespalier's spans, written as questions (App
health, Screens, Actions, Errors; green, amber or red), and fsp telemetry --report prints the same answers in
the terminal. The command, the
endpoint an app on an emulator, a simulator, a phone or the web uses, which dashboard answers which
question, and the traps (empty dashboards, otel_zone's runGuarded blanking a web app before v0.8.1) are in
references/observability.md.
Examples
examples/minimal, examples/shop, examples/features, examples/auth, examples/telemetry, examples/adopt, examples/cose, examples/i18n,
examples/maps and examples/offline test their routes with pumpRouter from package:fespalier/testing.dart; examples/plugins pumps
AppMain.root() (and uses pumpRouter in its push test), and examples/tabs builds its own MaterialApp.router. examples/shop also carries what fsp test and
fsp maestro write (test/routes/, .maestro/routes/);
the fespalier skill lists every example.
Three facts to keep in mind
- go_router builds the whole matched stack: a deep link to
/products/2also runs/products'data.dartunderneath; pump long enough for both orpumpAndSettle. fsp checkdoes not catch a stalelib/app.g.dart: it writes and compares nothing. Regenerate and diff in CI (dart run fespalier gen, thengit diff --exit-code lib/app.g.dart).await ProductRoute.read(ref, id: 1)under a fake clock hangs until youpumpthe delay: start it, pump, then await.
Other skills: fespalier-data for what the data providers do,
fespalier-guards for the guard behaviours you will be testing.