Mocks & Fakes

## What mocktail is **mocktail** (version 1.x) is a mocking library for Dart and Flutter tests. It creates a **mock**: an object that implements your dependency's interface, records every call made on it, and returns whatever you configured. Its selling point is that it needs **no code generation** — you write one line per mock class and never run a build step. ```dart import 'package:flutter_test/flutter_test.dart'; import 'package:mocktail/mocktail.dart'; class MockWeatherApi extends Mock implements WeatherApi {} ``` `Mock` overrides `noSuchMethod`. Because `MockWeatherApi` declares no bodies of its own, every call to a `WeatherApi` member lands in `noSuchMethod`, where mocktail either records the call or looks up a stub. ## Stubbing: `when` plus a response A **stub** tells the mock what to return for a matching call. mocktail's `when` takes a **closure**, not the call's result: ```dart final api = MockWeatherApi(); when(() => api.fetchForecast('Oslo')) .thenAnswer((_) async => const Forecast(highC: 14, lowC: 6)); ``` The three responses: - `thenReturn(value)` — returns a fixed, synchronous value. Passing a `Future` or `Stream` throws an `ArgumentError` telling you to use `thenAnswer` instead. - `thenAnswer((invocation) => ...)` — runs a function on every call, so it is the right tool for `Future`s, `Stream`s and answers computed from the arguments. - `thenThrow(error)` — throws, which is how you drive the view model's error branch. When several stubs match the same call, the **most recently registered** one wins, so a test can override a stub set in `setUp`. ## Argument matchers Literal arguments must be equal to match. For looser matching: - `any()` for a positional argument and `any(named: 'units')` for a named one. - `any(that: startsWith('O'))` to apply a `package:matcher` matcher. - `captureAny()` inside `verify` to read back the arguments that were passed. Using `any()` on a parameter of a custom class needs `registerFallbackValue` for that type first; primitives, `List`, `Map`, `Set` and `DateTime` are covered out of the box. ## Verifying interactions After running the code under test, `verify` checks what happened: ```dart await viewModel.load('Oslo'); verify(() => api.fetchForecast('Oslo')).called(1); verifyNever(() => api.fetchForecast('Bergen')); verifyNoMoreInteractions(api); ``` Details interviewers probe: 1. `called` accepts an exact count or a matcher such as `greaterThan(1)`. 2. `called(0)` does not work as expected; mocktail's own docs say to use `verifyNever`. 3. A verified invocation is **excluded from later verifications**, so a second `verify(...).called(1)` only counts calls made since the first. 4. `verifyInOrder([...])` checks order; `untilCalled(() => ...)` returns a `Future` that completes when the call happens. 5. `reset(api)` clears both stubs and recorded calls. ## The failure you meet first An unstubbed member returns `null` by default. For a method whose return type is non-nullable — `Future<Forecast>` — that surfaces as a `TypeError` such as `type 'Null' is not a subtype of type 'Future<Forecast>'`, thrown where the view model calls the mock. The fix is a stub, not a nullable signature. `throwOnMissingStub(mock)` makes unstubbed calls throw a clearer error instead. | Goal | mocktail call | |---|---| | Return a plain value | `thenReturn(value)` | | Return a `Future` or `Stream` | `thenAnswer((_) async => value)` | | Drive the error path | `thenThrow(Exception('offline'))` | | Assert exactly n calls | `verify(() => ...).called(n)` | | Assert no call | `verifyNever(() => ...)` | ## Common mistakes in review - **Stubbing after the call.** `when` must run before the code under test calls the mock; a stub registered afterwards affects only later calls. - **Literal arguments that never match.** `when(() => api.fetchForecast('oslo'))` does not match a call with `'Oslo'`; the mock then returns `null` and the failure appears far from the typo. Use `any()` when the argument is not what the test is about. - **Stubbing an extension method.** Extension methods are resolved statically and never reach `noSuchMethod`, so mocktail cannot intercept them: the real extension runs, and `when` typically reports that no method stub was called. Stub the instance member the extension uses instead. - **One mock shared across tests without a fresh instance.** Create the mock in `setUp`, or call `reset` between tests, so stubs and recorded calls do not leak. ## Where it fits In a Flutter widget test the mock is handed to the view model — directly, or through whatever dependency injection the app uses — and the widget is pumped with `testWidgets`. The mock only replaces the collaborator; `flutter_test` still drives the widget tree. Keep verification for interactions that *are* the behaviour (the view model fetched once, it did not retry); assert on visible state for everything else, or the test breaks whenever the implementation is refactored.