MockK: Under the cover

Photo by Sander Sammy on Unsplash

The other day, I showed a MockK unit test to a colleague who isn’t familiar with Kotlin. He was stunned by how clean and powerful it was, immediately asking, “How does that work like a charm?”

His question got me wondering if it might be a good topic for another blog post. My first instinct was to write a dive deep into its internals — but soon I realized that MockK is leveraging on other tools to do the magical bytecode level object creation in the runtime.

However, the mock object creation is not the only thing that makes MockK special, it is also about its elegant DSL API. The reason it ‘works like a charm’ is that it’s a masterclass in idiomatic library design that relies heavily on Kotlin.

So, today we’ll focus more on the chance to unveil the API itself and show how it’s built heavily on Kotlin’s best features. We’ll explore how MockK uses DSLs, extension functions, and first-class coroutine support to create an experience that feels less like a third-party tool and more like a native part of the language.

Whether you’re an SDK developer or just a curious Kotlin enthusiast, I hope you’ll find some valuable insights in how this brilliant library exposes its APIs.

mockk

Let’s start with the most-used function: mockk(). In our last blog post: MockK: The basic , we used it in its simplest form:

val loginService = mockk<ILoginService>()

This looks clean and deceptively simple. But to appreciate the Kotlin-centric design, let’s look at its full function signature (or at least, the most important parts):

inline fun <reified T : Any> mockk(
    name: String? = null,
    relaxed: Boolean = false,
    vararg moreInterfaces: KClass<*>,
    relaxUnitFun: Boolean = false,
    mockValidator: MockkValidator = MockkValidator(RestrictMockkConfiguration()),
    block: T.() -> Unit = {},
): T

This signature looks intimidating, but it’s a masterclass in API design. Let’s break down how its use of Kotlin features creates such a lightweight experience.

1. Default Value

Almost every parameter has a default value.

This is the core of Kotlin’s “less boilerplate” philosophy. In a language like Java, you would need multiple “overloaded” methods to achieve this: mockk(T), mockk(T, name), mockk(T, relaxed), mockk(T, name, relaxed). And it also seems a good idea to stick the default value to where the value is treated as default to avoid confusion.(String is null, boolean is false, etc)

Thanks to default parameters, MockK provides one powerful function that remains incredibly lightweight for 90% of use cases. You only specify the parameters you need to change, like mockk<ILoginService>(relaxed = true).

2. inline fun <reified T> (No More .class!)

This is the magic that lets us pass the type. Because we need the actual class type for runtime object creation. and in Java, you have to pass the class object, which leads to the familiar, clunky syntax: mock(ILoginService.class).

Kotlin solves this with inline and reified.

• **reified** is a keyword that makes the generic type T (like our ILoginService) available at runtime.
• **inline** is what makes reified possible. It copies the function's bytecode to the call site, allowing it to access the runtime type.

So here the T is more than just a generic type, it can be used as a class like below:

T::class.java.newInstance()

This feature is the sole reason we can use the clean, angle-bracket syntax: mockk<ILoginService>() ...instead of the Java-style: mockk(ILoginService::class)

It’s a small change in syntax that makes a massive difference in how “native” the API feels.

3. vararg (for Dynamic flexibility)

What if your mock needs to be an ILoginService and also implement IOtherService? The vararg moreInterfaces: KClass<*> parameter handles this.

vararg (variable number of arguments) allows you to pass a dynamic, comma-separated list of extra interfaces. This makes the API incredibly flexible for complex scenarios without cluttering the simple ones. You can pass zero extra interfaces, or five.

// A mock that is both an ILoginService AND an IOtherService
val complexMock = mockk<ILoginService>(
    moreInterfaces = arrayOf(IOtherService::class)
)

4. T.() -> Unit (The DSL Maker)

This might be the most common “Kotlin” feature of all. The final parameter, block: T.() -> Unit = {}, is a function type with a receiver.

This is the secret sauce for creating DSLs.

• T.() means that the lambda block you pass will be executed as if it were a method inside the newly created mock object (T).
• This is why we can “attach a block in the end” and remove the need to specify the object again.

Without this feature, you’d have to write:

val loginService = mockk<ILoginService>()
every { loginService.login(any(), any()) } returns true

But with the lambda receiver, we can combine creation and stubbing into one, concise, readable block:

val loginService = mockk<ILoginService> {
    // We are "inside" the loginService
    // so we can just call 'every' directly
    every { login(any(), any()) } returns true
}

And same thing applies the spyk since it shares the same concept and situation.

every

Besides mockk, every is yet another perfect showcase of idiomatic Kotlin design.

fun <T> every(stubBlock: MockKMatcherScope.() -> T): MockKStubScope<T, T>

At first glance, the function signature looks very simple compared to our previous sample but it actually has a lot to talk about.

1. The DSL Magic: MockKMatcherScope.() -> T

This first parameter, stubBlock, is the secret sauce. It's not a simple lambda; it's a function type with a receiver. But what make it different to our previous example?

MockKMatcherScope.() means the lambda you pass to every (the code inside the { ... }) is executed as if it were a method inside an object of type MockKMatcherScope. It is quite similar to our previous example, and why it’s “charming”?

This is the entire reason you can use matchers like any() and eq() so cleanly!

• any(), eq(), more(), less(), etc., are all methods defined on MockKMatcherScope.
• Because your lambda { loginService.login(any(), any()) } runs inside that scope, you can call any() directly, without any prefixes.
• This is what makes MockK feel so native compared to traditional Java libraries, where you’re forced to call static, verbose functions like Mockito.any() or ArgumentMatchers.eq().

2. The Fluent API: : MockKStubScope<T, T>

The every block doesn't complete the thought; it just starts it. The return type of the function is what enables the clean, fluent "chaining" API that reads just like a sentence.

• What it does: It returns a MockKStubScope object.
• Why it’s charming: This MockKStubScope object is what exposes the functions you chain onto it, such as:
• .returns(value: T)
• .answers(answerBlock: (Call) -> T)
• .throws(exception: Throwable)
• .justRun() (a helper for Unit-returning functions)

This is a classic Fluent Interface (or Builder) pattern. The every { ... } block specifies what call to mock, and the returned object lets you specify what it should do.

And all these returns, answers, etc are infix functions, so it makes the DSL even cleaner.

3. The Compile-Time Safety: fun <T>

Finally, the function is generic (<T>). This T is the return type of the function you're mocking inside the stubBlock.

• What it does: When you write { loginService.login(...) }, the compiler knows that login returns a Boolean. Therefore, the generic type T is inferred to be Boolean.
• Why it’s charming: Because T is now Boolean, the return type MockKStubScope<T, T> becomes MockKStubScope<Boolean, Boolean>. This means the compiler will force you to provide the correct type in the next step.
• every { ... } returns true // Compiles perfectly!
• every { ... } returns "a string" // COMPILE ERROR!

MockK leverages Kotlin’s strong type system to ensure your stubs are type-safe at compile time, saving you from countless simple errors long before you even run your test.

So MockK is not just a powerful Kotlin library, it’s also a great example for people who like to learn how to write clean Kotlin code. I believe it’s a library built for Kotlin lovers, by Kotlin lovers. I hope you feel the same and enjoy the read.