A Complete Guide to mocking with mockito in Flutter

When you hear about "mocking" in software testing, it's really just a way to create fake, predictable stand-ins for the complex parts of your app. With a tool like Mockito, you can create these controlled versions of class dependencies, which is the key to truly isolating the code you want to test. This isolation makes your tests fast, reliable, and completely independent of things you can't control, like a spotty network connection or a database that's temporarily down.

Why Mocking Is Essential for Robust Flutter Apps

Before we jump into writing any test code, it’s worth taking a moment to understand why mocking is a must-have skill for any serious Flutter developer. The entire concept boils down to one critical goal: test isolation. You want to test one specific piece of your app's logic without any interference from its dependencies.

Think about it. Let's say you're building a screen to show a user's profile. That screen probably relies on something like an ApiService to go and fetch the user's data from a server. If your test uses the real ApiService, it suddenly depends on a whole bunch of external factors:

• A working internet connection.
• Your backend server being up and running.
• The exact data the server decides to send back at that moment.

If any of those things fail, your test fails—even if your UI code is flawless. This is how you end up with "flaky" tests. They pass one minute and fail the next for reasons that have nothing to do with the code you're actually trying to test. Flaky tests are a nightmare because they erode trust in your test suite and can grind a CI/CD pipeline to a halt.

The Power of Predictable Tests

This is the exact problem that mocking with Mockito is designed to solve. Instead of calling the real ApiService, you create a mock version. This mock makes no network calls at all. You simply tell it how to behave for each specific test.

By swapping out real dependencies for mocks, you get total control over the test environment. You can force a success response, simulate a network error, or even test a weird edge-case from the API—all in a way that is instant and 100% predictable.

This approach is so powerful that Mockito has become a staple in the testing world. It started in Java, but the core ideas apply everywhere. In fact, a 2021 study of thousands of projects found that among those using mocking frameworks, Mockito had a massive 77% market share. If you're curious, you can dig into the full analysis of testing framework usage.

Here's a quick breakdown of why this matters so much in practice.

Mockito vs Real Dependencies at a Glance

Ultimately, using mocks gives you a testing environment that is fast, deterministic, and completely under your command.

Mocking as a Gateway to Better Design

Here’s a side benefit you might not expect: embracing Mockito often nudges you toward writing better-architected code. To mock a dependency effectively, your code has to be structured to allow that dependency to be swapped out in the first place. This naturally pushes you toward using patterns like Dependency Injection (DI).

When you design your classes to accept dependencies (like an ApiService) as constructor parameters instead of creating them internally, your code becomes far more modular and decoupled. This isn't just a testing trick; it's a hallmark of well-crafted, scalable software and one of the core skills that define a successful Flutter app developer.

Now that we've covered the "why," let's get into the practical "how." In the rest of this guide, you’ll learn exactly how to install Mockito, generate your first mock, and write unit and widget tests that are clean, fast, and completely reliable.

Integrating Mockito Into Your Flutter Project

Alright, now that we've covered the "why," let's get our hands dirty and actually wire up Mockito in a Flutter project. The process involves adding a couple of key packages and running a code generator. It might seem like a bit of a dance at first, but once you get the rhythm down, it becomes a natural part of your testing workflow.

Adding the Core Dependencies

First things first, you need to add two packages to your pubspec.yaml file. It's crucial to place them under dev_dependencies since they're only for testing, not for your final production app.

• mockito: This is the heart of the operation. It gives you all the tools for creating mocks, stubbing methods with when(), and checking behavior with verify().
• build_runner: This is a powerful code generation tool from the Dart team. Mockito leans on it to automatically write the mock class implementations for you, which saves a ton of boilerplate.

Just pop these lines into your pubspec.yaml:

dev_dependencies:
flutter_test:
sdk: flutter
mockito: ^5.4.4
build_runner: ^2.4.8

