Testing and Mocking Dart Applications

Contents

• Structuring Code for Testability
• Managing Dependencies
• Generating Mocks
• Implementing Unit Tests
• Workflow: Creating and Running Mocked Tests
• Examples

Structuring Code for Testability

Design classes for constructor injection. Mock external I/O (dio, SupabaseClient) at repository/service boundaries — use fakes for repositories in ViewModel tests (see implement-tdd/mocking.md).

• Inject Dio or SupabaseClient through constructors — not Supabase.instance
• Repositories return Future<Result<T, Failure>>

Managing Dependencies

dart pub add dio
dart pub add dev:mockito dev:build_runner

build_runner is allowed for Mockito mocks and freezed — see architecture.mdc.

Generating Mocks

Use package:mockito and build_runner to automatically generate mock classes for fixed scenarios and behavior verification.

• Always use the @GenerateNiceMocks annotation (preferable to @GenerateMocks to avoid missing stub exceptions).
• Place the annotation in the test file, passing a list of MockSpec<Type>() objects.
• Import the generated file using the .mocks.dart extension.
• Execute build_runner to generate the mock files: dart run build_runner build.

Implementing Unit Tests

Isolate the system under test using the generated mock objects. Use package:test to structure the test suite.

• Stubbing: Configure mock behavior before interacting with the system under test.
  • Use when(mock.method()).thenReturn(value) for synchronous methods.
  • CRITICAL: Always use thenAnswer((_) async => value) for methods returning a Future or Stream. Never use thenReturn for asynchronous returns.
• Verification: Assert that the system under test interacted with the mock object correctly.
  • Use verify(mock.method()).called(1) to check exact invocation counts.
  • Use argument matchers like any, anyNamed, or captureAny for flexible verification.

Workflow: Creating and Running Mocked Tests

Use the following checklist to implement and verify mocked unit tests.

Task Progress

• 1. Identify the external dependency to mock (e.g., Dio, SupabaseClient).
• 2. Inject the dependency into the target class constructor.
• 3. Create a test file (e.g., target_test.dart) and add @GenerateNiceMocks([MockSpec<Dependency>()]).
• 4. Add the part or import directive for the generated .mocks.dart file.
• 5. Run dart run build_runner build to generate the mock classes.
• 6. Write the test cases using group() and test().
• 7. Stub required behaviors using when().
• 8. Execute the target method.
• 9. Verify interactions using verify() and assert outcomes using expect().
• 10. Run the test suite using dart test.

Feedback Loop: Test Failures

If tests fail or build_runner encounters errors:

1. Run validator: Execute dart test or dart run build_runner build.
2. Review errors: Check for missing stubs, mismatched argument matchers, or syntax errors in the generated files.
3. Fix:
   • If a mock method throws an unexpected null error, ensure you used @GenerateNiceMocks.
   • If an async stub throws an ArgumentError, change thenReturn to thenAnswer.
   • If build_runner fails, ensure the .mocks.dart import matches the file name exactly.
4. Repeat until all tests pass.

Examples

Repository test with Mockito + dio

1. Service (lib/features/items/data/services/item_api_service.dart)

class ItemApiService {
  ItemApiService(this._dio);
  final Dio _dio;

  Future<List<Map<String, dynamic>>> fetchItems() async {
    final response = await _dio.get('/items');
    return (response.data as List).cast<Map<String, dynamic>>();
  }
}

2. Test (test/features/items/data/services/item_api_service_test.dart)

import 'package:dio/dio.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:mockito/annotations.dart';
import 'package:mockito/mockito.dart';

@GenerateNiceMocks([MockSpec<Dio>()])
import 'item_api_service_test.mocks.dart';

void main() {
  late MockDio mockDio;
  late ItemApiService service;

  setUp(() {
    mockDio = MockDio();
    service = ItemApiService(mockDio);
  });

  test('returns items when dio responds 200', () async {
    when(mockDio.get('/items')).thenAnswer(
      (_) async => Response(
        requestOptions: RequestOptions(path: '/items'),
        statusCode: 200,
        data: [{'id': '1', 'name': 'A'}],
      ),
    );

    final result = await service.fetchItems();

    expect(result, hasLength(1));
    verify(mockDio.get('/items')).called(1);
  });
}

Run dart run build_runner build after adding @GenerateNiceMocks.