Setup and verification
Flutter 3.41.5 or newer with Dart 3.11. Python 3 is also required for the common verification entry point. Extract the learning package into a new folder and run python3 run_checks.py there. The script copies the included files into a temporary learning directory. It verifies the example and then the supplied solution there, preserving the original files. Required packages are downloaded on the first run.
Verified on 2026-10-20 on Linux x86_64. The fake fails on its first read and returns data on the second attempt. Check the transition from error to data and the repository call count.
Asynchronous state has more than one valid value. An interface also needs to explain waiting and failure. The provider owns the state machine. A repository returns data or an error. Automatic retry is disabled in this learning project so each test can observe exactly one attempt.
Package contents and individual files
01Define the boundary
AsyncValue separates loading, data and failure. The notifier owns the read operation. The UI selects its message and retry action from that state. A guard prevents overlapping retries.
import 'package:flutter_riverpod/flutter_riverpod.dart';
abstract interface class VehicleReader {
Future<List<String>> read();
}
class DemoReader implements VehicleReader {
int attempts = 0;
@override
Future<List<String>> read() async {
attempts++;
if (attempts == 1) throw StateError('Storage unavailable');
return ['Family car'];
}
}
final readerProvider = Provider<VehicleReader>((ref) => DemoReader());
final vehiclesProvider = AsyncNotifierProvider<Vehicles, List<String>>(
Vehicles.new,
retry: (_, _) => null,
);
class Vehicles extends AsyncNotifier<List<String>> {
@override
Future<List<String>> build() => ref.watch(readerProvider).read();
Future<void> retry() async {
state = const AsyncLoading();
state = await AsyncValue.guard(() => ref.read(readerProvider).read());
}
}
02Set up the learning project
Direct dependencies are pinned. Extract all files together and run flutter pub get. Do not use an existing app database for tests. Tests create and clean up their own data.
name: learning_example
publish_to: none
environment:
sdk: ">=3.11.0 <4.0.0"
dependencies:
flutter:
sdk: flutter
flutter_riverpod: 3.3.1
drift: 2.33.0
path_provider: 2.1.5
dev_dependencies:
flutter_test:
sdk: flutter
flutter:
uses-material-design: true
03Trace the successful outcome
The fake fails on its first read and returns data on the second attempt. Check the transition from error to data and the repository call count.
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:learning_example/model.dart';
void main() {
test(
'failed read can be retried without recreating the repository',
() async {
final reader = DemoReader();
final container = ProviderContainer(
overrides: [readerProvider.overrideWithValue(reader)],
);
addTearDown(container.dispose);
expect(container.read(vehiclesProvider).isLoading, isTrue);
await expectLater(
container.read(vehiclesProvider.future),
throwsStateError,
);
expect(reader.attempts, 1);
expect(container.read(vehiclesProvider).hasError, isTrue);
await container.read(vehiclesProvider.notifier).retry();
expect(container.read(vehiclesProvider).requireValue, ['Family car']);
expect(reader.attempts, 2);
},
);
}
Run / check
flutter pub get
flutter testThe fake fails on its first read and returns data on the second attempt. Check the transition from error to data and the repository call count.
04Observe failures deliberately
Change an expected number or state in the test. flutter test must fail. Restore the correct expectation afterwards. Distinguish a domain failure from a missing plugin or development environment.
05Solve the extension
Add a second record and verify both are returned after retry.
06Compare the solution
The repository contract stays unchanged. The solution extends the confirmed value and checks its complete order. An error remains an error instead of becoming an empty list.
flutter test passes for the original example and the extended solution.
Your exercise
Add a second record and verify both are returned after retry.
Show the solution and explanation
The repository contract stays unchanged. The solution extends the confirmed value and checks its complete order. An error remains an error instead of becoming an empty list.
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:learning_example/model.dart';
void main() {
test(
'failed read can be retried without recreating the repository',
() async {
final reader = ExtendedReader();
final container = ProviderContainer(
overrides: [readerProvider.overrideWithValue(reader)],
);
addTearDown(container.dispose);
expect(container.read(vehiclesProvider).isLoading, isTrue);
await expectLater(
container.read(vehiclesProvider.future),
throwsStateError,
);
expect(reader.attempts, 1);
expect(container.read(vehiclesProvider).hasError, isTrue);
await container.read(vehiclesProvider.notifier).retry();
expect(container.read(vehiclesProvider).requireValue, [
'Family car',
'Motorbike',
]);
expect(reader.attempts, 2);
},
);
}
class ExtendedReader extends DemoReader {
@override
Future<List<String>> read() async {
final rows = await super.read();
return [...rows, 'Motorbike'];
}
}
Project context and sources
This independent learning project explores a topic in this technology area. Project references provide a pinned revision as architectural context. They do not imply that every library or feature introduced here is already used in that application.