flutter-automated-testing

Goal

Generates, configures, and debugs automated tests for Flutter applications, encompassing unit, widget, integration, and plugin testing. Analyzes architectural components (such as MVVM layers) to produce isolated, mock-driven tests and end-to-end device tests. Assumes a standard Flutter project structure, existing business logic, and familiarity with Dart testing paradigms.

Instructions

1. Determine Test Type (Decision Logic)

Evaluate the user's target code to determine the appropriate testing strategy using the following decision tree:

If verifying a single function, method, ViewModel, or Repository: Implement a Unit Test (Proceed to Step 2).
If verifying a single widget's UI, layout, or interaction: Implement a Widget Test (Proceed to Step 3).
If verifying complete app behavior, routing, or performance on a device: Implement an Integration Test (Proceed to Step 4).
If verifying platform-specific native code (MethodChannels): Implement a Plugin Test (Proceed to Step 5).

STOP AND ASK THE USER: "Which specific class, widget, or flow are we testing today? Please provide the relevant source code if you haven't already."

2. Implement Unit Tests (Logic & Architecture)

Unit tests verify logic without rendering UI. They must reside in the test/ directory and end with _test.dart.

For ViewModels (UI Layer Logic): Fake the repository dependencies. Do not rely on Flutter UI libraries.

import 'package:test/test.dart';
// Import your ViewModel and Fakes here

void main() {
  group('HomeViewModel tests', () {
    test('Load bookings successfully', () {
      final viewModel = HomeViewModel(
        bookingRepository: FakeBookingRepository()..createBooking(kBooking),
        userRepository: FakeUserRepository(),
      );

      expect(viewModel.bookings.isNotEmpty, true);
    });
  });
}

For Repositories (Data Layer Logic): Fake the API clients or local database services.

import 'package:test/test.dart';
// Import your Repository and Fakes here

void main() {
  group('BookingRepositoryRemote tests', () {
    late BookingRepository bookingRepository;
    late FakeApiClient fakeApiClient;

    setUp(() {
      fakeApiClient = FakeApiClient();
      bookingRepository = BookingRepositoryRemote(apiClient: fakeApiClient);
    });

    test('should get booking', () async {
      final result = await bookingRepository.getBooking(0);
      final booking = result.asOk.value;
      expect(booking, kBooking);
    });
  });
}

3. Implement Widget Tests (UI Components)

Widget tests verify UI rendering and interaction. They must reside in the test/ directory and use the flutter_test package.

Use WidgetTester to build the widget.
Use Finder to locate elements (find.text(), find.byKey(), find.byWidget()).
Use Matcher to verify existence (findsOneWidget, findsNothing, findsNWidgets).

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

void main() {
  testWidgets('HomeScreen displays title and handles tap', (WidgetTester tester) async {
    // 1. Setup Fakes and ViewModel
    final bookingRepository = FakeBookingRepository()..createBooking(kBooking);
    final viewModel = HomeViewModel(
      bookingRepository: bookingRepository,
      userRepository: FakeUserRepository(),
    );

    // 2. Build the Widget tree
    await tester.pumpWidget(
      MaterialApp(
        home: HomeScreen(viewModel: viewModel),
      ),
    );

    // 3. Finders
    final titleFinder = find.text('Home');
    final buttonFinder = find.byKey(const Key('increment_button'));

    // 4. Assertions
    expect(titleFinder, findsOneWidget);

    // 5. Interactions
    await tester.tap(buttonFinder);
    await tester.pumpAndSettle(); // Wait for animations/state updates to finish

    expect(find.text('1'), findsOneWidget);
  });
}

4. Implement Integration Tests (End-to-End)

Integration tests run on real devices or emulators. They must reside in the integration_test/ directory.

Ensure integration_test is in dev_dependencies in pubspec.yaml.
Initialize IntegrationTestWidgetsFlutterBinding.

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:my_app/main.dart' as app;

void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  group('End-to-End App Test', () {
    testWidgets('Full flow: tap FAB and verify counter', (WidgetTester tester) async {
      // Load the full app
      app.main();
      await tester.pumpAndSettle();

      // Verify initial state
      expect(find.text('0'), findsOneWidget);

      // Find and tap the FAB
      final fab = find.byKey(const ValueKey('increment'));
      await tester.tap(fab);
      
      // Trigger a frame
      await tester.pumpAndSettle();

      // Verify state change
      expect(find.text('1'), findsOneWidget);
    });
  });
}

5. Implement Plugin Tests (Native & Dart)

If testing a plugin, tests must cover both Dart and Native communication.

Dart Side: Mock the platform channel and call the plugin's public API.
Native Side: Instruct the user to write native tests in the respective directories:
- Android: android/src/test/ (JUnit)
- iOS/macOS: example/ios/RunnerTests/ (XCTest)
- Linux/Windows: linux/test/ (GoogleTest)

6. Validate and Fix (Feedback Loop)

Provide the user with the exact command to run the generated test:

Unit/Widget: flutter test test/your_test_file.dart
Integration: flutter test integration_test/your_test_file.dart

STOP AND ASK THE USER: "Please run the test using the command above and paste the output. If the test fails, provide the stack trace so I can analyze the failure and generate a fix."

Constraints

Single Source of Truth: Do not duplicate state in tests. Always use fakes or mocks for external dependencies (Repositories, Services) to isolate the unit under test.
No Logic in Widgets: When writing widget tests, assume the widget is "dumb". All business logic should be tested via the ViewModel/Controller unit tests.
File Naming: All test files MUST end with _test.dart.
Pump vs PumpAndSettle: Use tester.pump() for single frame advances. Use tester.pumpAndSettle() strictly when waiting for animations or asynchronous UI updates to complete.
Immutability: Treat test data models as immutable. Create new instances for state changes rather than mutating existing mock data.
Do not use dart:mirrors: Flutter does not support reflection. Rely on code generation (e.g., build_runner, mockito, mocktail) for mocking.

flutter-testing