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
addTearDownthe 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:
addreturns the harness, sosetUpreads 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
- Registration: add inserts a cell under a
Symbolkey. The map is what pump passes to CellPumpWithCells.pumpWithCells, so the same set of cells is scoped above every widget the test pumps. - Lookup: cell and valueCell retrieve a registration with optional type narrowing. A type mismatch throws StateError; an unknown id throws too.
- Recording: recordPulses opens a PulseRecorder on the cell at the given id and stores it for later disposal.
- Pumping and emission: pump and emitAndSettle delegate to the
corresponding
WidgetTesterextensions, using the harness's registry as the scope. - 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:Cellcarries no value type parameter, so cell can only type-check ValueCell registrations. valueCell requires aValueCell<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
WidgetTesterownership: the harness does not hold a tester. pump and emitAndSettle take a tester argument per call so the same harness can serve multipletestWidgetsbodies.
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:
- CellPumpWithCells.pumpWithCells — the underlying scoped-pump helper.
- CellEmitAndSettle.emitAndSettle — the underlying emit-and-settle helper.
- CellRecordPulses.recordPulses — the underlying recorder constructor.
- CellScope — the registry installed above every pumped tree.
- PulseRecorder — the recorder type the harness tracks and disposes.
Constructors
Properties
Methods
-
add(
Symbol id, Cell cell) → CellTestHarness -
Registers
cellunderid. Chainable. -
cell<
V> (Symbol id) → Cell -
Returns the cell registered at
id, narrowed toValueCell<V>when the registration is aValueCell. -
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
idand 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
childwith 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 atid.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited