mockative

3.1.7indexed

Mocking via code-generation with concise, non-intrusive, type-safe API; mocks classes and interfaces, supports value/matcher stubbing, function/coroutine stubs, implicit Unit stubbing, verification.

AndroidJSJVMNativeWasm·MohamadJaara/mockative

Stars

Used by

dependents

—

Health

/ 100

Mockative

[!CAUTION] This is a temporary maintenance fork. The original Mockative library is no longer actively maintained. This fork exists solely to provide a working version while users migrate to an alternative.

We strongly recommend migrating to Mokkery, which is actively maintained and provides similar mocking capabilities for Kotlin Multiplatform.

This fork will only receive critical bug fixes and compatibility updates. No new features will be added. Support for this fork may end at any time without notice.

[!IMPORTANT] Mockative 3 now supports Kotlin 2! A new Gradle plugin has been introduced to make mocking much simpler in Mockative 3. Please take the time to read through this README if you're upgrading from Mockative 2, and follow the Migrating to Mockative 3 guide for a successful migration.

Mocking for Kotlin/Native and Kotlin Multiplatform using the Kotlin Symbol Processing API (KSP). Notable features include:

Concise, non-intrusive, type-safe API
Mocking of classes and interfaces
Supports both values and matchers when during stubbing verification
Supports implicit stubbing of functions returning Unit

Installation for Multiplatform projects

Add the io.github.mohamadjaara.mockative plugin and dependency to your build.gradle.kts file:

plugins {
  id("io.github.mohamadjaara.mockative") version "3.1.4"
}

kotlin {
    commonMain {
        dependencies {
            implementation("io.github.mohamadjaara:mockative:3.1.3")
        }
    }
}

Mockative is published to Maven Central and applies the following Gradle plugins:

com.google.devtools.ksp: Enables code generation of mockable implementations
org.jetbrains.kotlin.plugin.allopen: Enables mocking of classes

Make sure you specify the following plugin repositories in your build.settings.kts file:

pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}

Then add the following to your gradle.properties file:

#KSP
ksp.useKSP2=true

[!TIP] Now run your tests, which will copy a set of runtime dependencies to your generated code. These will disappear whenever you run a Gradle task that is not a test, lint of other verification task, but will reappear once you run one of them again.

If you're having the following error:

KSP2: KtInvalidLifetimeOwnerAccessException: Access to invalid KtAlwaysAccessibleLifetimeToken: PSI has changed since creation

Please disable incremental processing for KSP by adding the following to your gradle.properties file:

ksp.incremental=false

Mockative 3 code generation should "just work", but if you're looking for more control over when Mockative code generation is enabled or disabled, please read Controlling generation of mocks in Mockative 3.

Making types mockable

To mock an interface or class with Mockative, annotate the type with the @Mockable annotation. This annotation tells Mockative to generate a mock implementation of the annotated type, which can be used in tests.

import io.mockative.Mockable

@Mockable
class MyService {
    // ...
}

The Kotlin all-open plugin will automatically be applied to any class annotated with @Mockable.

Mocking External Types

Sometimes we would like to mock types that are external to our module in our tests. To do so, pass a list of types you'd like to mock in any @Mockable annotation in your main module. If you add the list of types to the @Mockable annotation of a type you'd also like to mock by itself, you must specify the type itself in the list of types to mock. By not specifying any types in the annotation, a mock for the annotated type itself is generated.

import io.mockative.Mockable

@Mockable(MyService::class, Clock::class)
class MyService {
    // ...
}

Testing with Mockative

Obtaining an instance of a mock is as ease as calling the <T> mock(KClass<T>) function:

class GitHubServiceTests {
    val api = mock(of<GitHubAPI>())
}

Then, to stub a function or property on the mock you have a couple of options:

Stubbing using values

To begin stubbing a function you may simply pass the values to the function call inside a block passed to the every or coEvery (when stubbing a suspend function) functions:

// Stub a blocking function
every { githubApi.getRepository("mockative/mockative") }
    .invokes { response }

// Stub a `suspend` function (notice the use of `coEvery`)
coEvery { repositoryMapper.mapResponseToRepository(response) }
    .invokes { repository }

// Stub a property getter
every { repository.maintainer }
    .returns("Nillerr")

// Stub a property setter (these are stubbed by default)
every { repository.stars = repository.stars + 1 }
    .doesNothing()

Stubbing using matchers

Sometimes when stubbing a function we're faced with difficulties providing a specified value for one or more of the parameters of our expectation. In such cases we can use the matcher API to specify the values our stub accepts:

// Assuming we want to stub the function in this S3Client:
interface S3Client {
    suspend fun <T> getObject(input: GetObjectRequest, block: suspend (GetObjectResponse) -> ): T
}





coEvery { s3Client.getObject<File>(eq(request), any()) }
    .returnsMany(expected)

Also note how we're explicitly specifying the type parameter. We could do the same by explicitly specifying it in the call to any() like this:

any<suspend (GetObjectResponse) -> File>()

But that would be significantly more verbose that the alternative.

❕Mockative has limited support for the matcher API when targeting Kotlin/Wasm (WASI).

Stubbing using functions

You may want to provide a function as an argument to another function, where you would like to be able to record invocations on that function. To do that, Mockative includes the interfaces Fun[N] and CoFun[N] (for suspend functions), each declaring a single function invoke that you can pass as a mock to other functions in order to stub and verify invocations on it:

// Declare the mock function as a property in your test class
@Mock
val block = mock(of<Fun1<GetObjectResponse, File>>())

// Stub the mock function
every { block.invoke(response) }
    .returns(file)

