mockk kotlin

Gitter Build Status Relase Version Change log Back log codecov Documentation

thank you for using MockK!!!

mockk usage

Table of contents:

Nice features

Examples & articles

Kotlin Academy

Installation

All you need to get started is just to add a dependency to MockK library.

Gradle/maven dependency

ToolInstruction
Gradle    
testCompile "io.mockk:mockk:1.7.15"
Maven
<dependency>
    <groupId>io.mockk</groupId>
    <artifactId>mockk</artifactId>
    <version>1.7.15</version>
    <scope>test</scope>
</dependency>

DSL examples

Simplest example. By default mocks are strict, so you need to provide some behaviour.

val car = mockk<Car>()

every { car.drive(Direction.NORTH) } returns Outcome.OK

car.drive(Direction.NORTH) // returns OK

verify { car.drive(Direction.NORTH) }

Annotations

You can use annotations to simplify creation of mock objects:


class TrafficSystem {
  lateinit var car1: Car
  
  lateinit var car2: Car
  
  lateinit var car3: Car
}

class Test {
  @MockK
  lateinit var car1: Car

  @RelaxedMockK
  lateinit var car2: Car

  @SpyK
  val car3 = Car()
  
  @InjectMockKs
  val trafficSystem = TrafficSystem()

  @Before
  fun setUp() = MockKAnnotations.init(this)

  @Test
  fun calculateAddsValues1() {
      // ... use car1, car2 and car3
  }
}

Injection first tries to match properties by name, then by class or superclass. Check lookupType parameter for customization.

Properties are injected even if private is applied. Constructors for injection are selected from the biggest number of arguments to lowest.

@InjectMockKs by default is injecting only lateinit vars or vars that are not assigned. To change this use overrideValues = true. This would assign value even if it is already somehow initialized. To inject vals use injectImmutable = true. For shorter notation use @OverrideMockKs which do the same as @InjectMockKs by default, but turns this two flags on.

JUnit5

In JUnit5 you can use MockKExtension to initialize mock.

@ExtendWith(MockKExtension::class)
class Test {
  @MockK
  lateinit var car1: Car

  @RelaxedMockK
  lateinit var car2: Car

  @SpyK
  val car3 = Car()

  @Test
  fun calculateAddsValues1() {
    // ... use car1, car2 and car3
  }
}

Additionally it adds possibility to use@MockK and @RelaxedMockK on test function parameters:

@Test
fun calculateAddsValues1(@MockK car1: Car, @RelaxedMockK car2: Car) {
  // ... use car1 and car2
}

Spy

Spies allow to mix mocks and real objects.

val car = spyk(Car()) // or spyk<Car>() to call default constructor

car.drive(Direction.NORTH) // returns whatever real function of Car returns

verify { car.drive(Direction.NORTH) }

Note: the spy object is a copy of a passed object.

Relaxed mock

Relaxed mock is the mock that returns some simple value for all functions. This allows to skip specifying behavior for each case, while still allow to stub things you need. For reference types chained mocks are returned.

val car = mockk<Car>(relaxed = true)

car.drive(Direction.NORTH) // returns null

verify { car.drive(Direction.NORTH) }

Note: relaxed mocking is working badly with generic return type. Usually in this case class cast exception is thrown. You need to specify stubbing manually for case of generic return type.

Workaround:

val func = mockk<() -> Car>(relaxed = true) // in this case invoke function has generic return type

// this line is workaround, without it relaxed mock would throw class cast exception on the next line
every { func() } returns Car() // or you can return mockk() for example 

func()

Object mocks

Objects can be transformed to mocks following way:

object MockObj {
  fun add(a: Int, b: Int) = a + b
}

objectMockk(MockObj).use {
  assertEquals(3, MockObj.add(1, 2))

  every { MockObj.add(1, 2) } returns 55

  assertEquals(55, MockObj.add(1, 2))
}

The use function is an utility for mock and unmock methods. If you need to mock an object outside of the use scope, you can do it with them:

@Before
fun beforeTests() {
    objectMockk(MockObj).mock()
    every { MockObj.add(1,2) } returns 55
}

@Test
fun willUseMockBehaviour() {
    assertEquals(55, MockObj.add(1,2))
}

@After
fun afterTests() {
    objectMockk(MockObj).unmock()
}


