Mocking With Mockk

Mocking with MockK — The Kotlin-First Mocking Stack

MockK is the Kotlin-first alternative to Mockito. Its headline wins are native suspend support (coEvery / coVerify with no runBlocking dance), first-class singleton / object / static / constructor mocking, and Kotlin-native syntax (every { … } returns x). The trade-off: androidx itself does NOT use MockK (a grep -r "io.mockk" over the AOSP checkout returns zero hits — see ../mocking-with-mockito/SKILL.md for the dominant pattern). New Kotlin code outside Google often picks MockK; new Kotlin code inside Google or matching AOSP conventions picks Mockito. Both are valid.

When to use this skill

• The codebase is Kotlin-only and dominated by suspend functions / coroutines, and the user wants ergonomic suspend stubbing.
• The user needs to mock a Kotlin object (singleton), companion object, top-level function (Kt-suffixed file), or every newly-constructed instance of a class.
• The user wants strict-by-default verification with the option to opt out per-mock via relaxed = true / relaxUnitFun = true.
• The user wants slot<T>() capture with slot.captured (cleaner than Mockito's ArgumentCaptor).
• The user is writing tests for viewModelScope, Flow collectors, LaunchedEffect-style suspend collaborators.

When NOT to use this skill

• The codebase is mixed Java/Kotlin or already standardized on Mockito. Use ../mocking-with-mockito/SKILL.md. Do not migrate without a reason — both frameworks are valid.
• The user is matching AOSP / androidx conventions (which are Mockito-only). Use ../mocking-with-mockito/SKILL.md.
• Behaviour matters more than interactions, e.g. a Repository with caching logic — write a fake instead. See ../../../fundamentals/doubles/picking-test-doubles/SKILL.md (Google explicitly prefers fakes per /test-doubles).
• The runner / Gradle matrix isn't set up yet — start with ../../runner/configuring-junit4-on-android/SKILL.md.
• The user is testing Flow emissions over time — pair MockK with Turbine. See ../../coroutines/testing-flows-with-turbine/SKILL.md.
• The user needs runTest semantics — see ../../coroutines/testing-coroutines-with-runtest/SKILL.md.

Prerequisites

• The base test wiring from ../../runner/configuring-junit4-on-android/SKILL.md is already in place.
• A MainDispatcherRule is installed if any code-under-test touches Dispatchers.Main — see the runner skill.
• For instrumented MockK (Android runtime), the device must be API 21+ (MockK supports back to API 21 on dexmaker).

Workflow

• 1. Add the MockK coordinates. Pin to a specific 1.14.x version (current latest at the time of writing):

dependencies {
    // JVM unit tests (src/test/)
    testImplementation("io.mockk:mockk-jvm:1.14.0")

    // Instrumented tests (src/androidTest/) — different artifact + agent
    androidTestImplementation("io.mockk:mockk-android:1.14.0")
    androidTestImplementation("io.mockk:mockk-agent:1.14.0")
}

mockk-android swaps the bytecode-generation backend so MockK runs inside Dalvik/ART where stock ByteBuddy doesn't work. Use mockk-jvm (NOT mockk-android) for src/test/ Robolectric tests — Robolectric runs on the JVM.

• 2. Wire mocks via MockKAnnotations.init(this) or direct mockk<T>() construction. The annotation route reads cleaner for tests with many mocks; direct construction wins for one-off mocks:

import io.mockk.MockKAnnotations
import io.mockk.impl.annotations.MockK
import io.mockk.impl.annotations.RelaxedMockK
import io.mockk.impl.annotations.SpyK
import io.mockk.impl.annotations.InjectMockKs

@RunWith(AndroidJUnit4::class)
class UserViewModelTest {
    @get:Rule val mainDispatcherRule = MainDispatcherRule()

    @MockK lateinit var repo: UserRepository
    @RelaxedMockK lateinit var logger: Logger
    @SpyK var realClock: Clock = SystemClock()
    @InjectMockKs lateinit var subject: UserViewModel

    @Before fun setUp() = MockKAnnotations.init(this, relaxUnitFun = true)
    @After fun tearDown() = unmockkAll()   // see step 5 — cleanup global hooks
}

MockKAnnotations.init does not itself install global hooks (mockkStatic / mockkObject / mockkConstructor); but if the test class adds any of those, the @After unmockkAll() is needed to prevent leakage into sibling tests. JUnit5's MockKExtension does this automatically — JUnit4 does not.

Direct construction:

val car = mockk<Car>(
    name = "carA",
    relaxed = false,
    relaxUnitFun = true,           // Unit-returning calls auto-relax; reference returns still throw
    moreInterfaces = arrayOf(Comparable::class),
)

• 3. Stub with every { … } returns … for plain functions and coEvery { … } returns … for suspend. This is the headline ergonomic win over Mockito — no runBlocking { whenever(...) } wrap is needed for suspend stubs:

import io.mockk.coEvery
import io.mockk.coVerify
import io.mockk.every
import io.mockk.verify

every { car.drive(Direction.NORTH) } returns Outcome.OK
every { car.brake() } throws IllegalStateException("frozen")
every { car.gear } returnsMany listOf(1, 2, 3)              // sequence
every { car.compute(any()) } answers { firstArg<Int>() * 2 }

// Suspend — the big win:
coEvery { repo.fetchUser(1) } returns User("Jane")
coEvery { repo.observeUser(1) } returns flowOf(User("Jane"))

• 4. Verify interactions with verify { … }, coVerify { … }, and the strict variants. MockK's verifiers are richer than Mockito's:

verify { car.drive(Direction.NORTH) }
verify(exactly = 2) { car.drive(any()) }
verify(exactly = 0) { car.brake() }                          // = never
verify(atLeast = 1, atMost = 3) { car.drive(any()) }

verifyAll { /* must list every interaction — exhaustive, unordered */ }
verifySequence { /* every interaction in this exact order */ }
verifyOrder { /* listed interactions occurred in this order, others may also have happened */ }

coVerify(exactly = 1) { repo.fetchUser(1) }

confirmVerified(car)                                         // strict: nothing else was invoked

confirmVerified is the safety net to catch silent extra interactions — pair it with verifyAll/verifySequence for a fully constrained test.

• 5. Capture arguments with slot<T>(). Cleaner than Mockito's captor — slot.captured is a property:

import io.mockk.slot

val slot = slot<User>()
every { repo.save(capture(slot)) } returns Unit

subject.register(User("Jane"))

assertEquals("Jane", slot.captured.name)

// Multiple captures over a sequence of calls:
val users = mutableListOf<User>()
every { repo.save(capture(users)) } returns Unit
// ... many calls ...
assertEquals(3, users.size)

• 6. Use relaxed = true or relaxUnitFun = true deliberately. MockK is strict by default — any unstubbed call throws MockKException. The two relaxation modes:

  • relaxed = true — every unstubbed call returns a type-default value (0, false, empty string, nested mock for reference types). Cuts boilerplate but hides bugs.
  • relaxUnitFun = true — only Unit-returning calls auto-relax; reference returns still throw. Recommended middle ground for logger / metrics / framework-callback collaborators.

val logger = mockk<Logger>(relaxed = true)             // any call -> default
logger.info("anything")                                // no every{} needed
val n = logger.lineCount                               // returns 0

val analytics = mockk<Analytics>(relaxUnitFun = true)  // safer middle ground
analytics.track(Event("foo"))                          // OK — Unit return is relaxed
analytics.session                                      // throws — reference return needs every{}

• 7. Mock singletons / statics / constructors with mockkObject / mockkStatic / mockkConstructor — and ALWAYS clean up. These install GLOBAL hooks that persist beyond the current test unless explicitly unmocked. Leakage across tests is the #1 MockK footgun.

import io.mockk.mockkObject
import io.mockk.mockkStatic
import io.mockk.mockkConstructor
import io.mockk.unmockkAll

@After fun tearDown() = unmockkAll()    // belt-and-braces cleanup

@Test fun mocksObject() {
    mockkObject(MySingleton)
    every { MySingleton.flag } returns true
    // ... assertions ...
}

@Test fun mocksTopLevel() {
    // Kotlin top-level functions compile as static methods on the file's *Kt class.
    mockkStatic("com.example.UtilsKt")
    every { hashSomething(any()) } returns "deadbeef"
}

@Test fun mocksJavaStatic() {
    mockkStatic(System::class)
    every { System.currentTimeMillis() } returns 0L
}

@Test fun mocksConstructor() {
    mockkConstructor(OkHttpClient::class)
    every { anyConstructed<OkHttpClient>().newCall(any()) } returns fakeCall
}

The JUnit5 MockKExtension auto-cleans, but JUnit4 tests must call unmockkAll() in @After.

• 8. Verify the test runs and the strict-mode failures actually fire. ./gradlew :<module>:testDebugUnitTest --tests <YourTestClass>. A passing test that uses verifyAll / verifySequence / confirmVerified on a strict mock means every interaction is accounted for. If MockK throws MockKException: no answer found for: …, the SUT is calling something the test didn't stub — either stub it, relax the mock, or fix the SUT.

Patterns

Pattern: WRONG vs RIGHT — suspend stubbing

// WRONG
every { mock.suspendFn() } returns x
// WRONG because: every { } produces a non-suspend stub. At call time MockK throws
// MockKException because the actual call carries a Continuation argument that
// every {} did not match against. This is the #1 trip-up when migrating from Mockito.

// RIGHT
coEvery { mock.suspendFn() } returns x
coVerify { mock.suspendFn() }