After you've added them, jump into your terminal and run flutter pub get to pull the packages into your project. These tools are real lifesavers, and if you're curious about others, check out our list of essential Flutter development tools in our 2024 guide.

Creating a Class to Mock

To see how this all works, we need a subject. Let's create a simple service class that pretends to fetch data from an API. This is the perfect real-world scenario for mocking—you definitely don't want your unit tests hitting a live network.

Create a new file, maybe something like lib/services/api_service.dart, and drop this class inside:

// lib/services/api_service.dart

class ApiService {
Future fetchUserData(String userId) async {
// In a real app, this would make an HTTP request.
await Future.delayed(const Duration(seconds: 2));
return '{"name": "John Doe", "id": "$userId"}';
}

Future deleteUserData(String userId) async {
// In a real app, this would be a DELETE request.
await Future.delayed(const Duration(seconds: 1));
return true;
}
}
This ApiService has a couple of async methods, making it a great candidate to practice mocking.

Generating the Mock File

Now for the magic. We need to tell build_runner to generate a mock version of our ApiService. The way we do this is by using the @GenerateMocks annotation from the Mockito package.

The common convention is to put this annotation right inside the test file where you plan to use the mock. For instance, if you were about to write tests for a UserRepository that depends on ApiService, you'd create test/user_repository_test.dart and set it up like this:

// test/user_repository_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:mockito/annotations.dart';
import 'package:mockito/mockito.dart';

// 1. Import the class you want to mock
import 'package:your_app/services/api_service.dart';

// 2. Import the generated mocks file (which doesn't exist yet!)
import 'user_repository_test.mocks.dart';

// 3. Add the annotation to generate a mock for ApiService
@GenerateMocks([ApiService])
void main() {
// Your tests will go here
}

The secret sauce is that @GenerateMocks([ApiService]) line. It acts as a flag for build_runner, telling it to find this file and create mock implementations for every class in the list.

With the annotation in place, run this command from your project's root folder:

dart run build_runner build --delete-conflicting-outputs

This command kicks off the generation process. I always add the --delete-conflicting-outputs flag; it's a handy way to prevent headaches by clearing out old generated files before creating new ones.

Once it finishes, you'll see a brand new file: user_repository_test.mocks.dart. If you peek inside, you’ll find a generated MockApiService class. This is the fake object, built for you, that you’ll use to control behavior in your tests. This is the power of mocking with Mockito.

Writing Your First Unit Tests With Mockito

Alright, with all the setup out of the way and our mock file generated, it’s time for the fun part: writing clean, isolated unit tests. To keep things organized and easy for the next person to read (who might be you in six months), we're going to lean on the classic Arrange-Act-Assert pattern. It's a simple but powerful structure that brings clarity to any test.

Think of it like this:

• Arrange: Set the stage. Create your mock objects and tell them exactly how to behave when called.
• Act: Perform the action. This is the one thing you're actually testing—usually just a single method call.
• Assert: Check the results. Did everything go as planned? Verify the outcome.

Let's put this into practice by testing a UserRepository that needs our ApiService to function. The repository’s job is simple: call the service, process the data, and return a User model.

Stubbing Synchronous Methods

While most of what you'll do in Flutter involves async code, let's start with a synchronous example to get the hang of Mockito's syntax. It’s a great way to build a foundation. Imagine our ApiService had a simple method like getApiVersion() that just returns a String.

To test any code that relies on this, you'll use the when(...).thenReturn(...) construct. The beauty is in its readability: "When this method gets called, then return this specific value."

// ARRANGE
// First, create an instance of the mock class we generated.
final mockApiService = MockApiService();

// Now, we "stub" the method, defining what it should do.
when(mockApiService.getApiVersion()).thenReturn('v2.1.0');

// Create the class we're testing, injecting our mock dependency.
final userRepository = UserRepository(mockApiService);

// ACT
// Call the method we want to test.
final version = userRepository.fetchApiVersion();

// ASSERT
// Check if we got the value we told the mock to return.
expect(version, 'v2.1.0');

