Mokkery Documentation

Mokkery provides four modes to handle calls to functions or properties that have no defined behavior. You can specify the mode when creating a mock or set a global default.

Available Modes

• strict: (Default) Throws a runtime exception if a member is called without a defined answer.
• autoUnit: Like strict, but does not fail for functions returning Unit.
• autofill: Returns default empty values (e.g., 0 for numbers, "" for strings, null for complex types).
• original: Calls the super implementation if available (e.g., a default implementation in an interface). Otherwise, it fails.

Usage

Per-mock configuration:

import dev.mokkery.MockMode.strict
import dev.mokkery.MockMode.autoUnit
import dev.mokkery.MockMode.autofill
import dev.mokkery.MockMode.original

val foo = mock<Foo>(strict)

Global default configuration:

mokkery {
    defaultMockMode.set(MockMode.autoUnit)
}

The Answers API allows you to define custom behavior by implementing the Answer<T> interface and registering it via AnsweringScope.answers.

Core Concepts

• Answer<T>: Represents custom behavior. It must implement call(MokkeryBlockingCallScope) for regular functions and call(MokkerySuspendCallScope) for suspend functions.
• AnsweringScope<T>: The scope where answers are registered.
• Type Safety: To prevent registering a suspend-only answer on a blocking call, Mokkery uses marker interfaces:
  • BlockingAnsweringScope: Returned by every.
  • SuspendAnsweringScope: Returned by everySuspend.

Best Practices for Custom Answers

1. Use existing answers: Instead of implementing Answer from scratch, use calls { ... } inside an extension function to reuse built-in logic.
2. Implement description(): Override description() in your Answer implementation to provide human-readable output for debugging (e.g., with printMokkeryDebug).
3. Use Helper Interfaces: When implementing Answer, use these to reduce boilerplate:
   • Answer.Suspending: For suspend-only answers (throws exception on blocking calls).
   • Answer.Blocking: For blocking-only answers (throws exception on suspend calls).
   • Answer.Unified: For logic that applies to both contexts (implements a single MokkeryCallScope overload).

Example: Creating a custom suspend-only answer

// 1. Define the Answer implementation
private class ReturnsDelayedAnswer<T>(private val value: T) : Answer<T> {
    public fun call(scope: MokkeryBlockingCallScope): T = error("Not supported")

    public suspend fun call(scope: MokkerySuspendCallScope): T {
        delay(1_000)
        return value
    }
    
    override fun description() = "returnsDelayed $value"
}

// 2. Expose via an extension on SuspendAnsweringScope
infix fun SuspendAnsweringScope<T>.returnsDelayed(value: T) {
    answers(ReturnsDelayedAnswer(value))
}

// Usage:
everySuspend { mock.fetchAt(any()) } returnsDelayed 10

The compiler plugin transforms the code inside every { ... } and verify { ... } blocks. This imposes two main restrictions:

1. No extraction of parts: You cannot extract calls made inside the block into separate functions.
2. Lambda requirement: The block parameter must be a lambda expression. You cannot use a function reference or a lambda assigned to a variable.

Illegal (extracting parts):

@Test
fun test() {
    verify {
       extracted()
    }
}

private fun MokkeryMatcherScope.extracted() {
   foo.getAll()
}

Allowed (extracting the whole call): You can extract the entire verify or every call into a separate function.

Allowed:

@Test
fun test() {
    extracted()
}

private fun extracted() {
   verify {
       foo.getAll()
   }
}

// Illegal: extracting parts of the block
@Test
fun test() {
    verify {
       extracted()
    }
}

private fun MokkeryMatcherScope.extracted() {
   foo.getAll()
}

// Allowed: extracting the entire call
@Test
fun test() {
    extracted()
}
private fun extracted() {
   verify {
       foo.getAll()
   }
}