Flutter testing

Flutter Testing — Unit, Widget, Golden

Instructions

Every feature should have tests at three levels: unit (logic), widget (rendering + interaction), and — for critical UI — golden (pixel regression).

1. Unit Tests

• Use package:test / package:flutter_test (both export test, expect, group).
• Mock collaborators with mocktail (preferred — no code-gen) or mockito.

class MockArticleRepo extends Mock implements ArticleRepository {}

void main() {
  late ArticlesNotifier sut;
  late MockArticleRepo repo;

  setUp(() {
    repo = MockArticleRepo();
    when(() => repo.getAll()).thenAnswer((_) async => [fakeArticle]);
  });

  test('loads articles on build', () async {
    final container = ProviderContainer(overrides: [
      articleRepoProvider.overrideWithValue(repo),
    ]);
    addTearDown(container.dispose);

    final value = await container.read(articlesProvider.future);
    expect(value, [fakeArticle]);
  });
}

For BLoC use package:bloc_test:

blocTest<ArticlesCubit, ArticlesState>(
  'emits [loading, data] on load',
  build: () => ArticlesCubit(repo),
  act: (c) => c.load(),
  expect: () => [const ArticlesState.loading(), ArticlesState.data([fakeArticle])],
);

2. Widget Tests

Use testWidgets with WidgetTester:

testWidgets('shows articles', (tester) async {
  await tester.pumpWidget(ProviderScope(
    overrides: [articleRepoProvider.overrideWithValue(repo)],
    child: const MaterialApp(home: ArticlesScreen()),
  ));
  await tester.pumpAndSettle();

  expect(find.text(fakeArticle.title), findsOneWidget);
  await tester.tap(find.byKey(const ValueKey('article-${fakeArticle.id}')));
  await tester.pumpAndSettle();
  // assert navigation result
});

Guidelines:

• Always provide a MaterialApp (or MediaQuery + Directionality) so widgets have required inherited widgets.
• Use find.byKey(...) with stable keys over find.text(...) for robustness against copy changes.
• Use tester.pumpAndSettle() sparingly — it hides timing bugs. Prefer explicit pump(Duration).

3. Golden Tests

For pixel-accurate regressions, use alchemist (preferred, ignores font/platform differences) or golden_toolkit.

goldenTest(
  'ArticleCard renders variants',
  fileName: 'article_card',
  builder: () => GoldenTestGroup(
    children: [
      GoldenTestScenario(name: 'default', child: ArticleCard(article: fakeArticle)),
      GoldenTestScenario(name: 'long title', child: ArticleCard(article: longTitleArticle)),
    ],
  ),
);

• Commit goldens to the repo. Regenerate with flutter test --update-goldens only when the UI intentionally changed.
• Run goldens on a single canonical platform (CI Linux) to avoid per-OS flakiness.

4. Semantics / A11y in Tests

final handle = tester.ensureSemantics();
expect(find.bySemanticsLabel('Add to favorites'), findsOneWidget);
handle.dispose();

5. Test Hygiene

• Each test is independent (setUp rebuilds fresh state; no shared mutable globals).
• Fakes/mocks are reset between tests.
• dispose verified for controllers and subscriptions.
• CI runs flutter test --coverage and publishes the report.
• Goldens run only on a pinned CI image.

6. Running

• Unit + widget: flutter test.
• Coverage: flutter test --coverage → coverage/lcov.info.
• Update goldens: flutter test --update-goldens.
• Single file: flutter test test/features/articles/articles_notifier_test.dart.