CellEmitAndSettle extension
An extension on WidgetTester that drives a ValueCell through the widget tree and lets the frame pipeline catch up.
CellEmitAndSettle is the binding's Emission Driver — the companion to CellPumpCell.pumpCell and CellPumpWithCells.pumpWithCells. Where the pump helpers put a widget on screen with the cell's initial value, this extension triggers an update and pumps the frames needed for that update to render. The pair together forms the shortest possible widget-test cycle: pump → emit → assert.
Why it is used
- Deterministic widget tests: a
cell.value = ...mutation runs the pulse through the graph synchronously but does not, by itself, cause Flutter to render the resulting state.emitAndSettlecombines the mutation with the pumping required to see it. - Timer-aware:
pumpAndSettledrains the microtask queue between frames, so receptors that resolve on a microtask (the common case) work without further help. See Async receptor caveats below for the one case it does not cover. - Intermediate-state observation:
emitAndPumplets a test observe the tree before the widget has fully settled — useful for asserting a loading spinner before the results list appears.
How it works
- emitAndSettle assigns
cell.value = value, then awaits WidgetTester.pumpAndSettle. It keeps pumping frames while any are scheduled, so a cell whose update triggers asetState(as in everyCellBuilder) will end with the tree settled. - emitAndPump assigns
cell.value = value, then awaits exactly one WidgetTester.pump — or one WidgetTester.pump withdurationwhen supplied. It does not wait for the tree to settle; the caller controls how many frames to advance.
Async receptor caveats (read this)
pumpAndSettle does not wait for timers — only for scheduled frames
and microtasks. That leaves three cases to reason about:
| Receptor resolves… | emitAndSettle works? |
Fallback |
|---|---|---|
| synchronously | yes | — |
on a microtask (e.g. plain await) |
yes — microtasks drain between frames | — |
on a timer (Future.delayed, Timer) |
no — the timer has not fired yet | await tester.pump(duration) after, or emitAndPump(cell, value, duration: …) |
Use emitAndPump with an explicit emitAndPumpduration when the
pulse resolution depends on a timer, or to inspect an intermediate
frame.
Design Note: why this is not automatic
CellBuilder rebuilds through ValueListenableBuilder and CellNotifier,
not through setState on the widget's own state. That means Flutter
does schedule a frame on every pulse — but the frame only renders
after the test's event loop yields. A test that asserts immediately
after cell.value = value inspects the previous frame, which is the
most common widget-test failure mode with cells. This extension exists
to make the yield explicit and test-local, rather than hidden in a
waitFor-style loop.
Technical Details
- ValueCell only: both methods assign
cell.valuesynchronously, which is a ValueCell capability. PlainCellsources (Cell.derive,Cell.asyncMap) must be driven through their input cells, not asserted directly here. - Single assignment: each call assigns once. For a burst of updates,
call the extension multiple times or assign directly and
pump—pumpAndSettlecollapses all intermediate frames into the final rendered state, which is usually what tests want. - No assertions: these helpers mutate and pump; they do not check
anything. Pair with CellExpectValue.expectCellValue or the usual
expect(find.text(...), …)after settling.
Example
await tester.pumpCell(cell: counter.cell, builder: (_, v) => Text('$v'));
await tester.emitAndSettle(counter.cell, 5);
expect(find.text('5'), findsOneWidget);
See Also:
- CellPumpCell.pumpCell — the pump step that precedes emission.
- CellPumpWithCells.pumpWithCells — the scoped variant.
- CellExpectValue.expectCellValue — the assertion step that follows.
- WidgetTester.pumpAndSettle / WidgetTester.pump — the Flutter primitives these helpers wrap.
- on
Methods
-
emitAndPump<
V> (ValueCell< V> cell, V? value, {Duration? duration}) → Future<void> -
Available on WidgetTester, provided by the CellEmitAndSettle extension
Setscell's value and pumps a single frame (orduration, if provided). Does not wait for settle. -
emitAndSettle<
V> (ValueCell< V> cell, V? value) → Future<void> -
Available on WidgetTester, provided by the CellEmitAndSettle extension
Setscell's value tovalue, then pumps until the widget tree settles.