when and do*

Mockito provides two similar approaches for stubbing behaviour on a mock: the when method and the do* family of methods.

Most stubs in Mockito are written with when at the beginning of the line, following the format “when the method is called then return something”. Stubs written with the when method look like this:

  1. val mockedFile = mock(File::class.java)
  3. `when`(mockedFile.read()).thenReturn("hello world")

Sometimes this syntax cannot be used in Mockito, so an alternative approach is available. doReturn and the related doThrow, doAnswer, doNothing, and doCallRealMethod methods are used for void methods, spies, and other occasions where the when method cannot be used. Stubs written with the do* family of methods look like this:

  1. val mockedFile = mock(File::class.java)
  3. doReturn("hello world").`when`(mockedFile).read()

In MockK, all stubs can be written with the every method. every starts a stubbing block and uses anonymous functions and infix functions to define the stub. The syntax looks like this:

  1. val mockedFile = mockk<File>()
  3. every { mockedFile.read() } returns "hello world"

MockK provides alternatives for many types of answers that Mockito supports for stubbing.

thenReturn/doReturn

Returning a value is probably the most common stub to create. In Mockito, the syntax can look like one of two approaches:

  1. val mockedFile = mock(File::class.java)
  3. `when`(mockedFile.read()).thenReturn("hello world")
  4. doReturn("hello world").`when`(mockedFile).read()

In MockK, an infix function is used instead.

  1. val mockedFile = mockk<File>()
  3. every { mockedFile.read() } returns "hello world"

thenThrow/doThrow

Rather than returning values, stubs can throw errors. Mockito lets exceptions be specified with one of two approaches:

  1. val mockedFile = mock(File::class.java)
  3. `when`(mockedFile.read()).thenThrow(RuntimeException())
  4. doThrow(RuntimeException()).`when`(mockedFile).read()

MockK provides the throws infix method to throw in stubs.

  1. val mockedFile = mockk<File>()
  3. every { mockedFile.read() } throws RuntimeException()

doNothing

See Migrating from Mockito: void methods

thenAnswer/then/doAnswer

Mockito allows arbitrary callbacks to be used for stubs with the Answer interface. Answer only contains a single method, so Kotlin allows a function literal to be used instead through SAM conversion.

  1. val mockedFile = mock(File::class.java)
  3. `when`(mockedFile.write(any())).thenAnswer { invocation ->
  4.   println("called with arguments: " + invocation.arguments.joinToString())
  5.   Unit
  6. }
  7. `when`(mockedFile.write(any())).then { invocation ->
  8.   println("called with arguments: " + invocation.arguments.joinToString())
  9.   Unit
  10. }
  11. doAnswer { invocation ->
  12.   println("called with arguments: " + invocation.arguments.joinToString())
  13.   Unit
  14. }.`when`(mockedFile).write(any())

MockK provides an equivalent infix function that also uses function literals.

  1. val mockedFile = mockk<File>()
  3. every { mockedFile.write(any()) } answers { call ->
  4.   println("called with arguments: " + call.invocation.args.joinToString())
  5.   Unit
  6. }

Consecutive calls

Mockito additionally lets different return values be stubbed for the same method call, such as for mocking an iterator.

  1. val mockedFile = mock(File::class.java)
  3. // Chain multiple calls
  4. `when`(mockedFile.read()).thenReturn("read 1").thenReturn("read 2").thenReturn("read 3")
  5. // Shorthand
  6. `when`(mockedFile.read()).thenReturn("read 1", "read 2", "read 3")
  7. doReturn("read 1", "read 2", "read 3").`when`(mockedFile).read()
  8. // Use different answer types
  9. `when`(mockedFile.read())
  10.   .thenReturn("successful read")
  11.   .thenThrow(RuntimeException())

Additional answers is supported in MockK using various infix functions.

  1. val mockedFile = mockk<File>()
  3. // Chain multiple calls
  4. every { mockedFile.read() } returns "read 1" andThen "read 2" andThen "read 3"
  5. // Shorthand using a list
  6. every { mockedFile.read() } returnsMany listOf("read 1", "read 2", "read 3")
  7. every { mockedFile.read() } andThenMany listOf("read 1", "read 2", "read 3")
  8. // Use different answer types
  9. every { mockedFile.read() } returns "successful read" andThenThrows RuntimeException()

Coroutines

As MockK uses function literals to create stubs, small changes are needed to stub suspend functions. MockK provides functions prefixed with co as equivalents to other functions, such as coEvery and coAnswers. See Coroutines and suspend functions for more details.

  1. val mockedFile = mockk<File>()
  3. coEvery { mockedFile.readAsync() } returns "hello world"
  4. coEvery { mockedFile.writeAsync(any()) } coAnswers { call ->
  5.   doAsyncWork()
  6.   Unit
  7. }