CellExpectGolden extension
An extension on WidgetTester that captures a golden image of a
CellBuilder over a ValueCell, at the cell's current value.
CellExpectGolden is the binding's Golden Capture Helper. It
assembles the same tree that CellPumpCell.pumpCell would — a
CellBuilder inside MaterialApp(home: Scaffold(...)) — pumps it,
then delegates to matchesGoldenFile to compare against a reference
image. In a single call it replaces the three-step
pumpWidget + pump + expectLater(..., matchesGoldenFile(...))
sequence that every cell-driven golden test would otherwise repeat.
Why it is used
- One call per snapshot: golden tests frequently capture several
snapshots of the same widget at different cell values. This helper
lets each snapshot be a single
await, keeping the test body readable and making the sequence of expected visual states obvious. - Correct ambient frame: a bare
CellBuilderlacks theMaterialApp+Scaffoldcontext thatTextstyling,Material, and theme-dependent widgets rely on. This helper supplies the same frame in every capture, so goldens are comparable across tests. - Optional scoped lookups: when the widget under test needs
CellScope-provided cells, pass
cellsand the helper routes the capture through CellPumpWithCells.pumpWithCells rather than a barepumpWidget.
How it works
- The
builderis wrapped in aCellBuilder<V>bound tocell. - If
cellsis non-empty, theCellBuilderis pumped inside a CellScope via CellPumpWithCells.pumpWithCells with the sameMaterialApp(home: Scaffold(...))wrapper. Otherwise a barepumpWidgetof the same wrapper is used. expectLater(find.byType(MaterialApp), matchesGoldenFile(...))is awaited against the file path resolved fromgoldenPathor the defaultgoldens/$name.png.
Design Note: capture the whole MaterialApp, not the Scaffold
The golden matcher targets find.byType(MaterialApp), not the
Scaffold inside it. That includes the app's ambient Material theme,
elevation, and any navigation bars or banner overlays that MaterialApp
contributes to the rendered pixels. Capturing the Scaffold alone would
omit that context, and two goldens generated under different ambient
themes would compare as if identical. The broader finder makes the
captured image a faithful record of what the user actually sees.
Design Note: every call starts from a fresh pump
Each expectCellGolden call builds and pumps a new tree — the
previous tree (and any frames pumped against it, e.g. by
emitAndSettle) is discarded. What matters for the capture is the
cell's value at the moment of the call; drive that with a direct
mutation (counter.update(5) or cell.value = 5), not by pumping the
tree that is about to be replaced.
Generating and updating goldens
Run the test suite with flutter test --update-goldens on the
reference platform to (re)generate baseline images. The reference
platform is typically macOS for iOS-shaped goldens; for cross-platform
precision, add per-platform overrides (e.g. goldens/ios/…,
goldens/android/…) at the call site via goldenPath.
Known limitation: text rendering
Flutter's default test font renders text as black boxes unless a
real-font loader has been installed for the suite. This helper does
not load fonts — that is a suite-level concern — so a test that
captures text-bearing widgets without loading fonts will produce
unreadable goldens. The recommended fix is a single setUpAll in the
test file (or a shared test harness) that calls loadAppFonts from
package:golden_toolkit:
setUpAll(() async {
await loadAppFonts(); // from package:golden_toolkit
});
golden_toolkit is a dev_dependency of the test suite, not of
cell_flutter. Application code that ships this binding does not need
it; only the binding's own golden tests (or an application's own golden
suite) do.
Technical Details
- Generic over ValueCell only:
CellBuildertakes a ValueCell, so this helper does too. Plain-cell sources (Cell.derive,Cell.synthesis,Cell.asyncMap) must be mirrored viaasValueCellor captured through a hand-built frame withCellValueBuilder. - Single pump: the helper performs the
pumpWidget; callers that need additional frames for post-frame or async completion mustawait tester.pump(...)before invoking this helper (or accept that the capture is of the pre-completion frame). - File path resolution:
goldenPathoverrides the default'goldens/$name.png'when supplied. Relative paths are resolved the same waymatchesGoldenFileresolves them — relative to the test file's directory. - Side effects: this method pumps and compares; it does not
subscribe, record, or otherwise mutate the cell. Any recorder the
test needs should be registered separately (see
CellRecordPulses.recordPulses and
addTearDown).
Example
testWidgets('counter golden', (tester) async {
final counter = Cell.state<int>(initial: 0);
await tester.expectCellGolden(
cell: counter.cell,
builder: (_, v) => Text('$v', style: const TextStyle(fontSize: 48)),
name: 'counter_zero',
);
// Drive the value directly. Each expectCellGolden call pumps a fresh
// tree; pumping the old tree in between (e.g. emitAndSettle) would
// only exercise a tree that the next call is about to replace.
counter.update(5);
await tester.expectCellGolden(
cell: counter.cell,
builder: (_, v) => Text('$v', style: const TextStyle(fontSize: 48)),
name: 'counter_five',
);
});
See Also:
- CellPumpCell.pumpCell — the non-golden equivalent for a single cell, no scope.
- CellPumpWithCells.pumpWithCells — the scoped variant this helper
delegates to when
cellsis non-empty. matchesGoldenFile— the Flutter primitive this helper invokes.- CellRecordPulses.recordPulses — a companion test helper for asserting pulse sequences.
- on
Methods
-
expectCellGolden<
V> ({required ValueCell< V> cell, required Widget builder(BuildContext context, V? value), String? name, Map<Symbol, Cell> cells = const {}, String? goldenPath}) → Future<void> -
Available on WidgetTester, provided by the CellExpectGolden extension
Captures a golden of aCellBuilderovercellat the cell's current value.