Despite Kotlin language limits you can create new instances of objects if testing logic needs that:

val newObjectMock = mockk<MockObj>()

Class mock

Sometimes you need mock of arbitary class. Use classMockk in this case.

val car = classMockk(Car::class)

every { car.drive(Direction.NORTH) } returns Outcome.OK

car.drive(Direction.NORTH) // returns OK

verify { car.drive(Direction.NORTH) }

Enumeration mocks

Enums can be mocked using objectMockk:

enum class Enoom(val goodInt: Int) {
    CONSTANT(35),
    OTHER_CONSTANT(45);
}

objectMockk(Enoom.CONSTANT).use {
    every { Enoom.CONSTANT.goodInt } returns 42
    assertEquals(42, Enoom.CONSTANT.goodInt)
}

Partial argument matching

You can mix both regular arguments and matchers:

val car = mockk<Car>()

every { 
  car.recordTelemetry(
    speed = more(50),
    direction = Direction.NORTH, // here eq() is used
    lat = any(),
    long = any()
  )
} returns Outcome.RECORDED

obj.recordTelemetry(60, Direction.NORTH, 51.1377382, 17.0257142)

verify { obj.recordTelemetry(60, Direction.NORTH, 51.1377382, 17.0257142) }

Chained calls

You can stub chains of calls:

val car = mockk<Car>()

every { car.door(DoorType.FRONT_LEFT).windowState() } returns WindowState.UP

car.door(DoorType.FRONT_LEFT) // returns chained mock for Door
car.door(DoorType.FRONT_LEFT).windowState() // returns WindowState.UP

verify { car.door(DoorType.FRONT_LEFT).windowState() }

Note: in case function return type is generic the information about actual type is erased. To make chained calls work additional information is required. Most of the times framework will catch the cast exception and do autohinting. But in the case it is explicitly needed just place hint before calls.


every { obj.op2(1, 2).hint(Int::class).op1(3, 4) } returns 5

Capturing

You can capture an argument to a CapturingSlot or MutableList:

val car = mockk<Car>()

val slot = slot<Double>()
val list = mutableListOf<Double>()

every {
  obj.recordTelemetry(
    speed = capture(slot),
    direction = Direction.NORTH
  )
} answers {
  println(slot.captured)

  Outcome.RECORDED
}


every {
  obj.recordTelemetry(
    speed = capture(list),
    direction = Direction.SOUTH
  )
} answers {
  println(list.captured())

  Outcome.RECORDED
}

obj.recordTelemetry(speed = 15, direction = Direction.NORTH) // prints 15
obj.recordTelemetry(speed = 16, direction = Direction.SOUTH) // prints 16

verify(exactly = 2) { obj.recordTelemetry(speed = or(15, 16), direction = any()) }

Verification atLeast, atMost or exactly times

You can check call count with atLeast, atMost or exactly parameters:


val car = mockk<Car>(relaxed = true)

car.accelerate(fromSpeed = 10, toSpeed = 20)
car.accelerate(fromSpeed = 10, toSpeed = 30)
car.accelerate(fromSpeed = 20, toSpeed = 30)

// all pass
verify(atLeast = 3) { car.accelerate(allAny()) }
verify(atMost  = 2) { car.accelerate(fromSpeed = 10, toSpeed = or(20, 30)) }
verify(exactly = 1) { car.accelerate(fromSpeed = 10, toSpeed = 20) }
verify(exactly = 0) { car.accelerate(fromSpeed = 30, toSpeed = 10) } // means no calls were performed

Verification order

verifyAll verifies that all calls happened without checking it’s order. verifySequence verifies that the exact sequence happened and verifyOrder that calls happened in order. wasNot Called verifies that mock or list of mocks was not called at all.

class MockedClass {
    fun sum(a: Int, b: Int) = a + b
}

val obj = mockk<MockedClass>()
val slot = slot<Int>()

every {
    obj.sum(any(), capture(slot))
} answers {
    1 + firstArg<Int>() + slot.captured
}

obj.sum(1, 2) // returns 4
obj.sum(1, 3) // returns 5
obj.sum(2, 2) // returns 5

verifyAll {
    obj.sum(1, 3)
    obj.sum(1, 2)
    obj.sum(2, 2)
}