With just a few lines, you’ve taken complete control. The UserRepository thinks it's talking to the real ApiService, but we've dictated the entire conversation. No real implementation is ever touched.

Handling Asynchronous Code with Futures

Now for the real world. In Flutter, you’re constantly working with asynchronous operations that return a Future. For these, thenReturn won't work because it provides a value instantly. We need to simulate the delay of a network call, which is where when(...).thenAnswer(...) comes in.

This powerful function lets you provide an async callback that returns a Future, perfectly mimicking how a real API call would behave. Let's test the "happy path" for our UserRepository's getUser method.

test('getUser returns a User on successful API call', () async {
// ARRANGE
final mockApiService = MockApiService();
final jsonResponse = '{"name": "Jane Doe", "id": "123"}';

// Stub the async method to return a Future with our fake JSON.
when(mockApiService.fetchUserData('123'))
.thenAnswer((_) async => jsonResponse);

final userRepository = UserRepository(mockApiService);

// ACT
final user = await userRepository.getUser('123');

// ASSERT
expect(user.name, 'Jane Doe');
});
The secret sauce is thenAnswer((_) async => ...). This tells Mockito: "Hey, when fetchUserData('123') is eventually called, resolve the Future with this JSON string I'm giving you."

Verifying Method Interactions

Sometimes, you care less about what a method returns and more about whether it was even called. Did my code actually trigger that save function? Was the deletion request sent? This is a job for Mockito's verify function. It lets you assert that a specific interaction with your mock actually happened.

For example, let's say our UserRepository has a deleteUser method. It's a void method—it doesn't return anything—but it absolutely must call deleteUserData on the service.

test('deleteUser calls the correct ApiService method', () async {
// ARRANGE
final mockApiService = MockApiService();
when(mockApiService.deleteUserData('123'))
.thenAnswer((_) async => true);

final userRepository = UserRepository(mockApiService);

// ACT
await userRepository.deleteUser('123');

// ASSERT
// We verify that deleteUserData was called exactly once with '123'.
verify(mockApiService.deleteUserData('123')).called(1);
});
That verify(...) line at the end is our entire assertion. It confirms that our repository is correctly delegating the deletion task, giving us confidence in its internal logic without needing a return value.

Simulating Failures and Exceptions

A great test suite doesn't just check for sunshine and rainbows; it validates that your app handles storms gracefully. Mockito makes it incredibly easy to simulate errors by telling a stubbed method to throw an exception instead of returning a value.

A core tenet of unit testing is to test behavior, not implementation. By forcing an exception with a mock, you can verify that your app’s UI or logic gracefully handles network failures, server errors, or any other problem without testing the network itself.

Let's test how our UserRepository reacts when the ApiService throws a 500 Internal Server Error.

test('getUser throws an exception when ApiService fails', () async {
// ARRANGE
final mockApiService = MockApiService();

// Instead of returning data, tell the mock to throw an exception.
when(mockApiService.fetchUserData(any))
.thenThrow(Exception('Server Error!'));

final userRepository = UserRepository(mockApiService);

// ACT & ASSERT
// We expect that calling getUser will result in an exception.
expect(() => userRepository.getUser('123'), throwsException);
});
Notice two things here. First, we used thenThrow to create the failure scenario. Second, we used any, a powerful argument matcher. It tells Mockito to trigger this stub for any argument passed to fetchUserData, making the test more robust if the specific ID isn't relevant to the error-handling logic.

Mockito's rise to fame was swift, especially after a landmark 2013 analysis of 30,000 GitHub projects placed it among the top Java libraries. Its dominance in mocking niches hit 77% after its seamless JUnit integration. You can find out more about its history and see how it stacks up on Slashdot's software comparison page.

7. Advanced Mocking Techniques and Professional Workflows

