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

• Inject external services (e.g.,

  http.Client

  ) through class constructors.
• Represent URLs strictly as

  Uri

  objects using

  Uri.parse(string)

  .
• Utilize Dart's object-oriented features (classes, mixins) to define clear interfaces for external interactions.

Managing Dependencies

pubspec.yaml

• Add runtime dependencies (e.g.,

  package:http

  ) using

  dart pub add http

  .
• Add testing dependencies using

  dart pub add dev:test dev:mockito dev:build_runner

  .
• Import HTTP libraries with a prefix to avoid namespace collisions:

  import 'package:http/http.dart' as http;

  .

Generating Mocks

package:mockito

build_runner

• 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

package:test

• 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

Task Progress

• 1. Identify the external dependency to mock (e.g.,

  http.Client

  ).
• 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

build_runner

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

High-Fidelity Mocking and Testing Example

lib/api_service.dart

import 'dart:convert';
import 'package:http/http.dart' as http;

class ApiService {
  final http.Client client;

  ApiService(this.client);

  Future<String> fetchData(String urlString) async {
    final uri = Uri.parse(urlString);
    final response = await client.get(uri);

    if (response.statusCode == 200) {
      return jsonDecode(response.body)['data'];
    } else {
      throw Exception('Failed to load data');
    }
  }
}

test/api_service_test.dart

import 'package:test/test.dart';
import 'package:mockito/annotations.dart';
import 'package:mockito/mockito.dart';
import 'package:http/http.dart' as http;
import 'package:my_app/api_service.dart';

// Generate the mock class for http.Client
@GenerateNiceMocks([MockSpec<http.Client>()])
import 'api_service_test.mocks.dart';

void main() {
  group('ApiService', () {
    late ApiService apiService;
    late MockClient mockHttpClient;

    setUp(() {
      mockHttpClient = MockClient();
      apiService = ApiService(mockHttpClient);
    });

    test('returns data if the http call completes successfully', () async {
      // Arrange: Stub the async HTTP GET request using thenAnswer
      when(mockHttpClient.get(any)).thenAnswer(
        (_) async => http.Response('{"data": "Success"}', 200),
      );

      // Act
      final result = await apiService.fetchData('https://api.example.com/data');

      // Assert
      expect(result, 'Success');
      
      // Verify the mock was called with the correct Uri
      verify(mockHttpClient.get(Uri.parse('https://api.example.com/data'))).called(1);
    });

    test('throws an exception if the http call completes with an error', () {
      // Arrange
      when(mockHttpClient.get(any)).thenAnswer(
        (_) async => http.Response('Not Found', 404),
      );

      // Act & Assert
      expect(
        apiService.fetchData('https://api.example.com/data'),
        throwsException,
      );
    });
  });
}