verifySequence {
    obj.sum(1, 2)
    obj.sum(1, 3)
    obj.sum(2, 2)
}

verifyOrder {
    obj.sum(1, 2)
    obj.sum(2, 2)
}

val obj2 = mockk<MockedClass>()
val obj3 = mockk<MockedClass>()
verify {
    listOf(obj2, obj3) wasNot Called
}

Returning Unit

If the function is returning Unit you can use just Runs construct:

class MockedClass {
    fun sum(a: Int, b: Int): Unit {
        println(a + b)
    }
}

val obj = mockk<MockedClass>()

every { obj.sum(any(), 3) } just Runs

obj.sum(1, 1)
obj.sum(1, 2)
obj.sum(1, 3)

verify {
    obj.sum(1, 1)
    obj.sum(1, 2)
    obj.sum(1, 3)
}

Coroutines

To mock coroutines you need to add dependency to the support library.

Gradle
testCompile "org.jetbrains.kotlinx:kotlinx-coroutines-core:x.x"
Maven
<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-coroutines-core</artifactId>
    <version>x.x</version>
    <scope>test</scope>
</dependency>

Then you can use coEvery, coVerify, coMatch, coAssert, coRun, coAnswers or coInvoke to mock suspend functions

val car = mockk<Car>()

coEvery { car.drive(Direction.NORTH) } returns Outcome.OK

car.drive(Direction.NORTH) // returns OK

coVerify { car.drive(Direction.NORTH) }

Extension functions

There a 3 cases of extension function:

In case of object and class you can mock extension function just by creating regular mockk:

data class Obj(val value: Int)

class Ext {
    fun Obj.extensionFunc() = value + 5
}

with(mockk<Ext>()) {
    every {
        Obj(5).extensionFunc()
    } returns 11

    assertEquals(11, Obj(5).extensionFunc())

    verify {
        Obj(5).extensionFunc()
    }
}

To mock module wide extension function you need to build staticMockk(…) with argument specifying module class name. For example “pkg.FileKt” for module “File.kt” in “pkg” package

data class Obj(val value: Int)

// declared in File.kt ("pkg" package)
fun Obj.extensionFunc() = value + 5

staticMockk("pkg.FileKt").use {
    every {
        Obj(5).extensionFunc()
    } returns 11

    assertEquals(11, Obj(5).extensionFunc())

    verify {
        Obj(5).extensionFunc()
    }
}

Private functions mocking / dynamic calls

In case you have a need to mock private function, you can do it via dynamic call.

class Car {
    fun drive() = accelerate()

    private fun accelerate() = "going faster"
}

val mock = spyk<Car>()

every { mock["accelerate"]() } returns "going not so fast"

assertEquals("going not so fast", mock.drive())

verifySequence {
    mock.drive()
    mock["accelerate"]()
}

In case you want private calls to be verified, you should create spyk with recordPrivateCalls = true

Additionally more verbose syntax allows to get and set properties, do same dynamic calls:

val mock = spyk(Team(), recordPrivateCalls = true)

every { mock getProperty "speed" } returns 33
every { mock setProperty "acceleration" value less(5) } just Runs
every { mock invoke "openDoor" withArguments listOf("left", "rear") } returns "OK"

verify { mock getProperty "speed" }
verify { mock setProperty "acceleration" value less(5) }
verify { mock invoke "openDoor" withArguments listOf("left", "rear") }

More interfaces

Adding additional behaviours via interfaces and stubbing them:


val spy = spyk(System.out, moreInterfaces = Runnable::class)

spy.println(555)

every {
    (spy as Runnable).run()
} answers {
    (self as PrintStream).println("Run! Run! Run!")
}

val thread = Thread(spy as Runnable)
thread.start()
thread.join()

DSL tables

Here are few tables helping to master the DSL.

Matchers

By default simple arguments are matched using eq()

