A blocTest fails although the printed expected and actual CartState lists look identical; what is bloc_test telling you, and how do you fix it?

## How blocTest compares states At the end of a **blocTest** case, the recorded list of states is matched against whatever `expect` returns. A plain `List` of states is compared element by element with `==`. Dart's default `==` on a class is **identity**: two objects are equal only if they are the same instance. A handler always builds a new `CartState`, and the test builds its own expected `CartState`, so without value equality they can never be equal - however similar they look. ## Reading the two failure messages bloc_test (version 10) adds help to the failure in two different situations: - **The strings match but the objects do not.** blocTest compares `'$states'` with `'$expected'`. If the text is identical yet the match failed, it appends a warning: ensure the state instances extend `Equatable`, override `==` and `hashCode`, or implement `Comparable` - or use matchers in `expect` instead of concrete instances. This is the "looks identical but fails" case. - **The strings differ.** When `expect` returned a `List` of states, blocTest appends a coloured diff between expected and actual, so you can see which field or which state is off. Note that the text comparison depends on `toString`. With `Equatable`, `stringify` defaults to true in debug mode, so states print their props; a class with no `toString` prints `Instance of 'CartState'` for every state, which also produces identical strings. ## Fix 1: value equality The usual fix is to make the state a value type, most often with the **equatable** package (version 3): ```dart class CartState extends Equatable { const CartState({this.items = const []}); final List<CartItem> items; @override List<Object?> get props => [items]; } ``` `Equatable` compares `props` element by element and compares nested lists and maps by content, so two carts with equal items are equal. `CartItem` needs value equality too, or the list comparison falls back to identity for its elements. ## The props trap A field missing from `props` is worse than no equality at all: 1. Add a `discountCode` field to `CartState` but forget it in `props`. 2. A test expecting `CartState(items: [apple], discountCode: 'SAVE10')` passes against a state with no code - the field is simply not compared. 3. In the app, the bloc drops an emission whose only change is the code, because the new state `==` the current one. So the test passes falsely **and** the UI never updates. Review `props` whenever a state gains a field. ## Fix 2: matchers When a state cannot have value equality (it wraps a type you do not control, or you only care about one field), return matchers from `expect`: - `isA<CartState>()` - asserts only the type. - `isA<CartState>().having((s) => s.items.length, 'items.length', 1)` - asserts one derived value. - A list of such matchers still enforces order and count. Matchers make tests less brittle but also less strict: a field you did not mention is not checked. ## A related symptom: a missing state If a handler mutates the current state's list in place and emits the same instance, the new state is identical to the current one; once the bloc has emitted at least once (bloc lets only the very first emission through when it equals the current state), it drops it. The test then fails because a state is **missing**, not because equality is wrong. The cure is immutable states - build a new list instead of `state.items.add(...)`. ## Checklist - Identical printed lists plus a failure means identity comparison. - Every field goes in `props`, including nested value types. - Use matchers when value equality is not possible. - A missing state after an in-place mutation is a state-design bug, not a test bug.