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:

tester.view.physicalSize = const Size(360, 640) * 3;
tester.view.devicePixelRatio = 3;
tester.platformDispatcher.textScaleFactorTestValue = 2.0;
addTearDown(tester.view.reset);
addTearDown(tester.platformDispatcher.clearAllTestValues);

Run this as a real testWidgets case per matrix cell for any screen/component whose layout changed — it is the failing test a layout change starts from (see tdd-first), not an afterthought bolted on once the happy path passes.

Accessibility guidelines (verified)

meetsGuideline from flutter_test/flutter/accessibility, run inside tester.ensureSemantics():

final handle = tester.ensureSemantics();
await expectLater(tester, meetsGuideline(androidTapTargetGuideline));   // 48x48
await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));       // 44x44
await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));   // every tappable has a label
await expectLater(tester, meetsGuideline(textContrastGuideline));
handle.dispose();

Run these against every new or changed interactive widget's test, not just a dedicated accessibility suite.

Golden test pitfalls (verified)

• Fonts: by default, text renders as box glyphs in a golden unless the app's real fonts are loaded in flutter_test_config.dart (loadAppFonts() or equivalent) — a golden taken without that setup locks in boxes, not the real typography. Use goldens for layout/shape verification, or load the fonts first.
• OS differences: text rendering and anti-aliasing differ per OS, so the same golden can legitimately differ on macOS vs Linux CI. Tag golden tests (@Tags(['golden'])) and generate/update them on one OS consistently (match CI's).
• Never --update-goldens to make a red test green without looking at the diff first — that silently accepts a visual regression as the new baseline.

Common Mistakes

• pumpWidget for logic that could be a plain unit test (slow, indirect).
• Asserting widget-tree internals instead of visible behavior.
• No error/empty-state test.
• Golden files regenerated blindly, hiding a visual regression.
• A layout test that only runs at the default device size and text scale 1.0.

Red Flags

• The test passes before the production code exists (tests a fake).
• Every test boots the full app.
• Only the happy path is covered.
• No test exercises text scale 2.0 on a screen that changed layout.