// Call something that calls the mock function
s3Client.getObject(request, block::invoke)

// Verify the call to the mock function
verify { block.invoke(response) }
    .wasInvoked(exactly = once)

Stubbing implementations

The following functions are available to provide a stub implementation for every expectation:

In order to provide familiarity to developers coming from MockK, who prefer using infix notation, Mockative also supports infix notation for the invokes, returns, and throws functions:

every { api.getUsers() } returns users

When the return type of the function or property being stubbed is Unit, the following additional then function is available:

Function	Description
`doesNothing()`	Returns `Unit`.

Implicit stubbing of functions returning Unit

Mockative automatically stubs functions returning Unit, based on the idea that such functions are typically used for verification rather than stubbing, and stubbing them could thus be considered boilerplate, while they are trivially automatically stubbed.

You can opt out of this behaviour on the project level through your build.gradle.kts file:

build.gradle.kts

mockative {
    stubsUnitByDefault = false
}

Alternatively, you can opt out (or opt-in if you've opted out on the project level), using the configure(mock, block) function either inline:

@Mock
val api = configure(mock(of<GitHubAPI>())) { stubsUnitByDefault = false }

Or as needed:

@Mock
val api = mock(of<GitHubAPI>())

@Test
fun test() {
    configure(api) { stubsUnitByDefault = false }
}

The configuration is stored on the mock instance. It must be configured before receiving any invocations.

Generic Types

When mocking a generic type use the <T> of(): KClass<T> function to retain the type arguments when passed to the <T> mock(KClass<T>) function. You can use the of function regardless of whether you're mocking a generic or non-generic type.

class GenericTypeTest {
    @Mock
    val list = mock(of<List<String>>())
}

Verification

Verification of invocations on mocks is supported through the verify and coVerify functions using either values or matchers as per the stubbing (every) API:

Verification using values

// Verify a `suspend` function (notice the use of `coVerify`)
coVerify { githubApi.getRepository("mockative/mockative") }
    .wasNotInvoked()

// Verify a blocking function
verify { repositoryMapper.mapResponseToRepository(response) }
    .wasInvoked(atLeast = 1)

// Verify a property getter
verify { repository.maintainer }
    .wasInvoked(atLeast = once, atMost = 6)

// Verify a property setter
verify { repository.stars = repository.stars + 1 }
    .wasInvoked(exactly = 1)

Verification using matchers

// Verify a suspend function (notice the use of `coVerify`)
coVerify { s3Client.getObject<File>(eq(request), any()) }
    .wasInvoked(exactly = once)

Validation

In addition to verification of expectations there's also validation of the use of expectations, which, if not used, can lead to both "under verification" and "over mocking" resulting in inaccurate tests. To handle such cases Mockative provides 2 functions you can use on your mocks, usually in the @AfterTest function of your tests:

@AfterTest
fun afterTest() {
    // Verifies that all expectations were verified through a call to `verify { ... }.wasInvoked()`.
    verifyNoUnverifiedExpectations(githubApi)

    // Verifies that the mock has no expectations that weren't invoked at least once.
    verifyNoUnmetExpectations(s3Client)
}

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

kotlin-fhir★ 63

ohs-foundationLean, fast HL7 FHIR data-model implementation with minimal generated classes, JSON-only serialization, multi-version support, and a tiny runtime footprint for efficient healthcare data handling.Shared: native, kotlin-native, code-generation

kmapper★ 22

s0nicyouthType-safe library enables automated data class mapping with compile-time validation, custom converters, seamless dependency injection integration, null safety, and an extensible architecture.Shared: native, kotlin-native, code-generation

room★ 6.0k

androidxAbstraction layer over SQLite enabling robust database access, compile-time schema export and migrations, annotation-processor tooling, coroutine/RxJava/paging integrations, Gradle plugin for schema management.Shared: test, ksp, code-generation

kfswatch★ 135

irgalyMonitors file system changes across multiple directories, emitting events such as create, delete, and modify. Allows observing file events using flows, supports multiple platforms, and provides raw event access for debugging.Shared: native, kotlin-native

GRPC-Kotlin-Multiplatform★ 133

TimOrtelImplements client-side gRPC with support for parsing proto3 files, generating corresponding code, and suspending RPC calls. Features a DSL for creating proto objects and supports various proto types.Shared: kotlin-native, code-generation

wgpu4k★ 110

wgpu4kCreates WebGPU bindings for web, desktop, and mobile, enabling cross-platform graphics development. Offers example executions and is progressing through API implementation and refinement phases.Shared: native, kotlin-native

`invokes(block: (args: Array<Any?>) -> R)`	Invokes the specified block. The arguments passed to the block are the arguments passed to the invocation.
`invokes(block: () -> R)`	Invokes the specified block.
`invokesMany(vararg block: (args: Array<Any?>) -> R)`	Invokes the specified blocks in sequence. The arguments passed to the block are the arguments passed to the invocation. Once the last block in the sequence has been invoked, this stubbing will no longer match any invocation.
`invokesMany(vararg blocks: () -> R)`	Invokes the specified block. Once the last block in the sequence has been invoked, this stubbing will no longer match any invocation.
`returns(value: R)`	Returns the specified value.
`returnsMany(vararg value: R)`	Returns the specified values in sequence. Once the last value in the sequence has been returned, this stubbing will no longer match any invocation.
`throws(throwable: Throwable)`	Throws the specified exception.
`throwsMany(throwable: Throwable)`	Throws the specified exceptions in sequence. Once the last exception in the sequence has been thrown, this stubbing will no longer match any invocation.