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. emitAndSettle combines the mutation with the pumping required to see it.
  • Timer-aware: pumpAndSettle drains 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: emitAndPump lets 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 a setState (as in every CellBuilder) will end with the tree settled.
  • emitAndPump assigns cell.value = value, then awaits exactly one WidgetTester.pump — or one WidgetTester.pump with duration when 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.value synchronously, which is a ValueCell capability. Plain Cell sources (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 — pumpAndSettle collapses 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:

on

Methods

emitAndPump<V>(ValueCell<V> cell, V? value, {Duration? duration}) → Future<void>

Available on WidgetTester, provided by the CellEmitAndSettle extension

Sets cell's value and pumps a single frame (or duration, if provided). Does not wait for settle.
emitAndSettle<V>(ValueCell<V> cell, V? value) → Future<void>

Available on WidgetTester, provided by the CellEmitAndSettle extension

Sets cell's value to value, then pumps until the widget tree settles.