CellPumpWithCells extension
An extension on WidgetTester that pumps a widget inside a CellScope.
CellPumpWithCells is the binding's Test Tree Seeder — a one-call
replacement for the pumpWidget(CellScope(cells: …, child: MaterialApp(…)))
boilerplate that every widget test using app-level cells would otherwise
repeat. It combines the two steps a test needs: registering the cells in
a CellScope above the widget under test, and pumping that tree with a
Material wrapper that provides Scaffold, Navigator, and the default
theme.
Why it is used
- Correct tree shape: any widget that calls CellScope.of /
CellScope.maybeOf / CellScope.valueOf requires a CellScope
ancestor. This extension guarantees one exists, above a default
MaterialApp+Scaffold, without each test spelling out the nesting. - Material defaults: a bare widget tree lacks a
ScaffoldandNavigator, which many widgets assume (dialogs, snackbars,Theme.of). The default wrapper supplies them. - Overridable wrapper: tests that need a
GlobalKeynavigator, a specific theme, or aMaterialApp.routercan passwrapperand get the same cell registration.
How it works
- The
childis wrapped — bywrapperif supplied, otherwise by a defaultMaterialApp(home: Scaffold(body: child)). - The wrapped tree is placed inside a CellScope holding
cells. - WidgetTester.pumpWidget is called once and the returned Future
is forwarded, so the caller can
await tester.pumpWithCells(...)exactly as they wouldawait tester.pumpWidget(...).
Design Note: why the CellScope sits outside the wrapper
The scope wraps the wrapper, not the other way around. That means a
custom wrapper — a MaterialApp with a navigatorKey, for instance —
is itself inside the CellScope, so widgets constructed by the wrapper
(route builders, splash-screen overlays) can also resolve cells. It also
matches how a production app is typically assembled: the app root that
installs global cells sits above the MaterialApp.
Return value
The Future returned by WidgetTester.pumpWidget. Resolves once the first frame has been built; call WidgetTester.pump afterward for subsequent frame-driven updates.
Technical Details
- Single pump: this extension pumps once. Widgets whose first
visible state depends on a post-frame or an async completion need an
additional
await tester.pump(...)— same as withpumpWidget. - Stateless extension: it adds no per-test state and no tear-down
hooks. Any recorders, subscriptions, or cell invalidation that the
test needs must be registered separately (see e.g.
CellRecordPulses.recordPulses and
addTearDown). - Wrapper signature is
Widget Function(Widget child): it receives the already-CellScope-free child (the scope is installed outside the wrapper) and returns the widget to pump.
Example: default wrapper
testWidgets('counter renders', (tester) async {
final counter = Cell.state<int>(initial: 42);
await tester.pumpWithCells(
cells: {#counter: counter.cell},
child: CellBuilder<int>(
cell: counter.cell,
builder: (_, v) => Text('$v'),
),
);
expect(find.text('42'), findsOneWidget);
});
Example: custom wrapper with a navigatorKey
final navKey = GlobalKey<NavigatorState>();
await tester.pumpWithCells(
cells: {#auth: auth.cell},
wrapper: (child) => MaterialApp(
navigatorKey: navKey,
home: child,
),
child: const LoginScreen(),
);
See Also:
- CellScope — the registry this extension installs above the widget.
- WidgetTester.pumpWidget — the Flutter primitive this wraps.
- CellRecordPulses.recordPulses — a companion test helper for asserting pulse sequences.
- CellTestHarness — a higher-level harness for tests that need cell lifecycle management alongside pumping.
- on
Methods
-
pumpWithCells(
{required Map< Symbol, Cell> cells, required Widget child, Widget wrapper(Widget child)?}) → Future<void> -
Available on WidgetTester, provided by the CellPumpWithCells extension
Pumpschildinside a CellScope pre-populated withcells.