dart-mocktail

name	dart-mocktail
description	Mocktail testing guidelines for Dart/Flutter. Use when creating mocks, fakes, stubbing async/sync, verifying interactions, registerFallbackValue, or avoiding MissingStub errors.

Dart Mocktail

Fake vs Mock

• Fake: lightweight custom behavior subset; use when asserting on outcomes (result values, state).
• Mock: use when verifying interactions (specific methods called, args, call count).
• Prefer real collaborators or fakes over mocks -- outcome-based tests are more robust.

Mock Creation

• Extend Mock -- never add manual overrides or concrete implementations.

class MockIRepository extends Mock implements IRepository {}

Fallback Values

• Register fallback values for every non-nullable custom type used in matchers (any(), captureAny(), captureThat()).
• Must run before stubbing or verifying -- typically in setUpAll().

setUpAll(() {
  registerFallbackValue(MyDomainType());
  registerFallbackValue(Result.success(dummy));
});

Stubbing

• Sync: when(() => mock.method()).thenReturn(value) for fixed return.
• Sync dynamic: thenAnswer((invocation) => value) for computed response.
• Async: thenAnswer((_) async => result) -- preferred over thenReturn(Future.value(...)).
• Failure: thenThrow(error) for error branches.
• Stub every dependency method the test expects to execute -- unstubbed calls cause MissingStubError.

Verification

• verify(() => mock.method()) -- method was called.
• verifyNever(() => mock.method()) -- method was not called.
• verify(() => mock.method()).called(n) -- assert exact call count.

Parameters and Matchers

• Supply all named parameters in both stubs and verifies; use any(named: 'param') when the exact value is irrelevant.
• any() -- match any positional value.
• captureAny() -- capture argument for later assertion.
• captureThat(matcher) -- capture when matcher matches.

Best Practices

• Custom types used in matchers should have consistent == and toString for deterministic assertions.