Once you've nailed the basics of stubbing and verifying, you're ready to tackle the more complex scenarios you'll inevitably face in a real-world Flutter app. This is where advanced mocking techniques move your tests from just "passing" to being a reliable safety net that catches bugs before they ever reach production.

One of the most common challenges in modern app development is testing reactive code. Think about a Stream—unlike a simple Future that gives you one value, a Stream can fire off a whole sequence of events. How do you test a BLoC or a ChangeNotifier that depends on one?

Thankfully, Mockito handles this beautifully. You can use when(...).thenAnswer(...) with Stream.fromIterable() to simulate a stream emitting multiple values over time.

Let's say our ApiService has a method that streams user activity updates. We can mock it like this:

// ARRANGE
final mockApiService = MockApiService();
final activityUpdates = ['User logged in', 'User viewed profile', 'User logged out'];

// Here, we're telling Mockito what to do when userActivityStream is called.
// Instead of a single value, we're providing a whole stream.
when(mockApiService.userActivityStream('123'))
.thenAnswer((_) => Stream.fromIterable(activityUpdates));

// ACT & ASSERT
// The emitsInOrder matcher is perfect for verifying stream outputs.
expect(mockApiService.userActivityStream('123'), emitsInOrder(activityUpdates));
This gives you total control over the stream's behavior, letting you precisely test how your logic or UI layer reacts to each event.

Writing More Resilient Tests with Argument Matchers

If you find yourself hardcoding specific values like user IDs or strings into your when() calls, you might be creating brittle tests. A minor, unrelated change—like updating a default ID from '123' to 'user-abc'—could break your test suite even if the core logic is perfectly fine.

Argument matchers are Mockito’s answer to this problem. You’ve probably already used any, but there's a whole toolkit of them you should get familiar with:

• anyNamed('...'): Matches any value passed to a specific named parameter.
• startsWith(...): Great for matching string arguments that begin with a certain prefix.
• captureAny(): This one is a game-changer. It "captures" the argument a method was called with, allowing you to run detailed assertions on it later.

captureAny() is especially powerful when you need to inspect an object that was created inside the method you're testing. For example, imagine your code builds a new User object and then passes it to a saveUser method. You can capture that object to make sure it was constructed correctly.

// ARRANGE
// … your usual mock and repository setup

// ACT
await repository.createNewUser('Alice', 30);

// ASSERT
// First, we verify the method was called, capturing the argument.
final captured = verify(mockDatabase.saveUser(captureAny)).captured;
final savedUser = captured.first as User;

// Now, we can run assertions on the actual object that was passed.
expect(savedUser.name, 'Alice');
expect(savedUser.age, 30);

This is a far more robust approach than just checking that saveUser was called with some object. You're confirming the state of that object is exactly what you expect.

An Alternative Worth Knowing: Mocktail

While Mockito is a proven and powerful tool, it's not the only player in town. A popular alternative in the Dart community is mocktail. Its main selling point? No code generation.

Mocktail uses Dart's noSuchMethod feature to create mocks on the fly. This can significantly simplify your project setup and speed up your TDD (Test-Driven Development) cycle, since you don't have to wait for build_runner to do its thing every time you add or change a mocked class.

Mockito vs Mocktail a Quick Comparison

If you're wondering which to choose, this table breaks down the main differences. The API is very similar, so switching isn't too difficult.

For teams that find the code generation step with build_runner to be a bottleneck, mocktail is an excellent choice. It provides a more immediate feedback loop, which is a huge win for productivity. Optimizing your workflow is a big part of professional development, and if you're interested in more tips, you can learn about improving developer productivity in our detailed guide.

Core Principles for Professional Mocking

Ultimately, leveling up your testing game is as much about mindset as it is about syntax. It's about adopting professional habits that lead to clean, maintainable, and truly useful tests.

The golden rule I always follow is to mock roles, not objects. Think about what a dependency does, not what it is. You should mock "a thing that fetches data" or "a service that handles authentication." This keeps your tests focused on behavior, making them more resilient to implementation changes.

