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.statereturns a ValueCell with a synchronous.value; aCell.derive,Cell.synthesis, orCell.asyncMapis a plainCellwithout one. recordPulses works uniformly on all of them, which makes it the most reliable way to test derived-cell behavior. - Tissue collections:
cell_tissuecollections areCellsubtypes; the same recorder works on them, giving test code a single uniform observation idiom across the reactive types.
How it works
- recordPulses constructs a PulseRecorder, which opens exactly
one
Cell.observelink on the source cell. - The egress effect appends every received pulse — data, error, or otherwise — to the recorder's in-order list.
- The recorder exposes two read views: PulseRecorder.pulses (the raw pulse list) and PulseRecorder.payloads (the payload-only list).
- 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
stopondispose.
Technical Details
- Generic over Cell subtype:
T extends Cellpreserves 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.