flutter-widget-testing

When to Use

• Testing UI components (atoms, molecules, organisms, templates, pages)
• Testing widget rendering, layout, and text content
• Testing user interactions (tap, scroll, enter text, drag)
• Creating golden tests for visual regression
• Verifying accessibility (semantics, labels)
• Testing widgets that use Riverpod providers
• Testing navigation and routing behavior

Critical Patterns

| Pattern | Rule | |---------|------| | Test FIRST | Write the failing widget test before the widget. Red -> Green -> Refactor. | | Wrap with app shell | Always wrap tested widgets in MaterialApp or the Forui theme equivalent | | pump vs pumpAndSettle | pump() advances one frame; pumpAndSettle() waits for all animations | | Finders are lazy | find.text('X') doesn't search until used in expect() or tester.tap() | | Golden tests pinned | Update goldens explicitly with --update-goldens; never auto-update in CI | | Test behavior, not pixels | Prefer semantic finders (find.text, find.byType) over pixel coordinates | | Riverpod: use ProviderScope | Wrap widget in ProviderScope with overrides for test isolation |

Test Directory Structure

mobile/
  test/
    shared/
      presentation/
        atoms/
          app_button_test.dart
          app_text_field_test.dart
          app_badge_test.dart
        molecules/
          emphasis_headline_test.dart
        organisms/
          pet_emoji_carousel_test.dart
    features/
      auth/
        presentation/
          pages/
            welcome_page_test.dart
          widgets/
            auth_sheet_test.dart
    goldens/                    # Golden reference images
      shared/
        atoms/
          app_button_light.png
          app_button_dark.png
      features/
        auth/
          welcome_page_light.png
    helpers/
      pump_app.dart             # Shared widget wrapper helper
      test_theme.dart           # Theme setup for tests

Widget Test Wrapper Helper

Every widget test needs a proper app shell with theme. Create a shared helper:

See assets/pump_app.dart

Atom Tests (Simple Widgets)

See assets/app_button_test.dart

Text Field Tests

See assets/app_text_field_test.dart

Interaction Tests

See assets/interaction_tests.dart

Page Tests with Riverpod

See assets/welcome_page_test.dart

Navigation Tests

See assets/navigation_test.dart

Golden Tests (Visual Regression)

See assets/golden_test.dart

Accessibility Tests

See assets/accessibility_test.dart

Finders Reference

| Finder | Use For | |--------|---------| | find.text('X') | Find widget displaying exact text | | find.textContaining('X') | Find widget containing text | | find.byType(AppButton) | Find widget by runtime type | | find.byKey(Key('x')) | Find widget by key | | find.byIcon(Icons.home) | Find widget by icon | | find.descendant(of: x, matching: y) | Find widget nested inside another | | find.ancestor(of: x, matching: y) | Find parent widget | | find.byWidgetPredicate((w) => ...) | Custom predicate | | find.bySemanticsLabel('X') | Find by accessibility label |

Matchers Reference

| Matcher | Verifies | |---------|----------| | findsOneWidget | Exactly one match | | findsNothing | No matches | | findsNWidgets(n) | Exactly N matches | | findsAtLeastNWidgets(n) | At least N matches | | matchesGoldenFile('path') | Visual match against golden |

Commands

# Run all widget tests
flutter test

# Run specific widget test
flutter test test/shared/presentation/atoms/app_button_test.dart

# Update golden files (run locally, commit the PNGs)
flutter test --update-goldens

# Update specific golden
flutter test --update-goldens test/shared/presentation/atoms/app_button_golden_test.dart

# Run with coverage
flutter test --coverage

# Run tests matching name
flutter test --name "AppButton"

Dev Dependencies

See assets/pubspec_dev_deps.yaml

Anti-Patterns

| Don't | Do | |-------|-----| | Test without app shell/theme | Always use pumpApp() helper with Forui theme | | Use find.byType(Text) broadly | Use find.text('specific text') for precision | | Forget pump() after interactions | Always pump() or pumpAndSettle() after tap/input | | Hardcode pixel positions | Use semantic finders | | Update goldens in CI | Only update locally, review diffs, commit PNGs | | Test Forui internals | Test YOUR widget's behavior, not Forui's | | Skip dark mode tests | Test both light and dark themes | | Forget to dispose controllers | Use addTeardown or dispose in tearDown |