Mockito for Dart

Mockito cannot mock static methods, constructors, or top-level functions because it relies on overriding class instance methods via noSuchMethod.

To make your code testable, consider these refactoring patterns:

1. Dependency Injection: Instead of constructing an object inside a function, pass the object as an argument.

// BEFORE: Un-mockable constructor call
void f() {
  var foo = Foo();
  // ...
}

// AFTER: Inject the dependency
void f(Foo foo) {
  // ...
}

In your test, you can then pass a MockFoo instance to f.

2. Wrapper Systems: Use a wrapper or a service to abstract away static/global calls. For example, instead of using Directory.current or File(), use the file package's FileSystem abstraction, which allows you to swap a LocalFileSystem for a MemoryFileSystem during tests.

Mockito uses ArgMatcher to allow flexible matching of arguments in when() and verify().

Important Constraints:

• You cannot use null as an argument adjacent to an ArgMatcher (e.g., verify(cat.hunt(argThat(contains('yard')), null)) is invalid).
• To match null, you must wrap it in a matcher like argThat(isNull).
• For named arguments, you must explicitly provide the name of the argument to the matcher.

// Using matchers
when(cat.eatFood(any)).thenReturn(false);
when(cat.eatFood(argThat(startsWith("dry")))).thenReturn(false);

// Named arguments REQUIRE the name
when(cat.eatFood(any, hungry: anyNamed('hungry'))).thenReturn(true);
when(cat.eatFood(any, hungry: argThat(isNotNull, named: 'hungry'))).thenReturn(false);

// Handling nulls with matchers
verify(cat.hunt(argThat(contains("yard")), argThat(isNull))); // OK

Mockito provides two ways to generate mocks, which differ in their "missing stub" behavior (what happens when a method is called without a corresponding when(...) declaration):

• @GenerateNiceMocks (Recommended): Returns a "simple" legal value (e.g., a non-null value for a non-nullable return type) to avoid runtime type exceptions. These values should not be relied upon for logic.
• @GenerateMocks: Throws an exception if a method is called without a stub.

Follow these guidelines to ensure reliable and maintainable tests:

• Prefer real objects: If you can construct a real instance, do so. Use mocks only when necessary.
• Use Fakes over Mocks: A tested implementation of a Fake is often better than a Mock because it behaves more like the real class.
• Don't stub in constructors: A class extending Mock should never use when inside its own constructor. Define stubs within the test where they are used.
• Keep Mocks pure: A class extending Mock should not have any implementation (no @override methods or mixins) other than static utilities. Mixing manual overrides with Mockito's stubbing leads to confusion and prevents Mockito from tracking/verifying calls correctly.
• Data models: Never mock data models; construct them with real or stubbed data instead.

When upgrading to Mockito 3, any matcher used as a named argument must be updated to include the argument name as a String.

Rules for named arguments:

• foo: any $\rightarrow$ foo: anyNamed('foo')
• foo: argThat(...) $\rightarrow$ foo: argThat(..., named: 'foo')
• foo: captureAny $\rightarrow$ foo: captureAnyNamed('foo')
• foo: captureThat(...) $\rightarrow$ foo: captureThat(..., named: 'foo')

Rules for removing typed wrappers:

• typed(any) $\rightarrow$ any
• foo: typed(any, named: 'foo') $\rightarrow$ foo: anyNamed('foo')

Rule for nulls:

• Any bare null argument should be rewritten as argThat(isNull).

Mockito 5.0.0+ uses code generation to support Dart null safety. To generate mock classes, use the @GenerateNiceMocks annotation (recommended) or @GenerateMocks on an import statement.

1. Add build_runner to your dev_dependencies in pubspec.yaml.
2. Annotate the import of your generated .mocks.dart file.
3. Run the build command to generate the mock classes.

Note: By default, Mockito only processes annotations in files under test/. To use them elsewhere, you must configure a build.yaml file.

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

// Annotation which generates the cat.mocks.dart library and the MockCat class.
@GenerateNiceMocks([MockSpec<Cat>()])
import 'cat.mocks.dart';

class Cat {
  String sound() => "Meow";
  // ...
}

void main() {
  var cat = MockCat();
}

dart run build_runner build