mocktail

The mocktail repository provides Dart mocking libraries inspired by mockito. It consists of two primary packages:

1. mocktail: A mocking library designed for Dart with null safety support. It simplifies the mocking process by eliminating the need for manual mocks or code generation.
2. mocktail_image_network: A specialized package used to mock Image.network within widget tests, built to work seamlessly with package:mocktail.

By default, Flutter's TestWidgetsFlutterBinding intercepts all HTTP requests and returns a status code 400. If your widget uses Image.network, the image resource service will throw a NetworkImageLoadException because it cannot reach the URL.

mocktail_image_network provides a controlled environment by mocking the internal HTTP client, preventing these exceptions and allowing your widget tests to pass even when they contain network-dependent images.

When using argument matchers like any() or captureAny() with custom types, mocktail needs a default value to return to avoid type errors. You must register a fallback value for each custom type using registerFallbackValue. It is recommended to do this once per type in a setUpAll block.

class Food {...}
class Cat {
  bool likes(Food food) => true;
}

class MockCat extends Mock implements Cat {}
class FakeFood extends Fake implements Food {}

void main() {
  setUpAll(() {
    registerFallbackValue(FakeFood());
  });

  test('...', () {
    final cat = MockCat();
    when(() => cat.likes(any())).thenReturn(true);
  });
}

Mocktail is designed to be a drop-in replacement for Mockito with a similar API, but it eliminates the need for code generation. When migrating, keep these three key differences in mind:

1. No code generation: Remove @GenerateMocks, build_runner, and any generated .mocks.dart files. Instead, manually create mock classes by extending Mock and implementing the interface.
2. Wrap calls in closures: Unlike Mockito, where you pass the method call directly to when() or verify(), Mocktail requires you to wrap the call in a closure: () => mock.method().
3. Unified matchers: Use unified matchers like any(), any(named: 'param'), and any(that: matcher) instead of type-specific matchers like anyString or argThat.

To create a mock, define a class that extends Mock and implements the interface of the class you want to mock. This approach avoids the need for code generation.

import 'package:mocktail/mocktail.dart';

// A Real Cat class
class Cat {
  String sound() => 'meow!';
  bool likes(String food, {bool isHungry = false}) => false;
  final int lives = 9;
}

// A Mock Cat class
class MockCat extends Mock implements Cat {}

void main() {
  // Create a Mock Cat instance
  final cat = MockCat();
}

When testing Flutter widgets that use Image.network, tests will fail because the TestWidgetsFlutterBinding prevents real network requests, resulting in a NetworkImageLoadException (HTTP 400).

To resolve this, wrap your test logic inside the mockNetworkImages function. This mocks the internal HTTP client used by Image.network, allowing the images to load successfully during the test without making actual network calls.

void main() {
  testWidgets('can use mocktail for network images', (tester) async {
    // Wrap the widget pump in mockNetworkImages
    await mockNetworkImages(() async => tester.pumpWidget(FakeApp()));
    
    expect(find.byType(Image), findsOneWidget);
  });
}

This example demonstrates the transition from a code-generated Mockito setup to a manual Mocktail setup.

// After (mocktail)
import 'package:mocktail/mocktail.dart';

class MockCat extends Mock implements Cat {}

void main() {
  test('sounds', () {
    final Cat cat = MockCat();
    when(() => cat.sound()).thenReturn('meow');
    expect(cat.sound(), 'meow');
    verify(() => cat.sound()).called(1);
  });

  test('eat with matcher', () {
    final Cat cat = MockCat();
    when(() => cat.eat(any(that: startsWith('fish')))).thenAnswer((_) async => 'yum');
    expect(cat.eat('fishy'), completion(equals('yum')));
    verify(() => cat.eat('fishy')).called(1);
  });
}

Use reset(mock) to clear all stubs and recorded interactions for a specific mock instance.

reset(cat); // Reset stubs and interactions