expectCellGolden<V> method

Future<void> expectCellGolden<V>({
  1. required ValueCell<V> cell,
  2. required Widget builder(
    1. BuildContext context,
    2. V? value
    ),
  3. String? name,
  4. Map<Symbol, Cell> cells = const {},
  5. String? goldenPath,
})

Captures a golden of a CellBuilder over cell at the cell's current value.

Pumps the widget inside MaterialApp(home: Scaffold(...)) — with a CellScope above it when cells is non-empty — then awaits matchesGoldenFile against the resolved path.

Parameters:

  • cell: The Captured Cell. Must be a ValueCell because CellBuilder requires a synchronous current value. Use asValueCell or CellValueBuilder for plain-Cell sources.
  • builder: The Render Callback. Same contract as CellBuilder.builder — receives V? and is called on every pulse. The golden is captured from whatever the builder renders at the time of the call.
  • name: The Golden Name. Used to build the default path 'goldens/$name.png'; ignored when goldenPath is supplied. Choose names that are stable across platforms and unambiguous within a test file.
  • cells: Optional Scope Registration. When non-empty, the widget is pumped inside a CellScope holding these cells, via CellPumpWithCells.pumpWithCells. When empty (the default), a bare pumpWidget is used — no CellScope is installed, matching CellPumpCell.pumpCell's behavior.
  • goldenPath: Optional Path Override. Replaces the default 'goldens/$name.png'. Use this for per-platform golden directories (goldens/ios/…) or for goldens that live outside the default path.

Exactly one of name / goldenPath must be supplied (asserted in debug builds; a null name with a null goldenPath is a caller bug).

Returns:

A Future that resolves once the golden comparison has completed. On mismatch, the Future completes with the standard matchesGoldenFile failure.

See Also:

  • CellExpectGolden — the extension-level docs, including the text-rendering limitation and golden-generation workflow.
  • CellPumpWithCells.pumpWithCells — the scoped pump path.
  • matchesGoldenFile — the underlying comparison primitive.

Implementation

Future<void> expectCellGolden<V>({
  required ValueCell<V> cell,
  required Widget Function(BuildContext context, V? value) builder,
  String? name,
  Map<Symbol, Cell> cells = const {},
  String? goldenPath,
}) async {
  assert(
    goldenPath != null || name != null,
    'expectCellGolden: provide either a name or a goldenPath.',
  );
  final path = goldenPath ?? 'goldens/${name!}.png';
  final widget = CellBuilder<V>(cell: cell, builder: builder);
  if (cells.isNotEmpty) {
    await pumpWithCells(
      cells: cells,
      wrapper: (child) => MaterialApp(home: Scaffold(body: child)),
      child: widget,
    );
  } else {
    await pumpWidget(
      MaterialApp(home: Scaffold(body: widget)),
    );
  }
  await expectLater(
    find.byType(MaterialApp),
    matchesGoldenFile(path),
  );
}