CellRecordPulses<T extends Cell> extension

An extension that records every pulse emitted by a Cell, for assertion in tests.

CellRecordPulses is the binding's Pulse Journal Entry Point — the minimal way to capture the ordered sequence of pulses a cell produces without constructing a widget or hand-rolling a Cell.observe call. Where CellBuilder collapses history into a current value and CellListener routes pulses into side effects, this extension preserves the full sequence, so tests can assert on order, payloads, and error types.

Why it is used

  • Pulse-level assertions: some behaviors are only observable at the pulse level — the order of emissions, the number of emissions, or the distinction between a data pulse and an error pulse. A value-based widget (CellBuilder) or a side-effect widget (CellListener) does not expose that.
  • Any Cell, including derived ones: Cell.state returns a ValueCell with a synchronous .value; a Cell.derive, Cell.synthesis, or Cell.asyncMap is a plain Cell without one. recordPulses works uniformly on all of them, which makes it the most reliable way to test derived-cell behavior.
  • Tissue collections: cell_tissue collections are Cell subtypes; the same recorder works on them, giving test code a single uniform observation idiom across the reactive types.

How it works

  1. recordPulses constructs a PulseRecorder, which opens exactly one Cell.observe link on the source cell.
  2. The egress effect appends every received pulse — data, error, or otherwise — to the recorder's in-order list.
  3. The recorder exposes two read views: PulseRecorder.pulses (the raw pulse list) and PulseRecorder.payloads (the payload-only list).
  4. PulseRecorder.stop releases the egress; PulseRecorder.clear resets the recorded list without releasing it.

Error pulses (please read)

Every pulse is recorded regardless of type — the recorder does not filter errors. Today in the core package, Cell.fromFuture is the only operator that emits type == 'error' pulses; Cell.fromStream and Cell.asyncMap do not emit error pulses at present. A recorder over those sources will therefore not observe failures through PulseRecorder.pulses or PulseRecorder.payloads. The per-source behavior is asserted in test/error_pulse_sources_test.dart, which is the authoritative statement every other doc in this package references.

When an error pulse is emitted, its payload is the underlying error object (Object), not a V. Use PulseRecorder.pulses when the test needs to distinguish type == 'error'; use PulseRecorder.payloads when the test only cares about the payload sequence and errors are not expected.

Cleanup (read this)

Always release the recorder. A PulseRecorder holds a strong reference to the source cell until PulseRecorder.stop is called, so a recorder left running pins its source for the lifetime of the isolate. Two safe patterns:

  • addTearDown(recorder.stop) for standalone use.
  • Let CellTestHarness manage it — the harness calls stop on dispose.

Technical Details

  • Generic over Cell subtype: T extends Cell preserves the source's static type for callers who want it (PulseRecorder<ValueCell<int>>).
  • One egress per recorder: each call to recordPulses opens a new observation link. Two recorders on the same source are two egresses.
  • Ordered, unfiltered: pulses are appended in emission order; the list is not coalesced, sorted, or deduplicated.

Example

testWidgets('emits on each update', (tester) async {
  final counter = Cell.state<int>(initial: 0);
  final recorder = counter.cell.recordPulses();
  addTearDown(recorder.stop);

  counter.update(1);
  counter.update(2);
  counter.update(3);

  expect(recorder.payloads, [1, 2, 3]);
});

See Also:

  • PulseRecorder — the recorder this extension constructs.
  • CellTestHarness — a higher-level test harness that manages recorder lifetime automatically.
  • Cell.observe — the underlying observation primitive.
  • CellAsyncBuilder — for rendering error pulses in a widget context.
  • test/error_pulse_sources_test.dart — the authoritative statement of which sources emit error pulses.
on
  • T

Methods

recordPulses() → PulseRecorder<T>

Available on T, provided by the CellRecordPulses extension

Records every pulse emitted by this cell.