To wrap up, here are three best practices I've learned from years of writing tests:

1. Keep Mocks Simple: Your mock setup for a single test should be minimal. If you find yourself writing dozens of when() calls, that’s a code smell. It often means the class you're testing has too many responsibilities and should be refactored.
2. Never Mock Data Models: Simple data-holding classes (like a User or Product model) should never be mocked. Just create a real instance with the data you need. Mocking them adds needless complexity and makes the test harder to understand.
3. Don't Mock Types You Don't Own: Resist the urge to mock classes from the Flutter SDK or third-party packages (like HttpClient). You can't control their implementation, and a future update could break all your tests. The professional approach is to wrap that external code in your own class (e.g., MyApiClient) and mock your wrapper instead. This isolates your code and protects you from upstream changes.

Using Mocks in Your Widget and Integration Tests

Unit tests are fantastic for making sure your business logic is solid, but they have a blind spot: they can't tell you what your UI actually looks like or how it behaves. That’s where widget tests shine. They let you test individual Flutter widgets in an isolated, controlled environment. When you bring Mockito into the mix, you can finally connect your logic to your visuals and guarantee your UI handles every possible state correctly.

The trick is injecting your mocks directly into the widget tree. If you're already using a dependency injection (DI) or state management package like provider or get_it, this is surprisingly simple. You just provide the mocked version of your service or repository instead of the real one, giving you total command over the data your widget receives.

Testing UI States with Mocked Data

Let's walk through a classic scenario: a screen that needs to fetch and show a list of items from an ItemRepository. Any screen like this will have at least three core states: a loading spinner while data is being fetched, the list of items when it succeeds, and an error message if something goes wrong. Widget tests are the perfect tool to lock down the behavior for all three.

Imagine you have a testWidgets block and you want to confirm the success state. All you need to do is provide a mocked repository that’s been told to return a specific list of items.

testWidgets('displays a list of items on successful fetch', (WidgetTester tester) async {
// ARRANGE: Create the mock and stub its method.
final mockRepository = MockItemRepository();
when(mockRepository.fetchItems())
.thenAnswer((_) async => [Item(name: 'First Item')]);

// ACT: Pump the widget, providing the mock.
await tester.pumpWidget(
Provider.value(
value: mockRepository,
child: const MaterialApp(home: ItemsScreen()),
),
);

// Let the UI build after the Future resolves.
await tester.pumpAndSettle();

// ASSERT: Verify the correct widgets are on screen.
expect(find.text('First Item'), findsOneWidget);
expect(find.byType(CircularProgressIndicator), findsNothing);
});

With this test, the ItemsScreen is completely isolated. It has no idea where the data came from—it just knows it received a list and rendered it properly. You've just successfully tested your UI's response to a specific data scenario without ever hitting a real database or network.

Simulating Loading and Error States

Testing the loading and error states follows the same pattern, you just change the mock's behavior. To test the loading UI, for instance, you can use a Completer to delay the mock's response. This gives you a window to check that your CircularProgressIndicator is actually showing up.

The real power of mocking in widget tests is the ability to reliably reproduce UI states that are otherwise difficult to trigger. You can force an error state in a single line of code, something that would be nearly impossible to do consistently with a live backend.

And for an error condition? Just tell your mock to throw an exception. It’s that easy.

• Arrange: when(mockRepository.fetchItems()).thenThrow(Exception('Network Error'));
• Act: Pump the widget with your pre-configured, error-throwing mock.
• Assert: expect(find.text('Oops! Something went wrong.'), findsOneWidget);

By setting up separate, focused tests for your loading, success, and error states, you build an incredibly robust safety net around your UI. You can then refactor your widgets with confidence, knowing your test suite will instantly flag any regressions in how they handle data.

Extending to Integration Tests

