mocking-strategies

name	mocking-strategies
description	Guidance on choosing between fakes, stubs, and mocking libraries (MockK, Mockito, mocktail, ts-jest, Swift test doubles) for mobile unit tests. Use when asked to mock a collaborator or to decide which double to use.

Mocking Strategies for Mobile

Instructions

Most "mocking" problems are really design problems: the code under test depends on a concrete implementation instead of an interface, or on a framework class it does not own. Fix the seam first; pick the double second.

1. Hierarchy of Test Doubles

From most preferred to least:

1. Fake — a working in-memory implementation of an interface (e.g., InMemoryUserRepository). Durable, readable, reusable across tests.
2. Stub — returns hard-coded answers to method calls, no behavior.
3. Spy — a real object with selected method interactions recorded.
4. Mock — a test-only object whose interactions are asserted.

Default to fakes for stateful collaborators (repositories, caches, stores) and stubs/mocks only for thin boundary adapters (loggers, analytics, network clients).

2. Do Not Mock What You Do Not Own

Never mock OkHttpClient, URLSession, Dio, fetch, Firebase*, CoreLocation, etc. directly. Wrap them in a seam you own:

interface WeatherApi { suspend fun forecast(city: String): Forecast }
class OkHttpWeatherApi(private val client: OkHttpClient) : WeatherApi { /* ... */ }

Then fake or mock WeatherApi in tests. The wrapper is tested once as an integration test.

3. Library Choices

Kotlin — MockK (preferred) for idiomatic Kotlin including coroutines and top-level functions:

val repo = mockk<UserRepository>()
coEvery { repo.load(id = 42) } returns User("Ada")

Java — Mockito / Mockito-Kotlin:

UserRepository repo = mock(UserRepository.class);
when(repo.load(42)).thenReturn(new User("Ada"));

Swift — manual protocol doubles (preferred):

final class UserRepositoryFake: UserRepository {
    var users: [Int: User] = [:]
    func load(id: Int) async throws -> User {
        guard let u = users[id] else { throw UserError.notFound }
        return u
    }
}

Use Cuckoo or Mockingbird only when the codebase is already committed to them; hand-written doubles usually win on readability.

Dart — mocktail (null-safe, no codegen):

class MockUserRepo extends Mock implements UserRepository {}

final repo = MockUserRepo();
when(() => repo.load(42)).thenAnswer((_) async => User('Ada'));

Prefer mocktail over mockito in new Flutter code — no build_runner step.

TypeScript / Jest:

const repo: jest.Mocked<UserRepository> = {
  load: jest.fn().mockResolvedValue({ name: 'Ada' }),
};

For module-level mocks prefer jest.mock('./module', factory) over auto-mocking; auto-mocks silently drift from the real module.

4. Verify vs Assert

Assert on outputs and observable state by default:

val result = sut.signIn(email, password)
result shouldBe Success(userId = 1)

Verify interactions only when the interaction is the behavior:

verify(exactly = 1) { analytics.track(SignInSucceeded(userId = 1)) }

Every verify you write is a line the next refactor might break without the behavior actually changing. Treat them as expensive.

5. Argument Matchers and Captors

Match only on what matters. any() everywhere hides bugs; over-specific matchers make tests brittle. When you need to inspect a complex argument, use a captor:

val slot = slot<AnalyticsEvent>()
verify { analytics.track(capture(slot)) }
slot.captured.name shouldBe "sign_in_succeeded"

6. Time, Randomness, IDs

These are collaborators. Inject them instead of mocking statics:

class OrderFactory(private val clock: Clock, private val ids: IdGenerator)

Then pass a FixedClock(Instant.parse("2026-01-01T00:00:00Z")) and SequentialIdGenerator() in tests.

7. Common Smells

• Mocking Logger / println — usually unnecessary; if you must, assert on a collected log list, not on call counts.
• Mocking DateTime.now() by patching a global — inject a clock instead.
• Five-deep when { ... } chains — the SUT is doing too much; split it.
• Matching on anyOrNull() for every argument — the test asserts nothing.

8. Checklist

• Third-party SDKs are wrapped before being faked.
• Fakes are used for stateful collaborators; mocks only for interaction verification.
• No static/global clock, RNG, or ID generator reaches the SUT.
• verify calls exist only where the interaction is the behavior.
• Argument matchers are specific enough to catch regressions.
• Chosen library matches the stack (MockK / Mockito / mocktail / Jest / hand-written Swift doubles).