CellExpectValue extension
An extension on WidgetTester that asserts a ValueCell's current value against a matcher, with a cell-naming diagnostic on failure.
CellExpectValue is the binding's Value Assertion Helper. It is a
thin sugar over expect(cell.value, matcher) whose only behavior beyond
the raw matcher call is to attach a reason that names the cell. That
sounds small, but it turns a failed assertion from
Expected: <5>
Actual: <3>
into
Expected: <5>
Actual: <3>
for cell ValueCell<int>
which tells the reader which cell in a test with several of them was the one that disagreed with the expectation.
Why it is used
- Readable assertions:
tester.expectCellValue(counter.cell, 5)reads as a sentence and, at a glance, makes the test's intent obvious. - Failure diagnostics: the default
reasonnames the cell's runtime type so multi-cell tests do not require counting failures against a stack trace to figure out which assertion failed. - Uniform idiom across the binding's tests: mirroring the way
CellRecordPulses.recordPulses and
pumpWithCellsextend WidgetTester, this helper keeps cell-specific test utilities on the same receiver, so tests do not need to import per-helper utilities.
How it works
- It calls
cell.value— a synchronous read of the ValueCell's current value. - It forwards that value and
matcherto expect, along with areasonderived fromreason(if supplied) or from the cell's runtime type.
Design Note: why a WidgetTester extension, not a free function
Placing the helper on WidgetTester is deliberate: it lets tests mix
cell assertions with widget-test actions (tap, pump, find) on the
same tester receiver, and it keeps the helper out of the global
namespace so application code that happens to import flutter_test
does not accidentally see it. The same placement is used by
CellPumpCell.pumpCell and CellPumpWithCells.pumpWithCells, so the
binding's test helpers are cohesive.
Return value and failure
This method returns void. On mismatch, it throws a TestFailure — the
same failure type expect raises — with the diagnostic described above.
There is no way to make it not throw: it is a strict assertion.
Technical Details
- Generic over ValueCell only: the helper reads
cell.valuesynchronously, which is a ValueCell capability. PlainCellsources (Cell.derive,Cell.asyncMap) have no synchronous value — assert on a recorded pulse sequence via CellRecordPulses.recordPulses or on the rendered widget via CellPumpCell.pumpCell instead. - The default
reasonnames only the runtime type, not the specific instance — twoCell<int>instances in one test still produce the same message. Supplyreasonexplicitly when the test has more than one cell of the same value type. - No cell-side effects: this helper reads; it does not mutate, does not subscribe, and does not require the recorder or any harness.
Example
tester.expectCellValue(counter.cell, 5);
tester.expectCellValue(auth.cell, isA<SignedIn>(),
reason: 'after sign-in');
See Also:
- ValueCell — the cell type this helper asserts on.
- CellRecordPulses.recordPulses — for asserting a pulse sequence rather than a current value.
- CellPumpCell.pumpCell / CellPumpWithCells.pumpWithCells — the companion pumping helpers, also extensions on WidgetTester.
- expect — the matcher call this helper forwards to.
- on
Methods
-
expectCellValue<
V> (ValueCell< V> cell, Object? matcher, {String? reason}) → void -
Available on WidgetTester, provided by the CellExpectValue extension
Asserts thatcell's current value matchesmatcher.