اختبار BLoC باستخدام bloc_test وMocktail

A BLoC is a pure state machine: it takes events in and emits a predictable sequence of states out. That makes it the most testable layer of a Flutter app.

A good bloc test answers one question: given this starting state and these events, exactly which states get emitted, in what order?

• Deterministic means the same input always produces the same output sequence.
• Sources of non-determinism to eliminate: real network calls, DateTime.now(), random values, and timers.

We solve this with two packages: bloc_test for the test harness and mocktail for faking dependencies.

Add the test tooling to the dev_dependencies section of pubspec.yaml. None of these ship in your production bundle.

• bloc_test provides the blocTest helper.
• mocktail creates mocks with no code generation.
• test gives you group, setUp, and expect.

Mocktail is preferred over Mockito here because it needs no build_runner step and works cleanly with null safety.

Here is the BLoC we will test. A WeatherBloc depends on a WeatherRepository abstraction. On a WeatherRequested event it emits a loading state, then either a success or failure state.

Notice the dependency is injected through the constructor. This is the key design choice that makes the BLoC testable: we can pass in a fake repository instead of one that hits the network.

To isolate the BLoC, we replace the real repository with a mock. With Mocktail you simply extend Mock and implement the abstraction.

• No annotations, no generated .mocks.dart files.
• The mock starts with every method stubbed to return null until you tell it otherwise.

You then control its behaviour per test using when(...).thenAnswer(...).

Inside a test, configure the mock before acting. Use thenAnswer for asynchronous methods that return a Future, and thenThrow to simulate an error path.

• thenAnswer((_) async => value) returns a resolved Future.
• thenThrow(Exception()) makes the call fail, exercising your catch block.

This is how you force the exact branch you want without any real I/O.

The blocTest function from bloc_test wires up the whole flow. Its core parameters are:

• build: returns a fresh BLoC instance for each run.
• act: dispatches one or more events into that BLoC.
• expect: the ordered list of states that should be emitted, excluding the initial state.

The build callback runs anew every test, guaranteeing a clean slate and no shared state between cases.

The expect list compares emitted states to your expected states using ==. Plain Dart classes compare by identity, so two different WeatherSuccess instances would never be equal and your test would fail confusingly.

Override value equality with the equatable package. List the fields in props and instances with the same values compare as equal.

Robust tests cover errors, not just the happy path. Stub the dependency to throw, then assert the BLoC emits the failure state instead of crashing.

This proves your try/catch in the handler actually converts exceptions into a user-facing error state.

Mocktail's any() matcher lets you stub a call regardless of the argument. But for custom types Mocktail cannot construct a placeholder, so it throws at registration time.

Fix this by registering a Fake instance once in setUpAll. Built-in types like String and int never need this; only your own classes do.

Beyond asserting emitted states, you often want to confirm the BLoC actually called its dependency the right number of times. Use verify in the verify callback of blocTest, which runs after expect.

• verify(() => mock.method()).called(1) asserts exactly one call.
• verifyNever(...) asserts a call never happened.

This catches bugs where the right state is emitted but for the wrong reason.

Two more blocTest parameters give you fine control:

• seed: provides a starting state, so you can test a transition from any point, not just the initial state.
• skip: ignores the first N emitted states, useful when you only care about the final one.
• wait: a Duration to let debounced or delayed events settle before assertions run.

Use seed to test event handlers in isolation without replaying the entire history.

A test stubs repository.fetch(any()) where fetch takes a custom Weather argument, and the test crashes at setup with a fallback-value error before any state is emitted. What is the correct fix?

You now have a repeatable recipe for testing BLoCs:

• Inject dependencies through the constructor so they can be swapped for mocks.
• Create mocks by extending Mock implements with Mocktail; no code generation needed.
• Stub behaviour with thenAnswer for success and thenThrow for failure paths.
• Use blocTest with build / act / expect to assert the exact ordered states.
• Make expect reliable with Equatable value equality.
• Register fallbacks with registerFallbackValue when matching custom types via any().
• Confirm intent with verify, and control flow with seed, skip, and wait.

Cover both the happy and failure paths, and your BLoC layer becomes fully deterministic and regression-proof.