The great news is that these exact same techniques scale up perfectly for integration tests. While widget tests are about individual widgets, integration tests verify entire user flows across multiple screens. You could write a test that simulates a user tapping a button, navigating to a new screen, and seeing data that was "fetched" from a mocked service.

By providing mocks at the root of your app within an integration_test, you gain control over the entire test environment. This lets you test complex user journeys in a way that is fast, repeatable, and completely deterministic, freeing you from the flakiness of external dependencies. This is really the heart of building a professional and reliable testing strategy.

Common Questions About Mocking With Mockito

As you get more comfortable with Mockito, you'll inevitably hit a few tricky situations. That's perfectly normal—it happens to everyone. Let's walk through some of the most common questions that pop up and get you unstuck.

These aren't just theoretical problems; they're scenarios you'll almost certainly face in real-world projects. Knowing how to handle them is what separates a good test suite from a great one.

How Do I Mock a Class With a Generic Type?

This is a big one. It trips up a lot of developers when they start working with more advanced services or repositories. Let's say you have a generic class like CacheService<T> that can handle different data types.

You can't just throw @GenerateMocks([CacheService]) at it. Why? Because Mockito and build_runner need to know exactly which version of that generic class to mock.

The solution is surprisingly simple: create a small helper class right inside your test file. This class just extends Mock and implements the specific version of the generic you need for that particular test.

For example, to test something that depends on CacheService<User>, you’d define a little mock class like this:

// test/user_repository_test.dart

// … other imports
import 'package:your_app/services/cache_service.dart';

// Create a concrete mock class for the generic type
class MockUserCache extends Mock implements CacheService {}

// Now, tell Mockito to generate a mock for this new class
@GenerateMocks([ApiService, MockUserCache])
void main() {
// … your tests
}
By creating MockUserCache, you're giving build_runner a concrete class to work with. From there, you can use MockUserCache in your tests just like any other mock, stubbing its methods and verifying interactions for a CacheService that deals specifically with User objects.

What’s the Difference Between thenReturn and thenAnswer?

On the surface, thenReturn and thenAnswer look like they do the same thing, but they have very different jobs, especially when you're dealing with async code. Getting this right is critical for your tests to behave correctly.

Here’s the breakdown:

• thenReturn(value): Use this for synchronous methods. It's clean, direct, and gives you a value immediately. Think when(mock.getName()).thenReturn('Alice');.

• thenAnswer((_) async => value): This is your go-to for any method that returns a Future. It lets you provide a function that returns a Future, which is exactly how things like network calls or database reads work.

The key takeaway is that thenReturn gives you a value right now, while thenAnswer gives you a Future that will resolve with a value later. If you use thenReturn for an async method, you’ll likely crash your test with an InvalidType error because the code is expecting a Future, not a raw value.

For instance, when you're faking an API call, thenAnswer is the only way to go:

// The right way to stub async methods
when(mockApi.fetchData())
.thenAnswer((_) async => '{"data": "success"}');

This ensures your mock response is properly wrapped in a Future, perfectly mimicking the real asynchronous behavior.

Can I Mock Top-Level Functions or Extension Methods?

The short answer here is no. Mockito simply can't mock top-level functions (like a global helper function) or extension methods.

This isn't a bug; it's a fundamental part of how Mockito is designed. It works by creating a new class that subclasses the one you want to mock, then it overrides its methods. Because top-level functions and extension methods don't technically belong to a class's interface, there's nothing for a mock subclass to override.

This limitation actually nudges you toward better code architecture. It encourages you to wrap that kind of logic inside a class that you can control.

Instead of calling a global sendEmail() function everywhere, you'd create an EmailService class with a send() method. This service can then be properly injected as a dependency and easily mocked in your tests. This approach, often called the "Wrapper" or "Adapter" pattern, leads to code that's more modular, decoupled, and, best of all, way easier to test.

Flutter Geek Hub is your go-to resource for mastering Flutter development. To continue learning with deep-dive tutorials and practical guides, explore more articles at https://fluttergeekhub.com.