CellTestHarness class

A per-test Cell Registry that bundles the cells a test suite needs, tracks their pulse recorders, and disposes both in one call.

CellTestHarness is the binding's Test Fixture. It wraps the two pieces that most cell-based tests share — a Symbol-keyed map of cells to register into a CellScope, and the PulseRecorders opened on them — behind a single object whose dispose cleans up everything it created. The per-operation extensions (pumpWithCells, emitAndSettle, recordPulses) remain available; the harness simply layers ownership on top so tests with several cells do not have to track recorders by hand.

Why it is used

  • Multi-cell tests: suites with 3+ cells, or with the same cells reused across many tests, benefit from a single fixture that knows every registration and every recorder. Per-test bookkeeping of "did I addTearDown the recorder?" disappears.
  • Recorder ownership: every recorder created via recordPulses is tracked and stopped on dispose. A recorder left running pins its source cell for the isolate's lifetime; the harness eliminates that failure mode by default.
  • Chainable setup: add returns the harness, so setUp reads as a single chain of registrations.

When not to use it

For a suite with 1–2 cells, the extension methods (CellPumpWithCells, CellEmitAndSettle, CellRecordPulses) are shorter — a few lines of setUp/tearDown beat a harness object. The harness is worth its ceremony only when there are enough registrations to justify it.

How it works

  1. Registration: add inserts a cell under a Symbol key. The map is what pump passes to CellPumpWithCells.pumpWithCells, so the same set of cells is scoped above every widget the test pumps.
  2. Lookup: cell and valueCell retrieve a registration with optional type narrowing. A type mismatch throws StateError; an unknown id throws too.
  3. Recording: recordPulses opens a PulseRecorder on the cell at the given id and stores it for later disposal.
  4. Pumping and emission: pump and emitAndSettle delegate to the corresponding WidgetTester extensions, using the harness's registry as the scope.
  5. Disposal: dispose stops every recorder and clears the registry. It is idempotent.

Design Note: the harness owns recorders, not cells

The split is deliberate. A test's cells may outlive the harness (a suite-level Cell.state reused across tests, for example), and invalidating them during tearDown would break the next test. The harness therefore owns only the resources it created — the recorders — and leaves cell lifecycle entirely to the caller. Registering the same Symbol twice replaces the previous entry without disposing it; dispose clears the map without invalidating the cells.

Technical Details

  • Symbol-keyed registry: matches CellScope's design — the same map is passed to the scope in pump, so registrations and lookups use the same keys. See CellScope for why Symbols rather than type-keys.
  • Type narrowing is ValueCell-only: Cell carries no value type parameter, so cell can only type-check ValueCell registrations. valueCell requires a ValueCell<V> and throws otherwise.
  • Disposal is idempotent and final: after dispose, add, recordPulses, and pump throw StateError. The registry is cleared; subsequent calls are programmer errors, not silent no-ops.
  • No WidgetTester ownership: the harness does not hold a tester. pump and emitAndSettle take a tester argument per call so the same harness can serve multiple testWidgets bodies.

Example

late CellTestHarness harness;

setUp(() {
  harness = CellTestHarness()
    ..add(#counter, Cell.state<int>(initial: 0).cell)
    ..add(#auth, Cell.state<AuthState?>(initial: null).cell);
});

tearDown(() => harness.dispose());

testWidgets('renders counter', (tester) async {
  await harness.pump(tester: tester, child: LoginScreen());
  await harness.emitAndSettle(tester, #counter, 5);
  expect(find.text('5'), findsOneWidget);
});

testWidgets('records pulses', (tester) async {
  final recorder = harness.recordPulses(#counter);
  // harness.dispose() stops all recorders automatically.
  expect(recorder.payloads, isEmpty);
});

See Also:

Constructors

CellTestHarness()

Properties

cells → Map<Symbol, Cell>
The cells registered in this harness, in insertion order.
no setter
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

add(Symbol id, Cell cell) → CellTestHarness
Registers cell under id. Chainable.
cell<V>(Symbol id) → Cell
Returns the cell registered at id, narrowed to ValueCell<V> when the registration is a ValueCell.
dispose() → void
Stops all recorders and clears the registry. Idempotent.
emitAndSettle<V>(WidgetTester tester, Symbol id, V? value) → Future<void>
Sets the value of the cell at id and pumps the tree to settle.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pump({required WidgetTester tester, required Widget child, Widget wrapper(Widget child)?}) → Future<void>
Pumps child with the harness's registered cells in a CellScope.
recordPulses(Symbol id) → PulseRecorder<Cell>
Records pulses from the cell registered at id.
toString() → String
A string representation of this object.
inherited
valueCell<V>(Symbol id) → ValueCell<V>
Returns the ValueCell<V> registered at id.

Operators

operator ==(Object other) → bool
The equality operator.
inherited