Matcher Description
any() matches any argument
allAny() special matcher that uses any() instead of eq() for matchers that are provided as simple arguments
isNull() checks if values is null
isNull(inverse=true) checks if values is not null
ofType(type) checks if values belongs to the type
match { it.startsWith("string") } matches via passed predicate
coMatch { it.startsWith("string") } matches via passed coroutine predicate
matchNullable { it?.startsWith("string") } matches nullable value via passe predicate
coMatchNullable { it?.startsWith("string") } matches nullable value via passed coroutine predicate
eq(value) matches if value is equal to the provided via deepEquals function
refEq(value) matches if value is equal to the provided via reference comparation
cmpEq(value) matches if value is equal to the provided via compareTo function
less(value) matches if value is less to the provided via compareTo function
more(value) matches if value is more to the provided via compareTo function
less(value, andEquals=false) matches if value is less or equals to the provided via compareTo function
more(value, andEquals=false) matches if value is more or equals to the provided via compareTo function
range(from, to, fromInclusive=true, toInclusive=true) matches if value is in range via compareTo function
and(left, right) combines two matchers via logical and
or(left, right) combines two matchers via logical or
not(matcher) negates the matcher
capture(slot) captures a value to a CapturingSlot
capture(mutableList) captures a value to a list
captureNullable(mutableList) captures a value to a list together with null values
captureLambda() captures lambda
captureCoroutine() captures coroutine
invoke(...) calls matched argument
coInvoke(...) calls matched argument for coroutine
hint(cls) hints next return type in case it’s got erased

Few special matchers available in verification mode only:

Matcher Description
run { code } matches any value and allows to execute some code
runNullable { code } matches any nullable value and allows to execute some code
coRun { code } matches any value and allows to execute some coroutine code
coRunNullable { code } matches any nullable value and allows to execute some coroutine code
assert(msg) { predicate } matches any value and checks the assertion
assertNullable(msg) { predicate } matches any nullable value and checks the assertion
coAssert(msg) { predicate } matches any value and checks the coroutine assertion
coAssertNullable(msg) { predicate } matches any nullable value and checks the coroutine assertion

Validators

Validator Description
verify { mock.call() } Do unordered verification that call were performed
verify(inverse=true) { mock.call() } Do unordered verification that call were not performed
verify(atLeast=n) { mock.call() } Do unordered verification that call were performed at least n times
verify(atMost=n) { mock.call() } Do unordered verification that call were performed at most n times
verify(exactly=n) { mock.call() } Do unordered verification that call were performed at exactly n times
verifyAll { mock.call1(); mock.call2() } Do unordered verification that only the specified calls were executed for mentioned mocks
verifyOrder { mock.call1(); mock.call2() } Do verification that sequence of calls went one after another
verifySequence { mock.call1(); mock.call2() } Do verification that only the specified sequence of calls were executed for mentioned mocks
verify { mock wasNot Called } Do verification that mock was not called
verify { listOf(mock1, mock2) wasNot Called } Do verification that list of mocks were not called

Answers

Answer can be followed by one or more additional answers.

Answer Description
returns value specify that matched call returns one specified value
returnsMany list specify that matched call returns value from the list, returning each time next element
throws ex specify that matched call throws an exception
answers { code } specify that matched call answers with code block scoped with answer scope
coAnswers { code } specify that matched call answers with coroutine code block with answer scope
answers answerObj specify that matched call answers with Answer object
answers { nothing } specify that matched call answers null
just Runs specify that matched call is returning Unit (returns null)

Additional answer

Next answer is returned on each consequent call and last value is persisted. So this has similiar to returnsMany semantics.

Addititonal answer Description
andThen value specify that matched call returns one specified value
andThenMany list specify that matched call returns value from the list, returning each time next element
andThenThrows ex specify that matched call throws an exception
andThen { code } specify that matched call answers with code block scoped with answer scope
coAndThen { code } specify that matched call answers with coroutine code block with answer scope
andThenAnswer answerObj specify that matched call answers with Answer object
andThen { nothing } specify that matched call answers null

Answer scope

Parameter Description
call a call object that consists of invocation and matcher
invocation contains information regarding actual function invoked
matcher contains information regarding matcher used to match invocation
self reference the object invocation made
method reference to the function invocation made
args reference to arguments of invocation
nArgs number of invocation argument
arg(n) n-th argument
firstArg() first argument
secondArg() second argument
thirdArg() third argument
lastArg() last argument
captured() the last element in the list for convenience when capturing to the list
lambda<...>().invoke() call captured lambda
coroutine<...>().coInvoke() call captured coroutine
nothing null value for returning nothing as an answer

Getting Help

To ask questions, please use stackoverflow or gitter.

To report bugs, please use the GitHub project.