Overrides & Containers

## Why overrides make Riverpod testable In Riverpod, **providers hold no state themselves**. State lives in a `ProviderContainer`, and in a Flutter app the `ProviderScope` widget creates that container and exposes it to the widget tree. Because the container is the only place state lives, two things follow for tests: - every test that pumps its own `ProviderScope` starts from fresh state, with nothing carried over from the previous test; - the container accepts an **`overrides`** list, which replaces how chosen providers behave inside that container only. Riverpod's documentation stresses that all providers can be mocked this way by default, without any extra setup in production code — no service locator, no constructor injection through every widget. ## The widget-test recipe For a quiz app whose `QuizScreen` shows questions loaded through a `quizRepositoryProvider`: 1. Define a `FakeQuizRepository` that implements the same interface and returns canned questions. 2. In `testWidgets`, pump `ProviderScope(overrides: [...], child: MaterialApp(home: QuizScreen()))`. 3. Put `quizRepositoryProvider.overrideWithValue(FakeQuizRepository())` in the list. 4. Pump a frame so the fake's future completes, then assert on what the screen shows. Every provider downstream of the repository — a `questionsProvider` that calls `fetchQuestions()`, a notifier that submits answers — now reads the fake, because they obtain the repository with `ref.watch(quizRepositoryProvider)` from the same container. The production `main()` keeps its plain `ProviderScope` with no overrides. ## Which override to use | Method | Receives | Use it when | |---|---|---| | `overrideWithValue(fake)` | a ready-made value | the fake needs nothing from other providers | | `overrideWith((ref) => fake)` | a new create function with full `Ref` access | the fake must watch another provider or register `ref.onDispose` | For a repository, either works; `overrideWithValue` reads more directly. Overriding the **lowest** provider that touches the outside world — HTTP, a database, platform plugins — keeps the rest of the real logic under test. ## Override the dependency, not the notifier Riverpod's testing guide discourages mocking Notifiers. A Notifier cannot be instantiated on its own; it only works when a provider creates it. If you insist, a mock must **extend** the notifier's base class — with codegen, the generated `_$Name` class, which forces the mock into the same file — because implementing the interface breaks it. The recommended route is to put a seam below the notifier: the notifier reads `quizRepositoryProvider`, and the test overrides that. The notifier's real logic, scoring and validation, is then exercised by the test instead of being replaced by it. ## Inspecting providers from the test flutter_riverpod adds `tester.container()` to `WidgetTester`. It finds the `ProviderContainer` of the pumped scope, so a test can call `container.read(scoreProvider)` after tapping an answer, or read `container.read(questionsProvider.future)` to wait for data. Creating a separate `ProviderContainer()` in the test would not help: it is a different container with its own, unrelated state. ## Driving the screen through the fake A fake repository is more than a stub that returns data; it is how the test controls the scenario. A few fakes cover most quiz-screen tests: - a **happy** fake returning two or three questions, to check rendering and navigation between them; - an **empty** fake returning no questions, to check the empty state; - a **failing** fake that throws, to check the error message and the retry button; - a **slow** fake backed by a `Completer`, completed by the test, to check the loading indicator before and the content after. Each one is a few lines, lives in the test folder, and is passed through the same one-line override. Because the production providers stay untouched, the test also verifies the wiring between them — that `questionsProvider` really reads the repository and that the screen really reads `questionsProvider`. ## Pitfalls - **Overriding the wrong provider.** If the screen reads `questionsProvider` and the test overrides a different repository provider than the one `questionsProvider` watches, the real network code still runs. - **Duplicate overrides.** Listing the same provider twice in one container triggers an `AssertionError` in debug mode rather than letting one silently win. - **Leaking fakes between tests.** Building the fake in a shared `setUp` is fine; sharing one container across tests is not. - **Mixing real and fake state.** A fake repository that returns a new list on every call can make equality-filtered providers rebuild more than production does; return stable data.