0Pricing
Flutter Mobile Development · Lesson

Testing BLoCs with bloc_test and Mocktail

Write deterministic unit tests for blocs using bloc_test expectations and mocked dependencies.

Testing BLoCs with bloc_test and Mocktail is a free Flutter Mobile Development lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Flutter Mobile Development learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why BLoCs Need Deterministic Tests

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.

Setting Up the Test 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.

dev_dependencies:
  bloc_test: ^9.1.7
  mocktail: ^1.0.4
  test: ^1.25.0

The BLoC Under Test

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.

class WeatherBloc extends Bloc<WeatherEvent, WeatherState> {
  WeatherBloc(this._repository) : super(WeatherInitial()) {
    on<WeatherRequested>(_onRequested);
  }

  final WeatherRepository _repository;

  Future<void> _onRequested(
    WeatherRequested event,
    Emitter<WeatherState> emit,
  ) async {
    emit(WeatherLoading());
    try {
      final weather = await _repository.fetch(event.city);
      emit(WeatherSuccess(weather));
    } catch (_) {
      emit(WeatherFailure());
    }
  }
}

Creating a Mock with Mocktail

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(...).

import 'package:mocktail/mocktail.dart';

class MockWeatherRepository extends Mock
    implements WeatherRepository {}

class FakeWeather extends Fake implements Weather {}

Stubbing Return Values

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.

// Success path stub
when(() => repository.fetch('London'))
    .thenAnswer((_) async => const Weather(temp: 14, city: 'London'));

// Failure path stub
when(() => repository.fetch('London'))
    .thenThrow(Exception('network down'));

The blocTest Helper Anatomy

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.

blocTest<WeatherBloc, WeatherState>(
  'emits [Loading, Success] when fetch succeeds',
  build: () {
    when(() => repository.fetch(any()))
        .thenAnswer((_) async => const Weather(temp: 14, city: 'London'));
    return WeatherBloc(repository);
  },
  act: (bloc) => bloc.add(const WeatherRequested('London')),
  expect: () => const [
    WeatherLoading(),
    WeatherSuccess(Weather(temp: 14, city: 'London')),
  ],
);

Equatable Makes expect Work

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.

abstract class WeatherState extends Equatable {
  const WeatherState();
  @override
  List<Object?> get props => [];
}

class WeatherSuccess extends WeatherState {
  const WeatherSuccess(this.weather);
  final Weather weather;
  @override
  List<Object?> get props => [weather];
}

Testing the Failure Path

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.

blocTest<WeatherBloc, WeatherState>(
  'emits [Loading, Failure] when fetch throws',
  build: () {
    when(() => repository.fetch(any()))
        .thenThrow(Exception('network down'));
    return WeatherBloc(repository);
  },
  act: (bloc) => bloc.add(const WeatherRequested('London')),
  expect: () => const [
    WeatherLoading(),
    WeatherFailure(),
  ],
);

registerFallbackValue for any()

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.

setUpAll(() {
  // Required before using any<Weather>() in stubs
  registerFallbackValue(FakeWeather());
});

Verifying Interactions

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.

blocTest<WeatherBloc, WeatherState>(
  'calls repository exactly once',
  build: () {
    when(() => repository.fetch(any()))
        .thenAnswer((_) async => const Weather(temp: 14, city: 'London'));
    return WeatherBloc(repository);
  },
  act: (bloc) => bloc.add(const WeatherRequested('London')),
  verify: (_) {
    verify(() => repository.fetch('London')).called(1);
  },
);

Controlling Time with seed and skip

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.

blocTest<CounterBloc, int>(
  'emits [11] from a seeded state of 10',
  build: () => CounterBloc(),
  seed: () => 10,
  act: (bloc) => bloc.add(Increment()),
  expect: () => const [11],
);

Quick Check

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?

Recap: Deterministic BLoC Testing

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.

Frequently asked questions

Is the “Testing BLoCs with bloc_test and Mocktail” lesson free?

Yes — the full text of “Testing BLoCs with bloc_test and Mocktail” is free to read here on the web, and the Flutter Mobile Development course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Flutter Mobile Development course, upgrade to CoddyKit PRO.

What will I learn in “Testing BLoCs with bloc_test and Mocktail”?

Write deterministic unit tests for blocs using bloc_test expectations and mocked dependencies. You practise Flutter Mobile Development with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Flutter Mobile Development?

No prior experience is required. Flutter Mobile Development on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Testing BLoCs with bloc_test and Mocktail” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Flutter Mobile Development lesson?

Yes. Every Flutter Mobile Development lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Events, States, and the Cubit-vs-Bloc Decision
  2. Stream Transformers and Event Debouncing in BLoC
  3. Persisting State with HydratedBloc
  4. Testing BLoCs with bloc_test and Mocktail
← Back to Flutter Mobile Development