flutter_test_helpers #

A comprehensive Flutter package providing mock data generators, test utilities, and widget testing helpers to streamline your Flutter testing workflow.

Features #

• 🎲 Mock Data Generators: Generate random test data for colors, strings, numbers, dates, and more
• 🧪 Test Utilities: Helper functions for common testing scenarios
• 🎯 Widget Testing Helpers: Extensions and utilities for widget testing
• 🔧 Extensions: Useful extensions for common Flutter types (Color, String, DateTime, List)
• 🌍 Multi-Platform Support: Supports all 6 platforms (iOS, Android, Web, Windows, macOS, Linux)
• ⚡ WASM Compatible: Ready for Flutter WebAssembly
• 📱 Flutter 3.10+: Built with the latest Flutter features

Getting Started #

Installation #

Add flutter_test_helpers to your pubspec.yaml:

dependencies:
  flutter_test_helpers: ^0.0.3

Import #

import 'package:flutter_test_helpers/flutter_test_helpers.dart';

Usage #

Mock Data Generators #

Generate random test data for your tests:

// Generate random colors
final color = MockDataGenerators.randomColor();
final colorList = MockDataGenerators.randomColorList(5);

// Generate random strings
final string = MockDataGenerators.randomString(15);
final stringList = MockDataGenerators.randomStringList(3);

// Generate random numbers
final intValue = MockDataGenerators.randomInt(1, 100);
final doubleValue = MockDataGenerators.randomDouble(0.0, 1.0);

// Generate random dates
final date = MockDataGenerators.randomDate();

// Generate random booleans
final boolValue = MockDataGenerators.randomBool();

Test Utilities #

Create test apps and wait for conditions:

// Create a test app
final app = TestUtilities.createTestApp(MyWidget());
final themedApp = TestUtilities.createTestAppWithTheme(MyWidget(), myTheme);

// Wait for conditions
await TestUtilities.waitForCondition(() => someCondition);

// Find widgets
final finder = TestUtilities.findByKey(Key('my-key'));
final textFinder = TestUtilities.findByText('Hello World');

// Interact with widgets
await TestUtilities.tap(tester, finder);
await TestUtilities.enterText(tester, finder, 'New Text');
await TestUtilities.scrollTo(tester, finder);

Widget Testing Helpers #

Create specialized test widgets:

// Create padded widget
final paddedWidget = WidgetTestingHelpers.createPaddedWidget(
  MyWidget(),
  padding: EdgeInsets.all(16.0),
);

// Create constrained widget
final constrainedWidget = WidgetTestingHelpers.createConstrainedWidget(
  MyWidget(),
  maxWidth: 300,
  maxHeight: 200,
);

// Create themed widget
final themedWidget = WidgetTestingHelpers.createThemedWidget(
  MyWidget(),
  theme: ThemeData(primarySwatch: Colors.blue),
);

// Create localized widget
final localizedWidget = WidgetTestingHelpers.createLocalizedWidget(
  MyWidget(),
  locale: Locale('en', 'US'),
);

// Create media query widget
final mediaQueryWidget = WidgetTestingHelpers.createMediaQueryWidget(
  MyWidget(),
  screenSize: Size(800, 600),
  devicePixelRatio: 2.0,
);

Extensions #

Use helpful extensions on common Flutter types:

// Color extensions
final lighterColor = Colors.blue.lighten(0.2);
final darkerColor = Colors.blue.darken(0.2);
final contrastColor = Colors.blue.contrastColor;
final hexString = Colors.red.toHex();

// String extensions
final capitalized = 'hello'.capitalize; // 'Hello'
final titleCase = 'hello world'.titleCase; // 'Hello World'
final truncated = 'long text'.truncate(5); // 'lo...'
final isValidEmail = 'test@example.com'.isEmail; // true

// DateTime extensions
final isToday = someDate.isToday;
final startOfDay = someDate.startOfDay;
final relativeTime = someDate.relativeTime; // '2 hours ago'

// List extensions
final randomElement = [1, 2, 3, 4, 5].random;
final shuffled = [1, 2, 3, 4, 5].shuffled;
final firstOrNull = [].firstOrNull; // null

WidgetTester Extensions #

Use convenient extensions on WidgetTester:

// Tap by key, text, or type
await tester.tapByKey(Key('my-button'));
await tester.tapByText('Click me');
await tester.tapByType<ElevatedButton>();

// Enter text by key or type
await tester.enterTextByKey(Key('my-field'), 'Hello');
await tester.enterTextByType<TextField>('World');

// Scroll to widgets
await tester.scrollToKey(Key('my-widget'));
await tester.scrollToText('Hidden text');

// Wait for widgets
await tester.waitForWidget(find.byType(MyWidget));
await tester.waitForWidgetToDisappear(find.byType(LoadingWidget));

Finder Extensions #

Use helpful extensions on Finder:

// Check finder state
if (finder.hasOne) {
  // Exactly one widget found
}
if (finder.hasMultiple) {
  // Multiple widgets found
}

// Get widgets and elements
final widget = finder.firstWidget;
final allWidgets = finder.allWidgets;
final element = finder.firstElement;
final allElements = finder.allElements;

Example Test #

Here's a complete example of how to use flutter_test_helpers in your tests:

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_test_helpers/flutter_test_helpers.dart';

void main() {
  group('MyWidget Tests', () {
    testWidgets('should display and handle interactions', (WidgetTester tester) async {
      // Create test app with helpers
      final app = TestUtilities.createTestApp(
        WidgetTestingHelpers.createPaddedWidget(
          MyWidget(
            title: MockDataGenerators.randomString(10),
            color: MockDataGenerators.randomColor(),
          ),
        ),
      );

      await tester.pumpWidget(app);

      // Use helper methods to find and interact
      final titleFinder = TestUtilities.findByText('My Widget');
      expect(titleFinder, findsOneWidget);

      // Use extensions for easier interaction
      await tester.tapByKey(Key('action-button'));
      await tester.pumpAndSettle();

      // Wait for state changes
      await tester.waitForWidget(find.byType(SuccessWidget));
    });
  });
}

Platform Support #

This package supports all Flutter platforms:

• ✅ iOS - Full support
• ✅ Android - Full support
• ✅ Web - Full support
• ✅ Windows - Full support
• ✅ macOS - Full support
• ✅ Linux - Full support
• ✅ WASM - Compatible with Flutter WebAssembly

Requirements #

• Flutter: >=3.10.0
• Dart: >=3.0.0
• Flutter Test: Included in Flutter SDK

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Author #

Dhia Bechattaoui

• GitHub: @Dhia-Bechattaoui

Support #

If you encounter any issues or have questions, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue

Made with ❤️ for the Flutter community