CellPumpCell extension
An extension on WidgetTester that pumps a bare CellBuilder over a
ValueCell.
CellPumpCell is the binding's Single-Cell Test Harness. It is the
smallest possible test-tree for a CellBuilder-driven widget: a
MaterialApp wrapper for Text-based children that need an ambient
TextStyle, a Scaffold body slot to satisfy widgets that expect one,
and the CellBuilder itself. Nothing else — no CellScope, no
navigation, no theme override.
Why it is used
- Zero-boilerplate rendering: most widget tests only need to render one cell through one builder and assert on the resulting text or widget. This extension expresses that in a single call.
- Material-ambient defaults: a bare
pumpWidget(CellBuilder(...))lacks theMaterialApp+Scaffoldcontext thatText,Icon,Material, and theme-dependent widgets rely on. This extension supplies exactly that frame. - A clean failure mode: because no CellScope is installed, a widget under test that calls CellScope.of will fail loudly (its assertion fires) instead of silently resolving against an unintended scope. Tests that do need scoped lookups should use CellPumpWithCells.pumpWithCells instead — the two are deliberately distinct.
How it works
- The provided
builderis wrapped in aCellBuilder<V>bound tocell. - The
CellBuilderis placed in aScaffoldbody, which is itself wrapped in aMaterialApp. - WidgetTester.pumpWidget is called once and the returned Future
is forwarded, so callers can
await tester.pumpCell(...)exactly as they wouldawait tester.pumpWidget(...).
Design Note: why no CellScope
Installing a CellScope here would be a convenience for the minority
of tests that need scoped lookups, but a hazard for the majority that
don't: a widget that should be resolving its own cell via a
constructor argument would silently resolve against the ambient scope
instead, and the test would pass for the wrong reason. The absence is
intentional — tests that need a scope opt in by calling
pumpWithCells explicitly.
Return value
The Future returned by WidgetTester.pumpWidget. Resolves once the
first frame has been built. Widgets whose first visible state depends
on a post-frame or async completion need an additional
await tester.pump(...) — same as with pumpWidget.
Hooks and richer widget types
This extension renders exactly one CellBuilder. When the widget
under test is not a plain CellBuilder — a hook-based widget
(from flutter_hooks, or a Mitosis hooks layer if one is present), a
StatefulWidget in a non-Material frame, or a widget that needs a
Navigator — build the frame directly:
await tester.pumpWidget(
MaterialApp(home: Scaffold(body: HookBuilder(...))),
);
Any such widget composes fine inside that frame; the frame this extension supplies is exactly the one to reproduce.
Technical Details
- Single pump: this extension pumps once. Additional
pumps are the caller's responsibility, as with anypumpWidget-based helper. - Requires a ValueCell:
CellBuildertakesValueCell<V>, so this extension does too. Plain-cell sources (Cell.derive,Cell.synthesis,Cell.asyncMap) must be mirrored viaasValueCellor rendered with aCellValueBuilderunder a hand-builtpumpWidgetframe. - Stateless extension: it registers no teardown. Any recorders or
cell invalidation the test needs must be registered separately (see
e.g. CellRecordPulses.recordPulses and
addTearDown).
Example
testWidgets('displays cell value', (tester) async {
final counter = Cell.state<int>(initial: 0);
await tester.pumpCell(
cell: counter.cell,
builder: (_, v) => Text('value: $v'),
);
expect(find.text('value: 0'), findsOneWidget);
});
See Also:
- CellPumpWithCells.pumpWithCells — the CellScope-installing variant for tests that need scoped cell lookups.
CellBuilder— the widget this extension pumps.- WidgetTester.pumpWidget — the Flutter primitive this wraps.
- CellRecordPulses.recordPulses — a companion test helper for asserting pulse sequences.
- on
Methods
-
pumpCell<
V> ({required ValueCell< V> cell, required Widget builder(BuildContext context, V? value)}) → Future<void> -
Available on WidgetTester, provided by the CellPumpCell extension
Pumps a bareCellBuilderovercellinside a defaultMaterialApp+Scaffoldframe.