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 Scaffold and Navigator, which many widgets assume (dialogs, snackbars, Theme.of). The default wrapper supplies them.
  • Overridable wrapper: tests that need a GlobalKey navigator, a specific theme, or a MaterialApp.router can pass wrapper and get the same cell registration.

How it works

  1. The child is wrapped — by wrapper if supplied, otherwise by a default MaterialApp(home: Scaffold(body: child)).
  2. The wrapped tree is placed inside a CellScope holding cells.
  3. WidgetTester.pumpWidget is called once and the returned Future is forwarded, so the caller can await tester.pumpWithCells(...) exactly as they would await 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 with pumpWidget.
  • 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:

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

Pumps child inside a CellScope pre-populated with cells.