PulseRecorder<T extends Cell> class
A recorder that captures every pulse emitted by a Cell, in order.
PulseRecorder is the binding's Pulse Journal. It owns exactly one
Cell.observe link on a source cell and appends every received pulse
to an in-order list, so tests can assert on the sequence, payloads, and
error types of a cell's emissions without subscribing to the cell
themselves.
Why it is used
- Sequence assertions: the recorded list preserves order, so a test
can assert
expect(recorder.payloads, [1, 2, 3])on a burst of updates that a value-only view would collapse into the final value. - Error visibility: pulses exposes the raw pulse list, allowing
tests to distinguish data from
type == 'error'emissions — see the extension docs for which core operators currently emit errors. - Harness-integrated: CellTestHarness wraps one of these internally and manages its lifecycle, so most tests use the harness rather than the recorder directly.
How it works
- Construction: the private constructor (invoked via
CellRecordPulses.recordPulses) opens one
Cell.observelink on the source cell; the effect appends every pulse to an internal list. - Reading: pulses returns a snapshot copy of the list; payloads derives a payload-only view on demand.
- Reset: clear empties the recorded list without releasing the
egress — useful for
setUp-style isolation within a single test. - Release: stop releases the egress. Idempotent.
Cleanup (read this)
Always release the recorder. It holds a strong reference to the source cell until stop is called, so a recorder left running pins its source for the lifetime of the isolate. Two correct patterns:
addTearDown(recorder.stop)for standalone use.- Let CellTestHarness manage it — the harness calls stop on
dispose.
Pulse semantics
- Data pulses are recorded with their payload.
- Error pulses are recorded with
type == 'error'and the error object aspayload. OnlyCell.fromFuturecurrently emits these in the core package — see the extension docs for the full picture. - Ordering: pulses are appended in emission order; the list is neither filtered nor coalesced.
Technical Details
- Snapshot-copy reads: pulses returns
List.unmodifiable(_pulses), which is a copy of the internal list, not a live view — subsequent recordings do not appear in a previously obtained list, and each access is O(n). Hold the result when iterating over a long recording. - Reusable: clear resets the recording without dropping the egress, so one recorder can span multiple assertion phases.
- Idempotent stop: repeated calls are no-ops; after the first stop, pulses continues to return the last recorded list.
- Strong reference: the source cell is pinned for the recorder's lifetime (see Cleanup).
See Also:
- CellRecordPulses.recordPulses — the extension that creates one.
- CellTestHarness — the higher-level harness that owns recorders.
EgressHandle— the primitive that stop releases.Cell.observe— the underlying observation primitive.
Properties
- cell → T
-
The source cell.
final
- hashCode → int
-
The hash code for this object.
no setterinherited
-
payloads
→ List<
Object?> -
The payloads of all recorded pulses, in order.
no setter
-
pulses
→ List<
Pulse< Object?> > -
All pulses recorded so far, in order.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
clear(
) → void - Clears the recorded list without stopping the recorder.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
stop(
) → void - Stops recording and releases the egress.
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited