flutter-testing

Flutter Testing

Overview

Test-first in Flutter (see tdd-workflow). Three layers, each for a different question: does the logic work, does the widget behave, does it look right.

Core principle: Most tests are fast unit + widget tests. Golden tests guard appearance; integration tests guard whole flows — use them sparingly.

Test layers

Layer	Question	Tool
Unit	Does the controller/logic compute correctly?	flutter_test, mock the repository
Widget	Does the widget render state and respond to taps?	testWidgets + pumpWidget + finders
Golden	Does it match the approved pixels?	matchesGoldenFile
Integration	Does the whole flow work on a device?	integration_test

Widget test example

testWidgets('shows error view and retries', (tester) async {
  final controller = FakeTaskController()..emitError('boom');
  await tester.pumpWidget(wrap(TaskListScreen(controller: controller)));
  await tester.pump();

  expect(find.text('boom'), findsOneWidget);
  await tester.tap(find.byType(RetryButton));
  await tester.pump();
  expect(controller.loadCalled, isTrue);   // intent reached the controller
});

Rules

• Unit-test controllers/logic without pumping a widget — that's the payoff of keeping logic out of widgets (see flutter-state-management).
• Widget tests assert observable behavior (text visible, tap triggers intent), not internal structure.
• Mock the repository/ports, not the widget under test. Prefer a hand-written fake or mocktail per the app's convention.
• Golden tests: commit the golden, review changes deliberately; regenerate only when the change is intended.
• Cover loading, data, empty, and error states — the branches most likely to ship broken.
• pump vs pumpAndSettle: use pump for controlled frames, pumpAndSettle to drain animations — never rely on real timers.

Matrix test: size, text scale, dark mode

A widget test that only runs at the default size and text scale misses the most common mobile layout bug — overflow at larger text scales. See mobile-visual-self-review for the full size matrix and the worked PriceRow example (verified: passes at text scale 1.0 everywhere, overflows by 82px at 360×640/2.0). The shape: