Of course, you can find the rest of the series on my blog, too:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

Video Content

As always, if you prefer a video content, then please check out my latest YouTube video:

Additional Imports

As the first step, let’s add the necessary import:

testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.1")

This package provides utilities for testing coroutines.

And thanks to that, we can mock and test suspend functions.

Code To Test

Following, let’s introduce the suspended functions:

class Eight(
    private val one: EightOne,
    private val two: EightTwo,
) {
    suspend fun funToTest(): String {
        return "${one.returnInt()} ${two.returnString()}"
    }
}

class EightOne {
    suspend fun returnInt(): Int = 10
}

class EightTwo {
    suspend fun returnString(): String = "Some String"
}

And I know it does not make sense. But it is not important here😉

The important part is that we have suspended functions so we can start implementing tests.

MockK with Coroutines

As the next step, let’s try to implement the test “the old way”:

class EightTest {
    private val one: EightOne = mockk()
    private val two: EightTwo = mockk()

    private val eight = Eight(one, two)

    @Test
    fun `should return 1 codersee`() {
        every { one.returnInt() } returns 1
        every { two.returnString() } returns "codersee"

        val result = eight.funToTest()

        assertEquals("1 codersee", result)

        verifySequence {
            one.returnInt()
            two.returnString()
        }
    }
}

As a result, we can see the compiler complaining about our suspended functions:

Suspend function 'returnInt' should be called only from a coroutine or another suspend function
Suspend function 'returnString' should be called only from a coroutine or another suspend function
Suspend function 'funToTest' should be called only from a coroutine or another suspend function

So, as the first step, let’s add the runTest to get rid of the last error:

@Test
fun `should return 1 codersee`() = runTest {

The runTest is not related to the MockK itself. It comes from kotlinx.coroutines and executes our test body in a new coroutine, returning TestResult .

When it comes to MockK, then we can work with coroutines and suspended functions by simply adding the “co” suffix for all functions:

class EightTest {
    private val one: EightOne = mockk()
    private val two: EightTwo = mockk()

    private val eight = Eight(one, two)

    @Test
    fun `should return 1 codersee`() = runTest {
        coEvery { one.returnInt() } returns 1
        coEvery { two.returnString() } returns "codersee"

        val result = eight.funToTest()

        assertEquals("1 codersee", result)

        coVerifySequence {
            one.returnInt()
            two.returnString()
        }
    }
}

And yes, this is that easy!😉

MockK comes with plenty of functions to work with suspend functions, like:

• coVerify
• coEvery
• coJustRun
• coJustAwait
• coAnswers
• and many more😉

Issue With Spies

Lastly, at the moment of writing, there is one issue with spies and coroutines in MockK. You can see all the details here: https://github.com/mockk/mockk/issues/554

Assuming this is quite an old one, I wouldn’t expect it to be fixed in the near future.

But if that is the case, then please let me know in the comments below.

Summary

That’s all for this series about MockK – the mocking library for Kotlin.

During our time together, we learned A LOT, and I believe you are ready to use it in your projects!

Let me know your thoughts in the comments below, and if you are looking for the other articles, then here you are:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

The post MockK with Coroutines [5/5] appeared first on Codersee blog- Kotlin on the backend.

Of course, you can find the rest of the series on my blog, too:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

Video Content

As always, if you prefer a video content, then please check out my latest YouTube video:

MockK: Relaxed Mock

What does a relaxed mock mean?

Well, long story short, it is a mock that returns some value for all functions. In other words, the value is returned even if we do not provide a stubbing.

To better understand, let’s take a look at the example:

class Five(
    private val one: FiveOne,
) {
    fun funToTest(): String {
        one.returnInt()
        return one.returnString()
    }
}

class FiveOne {
    fun returnInt(): Int = 10
    fun returnString(): String = "Some String"
}

As we can see, the function we want to test invokes two another: returnInt and returnString.

And I am pretty sure that at this point, you know the result without even running the test:

class FiveTest {

    private val one: FiveOne = mockk()
    private val five = Five(one)

    @Test
    fun `should return mocked string`() {
        every { one.returnString() } returns "mocked"

        val result = five.funToTest()

        assertEquals("mocked", result)
    }
}

That’s right, it fails, and MockK complains about missing answer:

no answer found for FiveOne(#1).returnInt() among the configured answers: (FiveOne(#1).returnString()))
io.mockk.MockKException: no answer found for FiveOne(#1).returnInt() among the configured answers: (FiveOne(#1).returnString()))

And as you may have guessed, a relaxed mock may help us here a bit. But how do we define it in MockK?

It’s easy; the only thing we need is to set up the relaxed flag on creation:

private val one: FiveOne = mockk(relaxed = true)

(When working with annotations, we can use @RelaxedMockK instead of @MockK)

So, now, when we repeat our test, it passes!

Moreover, we could even completely skip the stubbing part:

@Test
fun `should return empty string`() {
    val result = five.funToTest()

    assertEquals("", result)
}

But please don’t do that in your tests and treat them as a curiosity😉

And before we head to the next part, I just wanted to mention that for Unit-returning functions, we must set a separate flag- relaxUnitFun – to true:

private val one: FiveOne = mockk(relaxed = true, relaxUnitFun = true)

Partial Mocking

Nextly, let’s focus on the partial mocking.

This technique, on the other hand, allows us to invoke the actual function.

Let’s take a look at the example of a new class to test:

class Six(
    private val one: SixOne,
) {
    fun funToTest(): String {
        one.returnInt()
        return one.returnString()
    }
}

class SixOne {
    fun returnInt(): Int = 10
    fun returnString(): String = "Some String"
}

As we can see, apart from the names, it works exactly the same as previously.

So, let’s take a look at the test:

class SixTest {

    private val one: SixOne = mockk()
    private val five = Six(one)

    @Test
    fun `should invoke actual functions`() {
        every { one.returnInt() } answers { callOriginal() }
        every { one.returnString() } answers { callOriginal() }

        val result = five.funToTest()

        assertEquals("Some String", result)
    }
}

As we can see, in MockK, we can use the answers { callOriginal() }  to invoke the actual function. And that’s why we get “Some String” value here.

MockK Spy

As the last step, let’s take a look at the spies. What are they?

Well, they are a mix of real objects with mocks. Whenever we do not specify any stubbing, the actual function is invoked.

So, the main difference between spies and partial mocking is that for a spy, the original function is invoked if we don’t write anything. In partial mocking, we must be explicit.

Let’s take a look at the code to test then. Again, this is a 1:1 copy of previous examples:

class Seven(
    private val one: SevenOne,
) {
    fun funToTest(): String {
        one.returnInt()
        return one.returnString()
    }
}

class SevenOne {
    fun returnInt(): Int = 10
    fun returnString(): String = "Some String"
}

Following, let’s implement a simple test with a MockK spy then:

class SevenTest {

    private val one: SevenOne = spyk(SevenOne())

    private val five = Seven(one)

    @Test
    fun `should invoke actual functions`() {
        val result = five.funToTest()

        assertEquals("Some String", result)
    }
}

And we can see the interesting difference here- we pass the instance of the dependent object to the spyk . And although underneath a copy of that object will be used rather than the passed instance, this shows that spies are actual objects with mocking capabilities.

Additionally, we can use a similar notation to mockk:

private val one: SevenOne = spyk()
// or 
private val one = spyk<SevenOne>()

In this case, the default constructor will be invoked.

And if you are wondering when to use spies, and when to choose partial mocks, then I would say that partial mocks will be better whenever actual calls are rare, almost exceptional. If since the very beginning we want to mix actual resposnes with stubs, then spies will be more optiomal option.

Summary

That’s all for the fourth article in a series in which we learned how to deal with MockK spies, relaxed mocks, and partial mocking.

Awesome! And without any further ado, let’s head to the next lesson:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

The post MockK: Spy, Relaxed Mock, and Partial Mocking [4/5] appeared first on Codersee blog- Kotlin on the backend.

Of course, you can find the rest of the series on my blog, too:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

Video Content

As always, if you prefer a video content, then please check out my latest YouTube video:

Kotlin Objects and MockK

Let’s start everything by explaining how to mock Kotlin objects in MockK.

And as you know, objects are pretty specific, so we are going to see two, different examples and approaches.

mockkObject

Let’s introduce a simple example with an object:

class One {
    fun funToTest(): UUID = SomeObject.generateId()
}

object SomeObject {
    fun generateId(): UUID = UUID.randomUUID()
}

It is not rocket science, right? We are going to simply test the function that should return the UUID generated by SomeObject function.

So, if we would like to mock that UUID to gain more control over the behavior, then we can use the mockkObject:

class OneTest {

    private val one = One()

    @Test
    fun `should return mocked ID`() {
        val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

        mockkObject(SomeObject)
        every { SomeObject.generateId() } returns id

        val result = one.funToTest()

        assertEquals(id, result)
    }
}

The above test succeeds, and we can see that we define stubbing just like with every mock.

Moreover, if we add mockkObject inside the function, it will not affect the scope of other tests:

class OneTest {

    private val one = One()

    @Test
    fun `should return mocked ID`() {
        val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

        mockkObject(SomeObject)
        every { SomeObject.generateId() } returns id

        val result = one.funToTest()

        assertEquals(id, result)
    }

    @Test
    fun `should fail returning mocked ID`() {
        val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

        val result = one.funToTest()

        assertEquals(id, result)
    }
}

This time, the second test fails because SomeObject returns a random value.

Additionally, if we use the mockkObject , but we don’t provide stubbing, MockK will not throw any exception:

@Test
fun `should fail returning mocked ID`() {
    val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

    mockkObject(SomeObject)
    val result = one.funToTest()

    assertEquals(id, result)
}

The above test runs just like mockkObject(SomeObject) does not exist. As a result, we get a random UUID.

So, we must be cautious about that.

unmockkObject

Although I highly doubt we should ever use that, MockK allows us to “unmock” the object with unmockkObject function.

How does it work?

Let’s analyze the below snippet:

@Test
fun `should illustrate unmockkObject`() {
    val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

    mockkObject(SomeObject)
    every { SomeObject.generateId() } returns id

    assertEquals(id, one.funToTest())

    unmockkObject(SomeObject)
    assertEquals(id, one.funToTest())
}

In this example, the first assertion succeeds. However, the second assertEquals fails due to unmockkObject that reverts our mock.

So, again, during the second call, a random UUID is generated.

Create Mock Object Instance

I know, this title sounds simply weird.

Nevertheless, let’s take a look at another class- Two :

class Two(
    private val someObject: SomeObject,
) {
    fun funToTest(): UUID = someObject.generateId()
}

This time, we inject our SomeObject through the constructor.

And for consistency, in MockK, we can mock that just like a simple class:

class TwoTest {

    private val someObject = mockk<SomeObject>()
    private val two = Two(someObject)

    @Test
    fun `should return mocked ID`() {
        val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

        every { someObject.generateId() } returns id

        val result = two.funToTest()

        assertEquals(id, result)
    }
}

But, we must remember about two, important things in this case.

Firstly, we must provide a stubbing:

@Test
fun `should fail due to missing stubbing`() {
    val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

    val result = two.funToTest()

    assertEquals(id, result)
}

So, just like with classes, the above test fails due to missing stubbing!

Secondly, when defining stubbing, we must use the instance:

@Test
fun `should fail due to incorrect stubbing`() {
    val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

    every { SomeObject.generateId() } returns id

    val result = two.funToTest()

    assertEquals(id, result)
}

As we can see, we cannot refer to the SomeObject anymore.

So, as always, the choice is up to you. 🙂

MockK and Top-Level Functions

With all of that said about objects, let’s take a look at how we can deal with another Kotlin feature, top-level functions, in MockK.

As the first step, let’s take a look at the code to test:

class Three {
    fun funToTest(): UUID = generateId()
}

fun generateId(): UUID = UUID.randomUUID()

This time, instead of the object and its function, we’re dealing with top-level generateId .

And from the MockK perspective, everything looks pretty much the same as with objects:

class ThreeTest {

    private val three = Three()

    @Test
    fun `should return mocked ID`() {
        val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

        mockkStatic(::generateId)
        every { generateId() } returns id

        val result = three.funToTest()

        assertEquals(id, result)
    }
}

As we can see, we use the mockkStatic and we simply provide our stubbing.

And just like in the first approach in objects, nothing happens if we define the mockkStatic , but we don’t set the stubbing. The random UUID is generated:

@Test
fun `should fail due to missing stubbing`() {
    val id = UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

    mockkStatic(::generateId)

    val result = three.funToTest()

    assertEquals(id, result)
}

Lastly, I just wanted to mention that we have a similar function- clearStaticMockk– on the table, too😉

Extension Functions Support

As the last thing in this article, let’s take a look at the example leveraging the extension function:

class Four {
    fun funToTest(): String = "abc".withCustomCase()
}

fun String.withCustomCase(): String = this.uppercase()

It does not make too much sense, but we can clearly see that our extension function should return an uppercase String value.

And to mock this case in MockK, we can use mockkStatic once again:

class FourTest {

    private val four = Four()

    @Test
    fun `should return codersee`() {
        mockkStatic(String::withCustomCase)
        every { "abc".withCustomCase() } returns "codersee"
        every { "xyz".withCustomCase() } returns "not-codersee"

        val result = four.funToTest()

        assertEquals("codersee", result)
    }
}

The really interesting part in the above snippet is that the String value must match!

Additionally, MockK allows us to mock extension functions defined in a class.

Nevertheless, in my opinion this case is so rare, that I will skip it. And if you really need to check it, then take a look at the documentation here.

Summary

That’s all for the third article, in which we learned how to deal with Kotlin objects, top-level and extension functions in MockK.

Great job, and without any further ado, let’s head to the next lesson:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

The post MockK: Objects, Top-Level, and Extension Functions [3/5] appeared first on Codersee blog- Kotlin on the backend.

To view other articles in this series, please take a look at:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

Video Content

As always, if you prefer a video content, then please check out my latest YouTube video:

Why Do We Need Verification?

At this point, you may wonder why we need to do anything else besides what we did previously. We configured mocks, and they worked; we made the necessary assertions.

Then what is the point of anything else?

Well, our logic is pretty clear and predictable:

fun createUser(email: String, password: String): UUID {
    userRepository.findUserByEmail(email)
        ?.let { throw IllegalArgumentException("User with email $email already exists") }

    return userRepository.saveUser(email, password)
        .also { userId ->
            emailService.sendEmail(
                to = email,
                subject = "Welcome to Codersee!",
                body = "Welcome user: $userId."
            )
        }
}

And by predictable, I mean that we see that every function will be invoked at most 1 time. That no other functions are invoked when we throw the exception. And I do not see any possibility that saveUser somehow would trigger before findUserByEmail.

But sometimes, that’s not the case.

Sometimes mocks may be invoked a variable number of times depending on some response, right? For example, when we call some user endpoint, we get a list of users, and then we fetch something for each user.

Another time, the order may be affected by the algorithm. And yet another time, it may be simply a spaghetti you inherited from someone else😉

And in a moment, we will learn what exactly we can do in our tests.

Verification with eq

Before we head to the actual functions, let me share a first MockK verification tip: prefer eq matchers wherever possible.

To better visualize, let’s recap the test example once again:

@Test
fun `should throw IllegalArgumentException when user with given e-mail already exists`() {
    val email = "contact@codersee.com"
    val password = "pwd"

    val foundUser = User(UUID.randomUUID(), email, password)
    every { userRepository.findUserByEmail(email) } returns foundUser

    assertThrows<IllegalArgumentException> {
        service.createUser(email, password)
    }
}

We clearly see that foundUser will be returned only if the findUserByEmail is invoked with contact@codersee.com

And this is already a kind of verification. Because if we would use any() , or any<String>() , the test would still pass. However, it would pass even if our logic sent a password there by mistake!

So I guess you see my point here. For such cases, I would go for eq matcher.

Various MockK Verifications

And with all of that said, we can finally take a look at various, actual verifications in MockK.

For that purpose, let’s introduce a more dummy example that will help us to focus on the topic without unwanted code:

class A (
    private val b: B,
    private val c: C
) {
    fun funToTest(): Int {
        return 5
    }
}

class B {
    fun funFromB(): Int = 10
}

class C {
    fun funFromC(): String = "Hi!"
}

verify

Let’s start with the simplest one- verify .

And for that, let’s update the funToTest and write a simple test for it:

fun funToTest(): Int {
    repeat(10) { b.funFromB() }
    repeat(5) { c.funFromC() }
    return 5
}

@Test
fun `should return 5 without any verification`() {
    every { b.funFromB() } returns 1
    every { c.funFromC() } returns ""

    val result = a.funToTest()

    assertEquals(5, result)
}

When we run the test, it succeeds. Moreover, we can clearly see that we can define stubbing once. Even though functions are invoked multiple times.

With the verify , we can make sure that they were invoked a specific number of times:

@Test
fun `should return 5 with verification and confirmation`() {
    every { b.funFromB() } returns 1
    every { c.funFromC() } returns ""

    val result = a.funToTest()

    assertEquals(5, result)

    verify(exactly = 10) { b.funFromB() }
    verify(atLeast = 5) { c.funFromC() }

    confirmVerified(b, c)
}

We can use exactly , atLeast , atMost – the choice is up to you.

Additionally, if we would like to set some arbitraty timeout, then this is our go-to function.

confirmVerified

Moreover, we should use verify in combination with confirmVerified .

This way, we additionally check if our test code verified all invoked functions.

If we get rid of verify(atLeast = 5) { c.funFromC() } and rerun the test, we will see:

Verification acknowledgment failed

Verified call count: 0
Recorded call count: 5


Not verified calls:
1) C(#2).funFromC()
2) C(#2).funFromC()
3) C(#2).funFromC()
4) C(#2).funFromC()
5) C(#2).funFromC()

So, as we can see, this is a great way to double-check our test assumptions (testing a test?🙂).

checkUnnecessaryStub

Speaking of testing the test- we can additionally check if there are no unused stubbings.

For that purpose, let’s slightly update the example:

class A(
    private val b: B,
    private val c: C
) {
    fun funToTest(): Int {
        repeat(10) { b.funFromB(7) }
        repeat(5) { c.funFromC() }
        return 5
    }
}

class B {
    fun funFromB(some: Int): Int = 10
}

class C {
    fun funFromC(): String = "Hi!"
}

So this time, funFromB will always be invoked with 7 .

And if we make our test this way:

@Test
fun `should return 5 with verification and confirmation`() {
    every { b.funFromB(7) } returns 1
    every { b.funFromB(6) } returns 2 // unwanted
    every { c.funFromC() } returns ""

    val result = a.funToTest()

    assertEquals(5, result)

    verify(exactly = 10) { b.funFromB(7) }
    verify(atLeast = 5) { c.funFromC() }

    confirmVerified(b, c)
    checkUnnecessaryStub(b, c)
}

Then MockK will be complaining a bit:

1) B(#1).funFromB(eq(6)))
java.lang.AssertionError: Unnecessary stubbings detected.
Following stubbings are not used, either because there are unnecessary or because tested code doesn't call them :

1) B(#1).funFromB(eq(6)))

verifyCount

When it comes to counts, we can use the verifyCount function instead:

@Test
fun `should return 5 with verifyCount`() {
    every { b.funFromB(7) } returns 1
    every { c.funFromC() } returns ""

    val result = a.funToTest()

    assertEquals(5, result)

    verifyCount {
        10 * { b.funFromB(7) }
        (4..5) * { c.funFromC() }
    }
    confirmVerified(b, c)
}

This allows us to achieve an even cleaner test with beautiful Kotlin DSL.

Nevertheless, we still have to invoke confirmVerified separately.

verifyAll/verifyOrder/verifySequence

Sometimes, we can use verifyAll , verifyOrder , and verifySequence to make the code slightly cleaner.

The verifyAll checks if all calls happened, but it does not verify the order:

@Test
fun `should return 5 with verifyAll`() {
    every { b.funFromB(7) } returns 1
    every { c.funFromC() } returns ""

    val result = a.funToTest()

    assertEquals(5, result)

    verifyAll {
        c.funFromC()
        b.funFromB(7)
    }
}

So, the above function will work like a charm.

On the other hand, if we use the verifyOrder , it won’t work anymore, and we will have to provide a valid order:

@Test
fun `should return 5 with verifyOrder`() {
    every { b.funFromB(7) } returns 1
    every { c.funFromC() } returns ""

    val result = a.funToTest()

    assertEquals(5, result)

    verifyOrder {
        b.funFromB(7)
        c.funFromC()
    }
}

Lastly, the verifySequence will work similar to verifyOrder , but it will force us to provide the right amount of times in the right order.

So, to make the test work, we would need to do a small tweak:

@Test
fun `should return 5 with verifySequence`() {
    every { b.funFromB(7) } returns 1
    every { c.funFromC() } returns ""

    val result = a.funToTest()

    assertEquals(5, result)

    verifySequence {
        repeat(10) { b.funFromB(7) }
        repeat(5) { c.funFromC() }
    }
}

The important thing to mention is that if in our verifyAll or verifySequence block we covered all mocks, then we don’t need to add confirmVerified .

But, unfortunately, this will succeed:

@Test
fun `should fail due to missing verification`() {
    every { b.funFromB(7) } returns 1
    every { c.funFromC() } returns ""

    val result = a.funToTest()

    assertEquals(5, result)

    verifySequence {
        repeat(10) { b.funFromB(7) }
    }
}

And we must guard ourselves with confirmVerified(c) .

However, if we do the b and c check inside. Then the confirmedVerified is not needed anymore.

MockK capturing

Lastly, I would like to show you one more interesting MockK feature useful in verification- the capturing.

Let’s imagine a new function inside the B class:

class B {
    fun anotherFunFromB(some: Int) {}
}

Now, the anotherFunToTest invokes it using the random value:

fun anotherFunToTest(): Int {
    b.anotherFunFromB(Random.nextInt())
    return 3
}

So, if we write a test this way:

@Test
fun `should return 3`() {
    justRun { b.anotherFunFromB(any()) }

    val result = a.anotherFunToTest()

    assertEquals(3, result)
}

We clearly see, that we cannot access this value in any way, right? It is not returned from the function itself. We cannot control it with other mock, too.

Thankfully, we can introduce a slot and capture the value on the fly:

@Test
fun `should return 3`() {
    val randomSlot = slot<Int>()

    justRun { b.anotherFunFromB(capture(randomSlot)) }

    val result = a.anotherFunToTest()

    println("Random value: ${randomSlot.captured}")
    assertEquals(3, result)
}

This way, the stubbing works just like any() ,but additionally, we can access the random value with captured .

And although this may not be a clear verification, in some cases, it can be really helpful.

Summary

That’s all for this article about verification in MockK.

We covered various approaches, techniques, and at this point I am pretty sure you will be able to pick the right one for your test cases.

Without any further ado, let’s head to the next article in this series:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

The post Verification in MockK [2/5] appeared first on Codersee blog- Kotlin on the backend.

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

If you enjoy this content, then check out my Ktor Server PRO course- the most comprehensive Ktor guide in the market. You’re gonna love it! 🙂

Video Content

As always, if you prefer a video content, then please check out my latest YouTube video:

Why Do We Need Mocking?

Long story short, we need mocking to isolate the unit / the system under test.

Sounds confusing? No worries.

Let’s take a look at the typical example of a function:

So, our function A- the one we would like to focus on in our test- calls both B and C. It can happen sequentially or simultaneously; it doesn’t matter.

What matters is that when we want to test A, we want to see its behavior in different cases. How does it behave when B returns (for instance) user data successfully? What happens in case of a null value? Does it handle exceptions gracefully?

And to avoid spending countless hours on manual setup, we use the mocking technique to simulate different scenarios. Mostly with the help of libraries, like MockK.

The important thing to remember is that mocking is not limited to functions. A, B, and C may as well represent services.

And in various sources, A will be referred to as the System Under Test (SUT), whereas B, and C will be Depended On Component (DOC).

Mocking, Stubbing, Test Doubles

Frankly, please skip this section if this is your first time with mocking or MockK. I truly believe you will benefit more from focusing on learning MockK-related concepts than slight differences in wording.

Anyway, from the chronicler’s duty, let me illustrate a few concepts:

• stub is a fake object that returns hard-coded answers. Typically, we use it to return some value, but we don’t care about additional info, like how many times it was invoked, etc.
• mock is pretty similar, but this time, we can verify interactions, too. For example, to see if this was invoked with a particular ID value, exactly N times.
• stubbing means setting up a stub or a mock so that a particular method returns some value or throws an exception
• mocking means creating/using a mock
• and lastly, we use the test doubles term for any kind of replacement we use in place of a real object in your tests (that terms comes stund doubles in movies).

And if you are looking for a really deep dive, I invite you to Martin Fowler’s article.

MockK Imports

With all of that said, let’s head to the practice part.

Firstly, let’s define the necessary imports for MockK.

We will be working with a plain Kotlin / Gradle project with JUnit 5, so our build.gradle.kts dependencies should look as follows:

dependencies {
    testImplementation("io.mockk:mockk:1.13.17")
    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

The io.mockk:mockk is the only thing we need when working with MockK (unless we want to work with couroutines- but I will get back to that in the fifth lesson).

Tested Code

Then, let’s take a look at the code we are supposed to test:

data class User(val id: UUID, val email: String, val passwordHash: String)

class UserRepository {
    fun saveUser(email: String, passwordHash: String): UUID =
        UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")

    fun findUserByEmail(email: String): User? =
        User(
            id = UUID.fromString("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"),
            email = "found@codersee.com",
            passwordHash = "foundPwd"
        )
}

class EmailService {
    fun sendEmail(to: String, subject: String, body: String) {
        println("Sending body $body to $to with subject $subject")
    }
}

class UserService(
    private val userRepository: UserRepository,
    private val emailService: EmailService,
) {

    fun createUser(email: String, password: String): UUID {
        userRepository.findUserByEmail(email)
            ?.let { throw IllegalArgumentException("User with email $email already exists") }

        return userRepository.saveUser(email, password)
            .also { userId ->
                emailService.sendEmail(
                    to = email,
                    subject = "Welcome to Codersee!",
                    body = "Welcome user: $userId."
                )
            }
    }
}

As we can see, we have a simple example of a UserService with one function- createUser . The service and the function that we will focus on in our tests.

And although UserRepository and EmailService look pretty weird, the createUser is more or less something we can find in our real-life code. We check if the given email is taken, and if that’s the case, we throw an exception. Otherwise, we save the user and send a notification e-mail.

Positive & Negative Scenario

Following, let’s do something different compared to other content about MockK. Let’s start by taking a look at the final result, and then we will see how we can get there.

So, firstly, let’s add the negative scenario:

class AwesomeMockkTest {

    private val userRepository: UserRepository = mockk()
    private val emailService = mockk<EmailService>()

    private val service = UserService(userRepository, emailService)

    @Test
    fun `should throw IllegalArgumentException when user with given e-mail already exists`() {
        val email = "contact@codersee.com"
        val password = "pwd"

        val foundUser = User(UUID.randomUUID(), email, password)
        every { userRepository.findUserByEmail(email) } returns foundUser

        assertThrows<IllegalArgumentException> {
            service.createUser(email, password)
        }

        verifyAll { userRepository.findUserByEmail(email) }
    }
}

As we can see, we start all by defining dependencies for UserService as MockK mocks, and then we simply inject them through the constructor.

After that, we add our JUnit 5 test that asserts if the createUser function has thrown an exception, nothing unusual. The “unusual” part here is the every and verifyAll – those two blocks come from MockK, and we will get back to them in a moment.

With that done, let’s add one more test:

@Test
fun `should return UUID when user with given e-mail successfully created`() {
    val email = "contact@codersee.com"
    val password = "pwd"
    val createdUserUUID = UUID.randomUUID()

    every { userRepository.findUserByEmail(email) } returns null
    every { userRepository.saveUser(email, password) } returns createdUserUUID
    every {
        emailService.sendEmail(
            to = email,
            subject = "Welcome to Codersee!",
            body = "Welcome user: $createdUserUUID."
        )
    } just runs

    val result = service.createUser(email, password)

    assertEquals(createdUserUUID, result)

    verifyAll {
        userRepository.findUserByEmail(email)
        userRepository.saveUser(email, password)
        emailService.sendEmail(
            to = email,
            subject = "Welcome to Codersee!",
            body = "Welcome user: $createdUserUUID."
        )
    }
}

This time, we test the positive scenario, in which the user was not found by the e-mail and was created successfully.

Defining MockK Mocks

With all of that done, let’s start breaking down things here.

Let’s take a look at what we did first:

private val userRepository: UserRepository = mockk()
private val emailService = mockk<EmailService>()

private val service = UserService(userRepository, emailService)

So, one of the approaches to define objects as mocks with MockK is by using the mockk function.

It is a generic function. So that’s why I presented both ways to invoke it. But please treat that as an example. In real life, I suggest you stick to either mockk() or mockk<EmailService>() for a cleaner code.

Alternatively, we can achieve exactly the same with MockK annotations:

@ExtendWith(MockKExtension::class)
class AwesomeMockkTest {

  @MockK
  lateinit var userRepository: UserRepository

  @MockK
  lateinit var emailService: EmailService

  @InjectMockKs
  lateinit var service: UserService

}

The preferred approach is totally up to you. The important thing to mention is that the @ExtendWith(MockKExtension::class) comes from JUnit 5.

And for the JUnit 4, we would implement a rule:

class AwesomeMockkTest {
  @get:Rule
  val mockkRule = MockKRule(this)

  @MockK
  lateinit var userRepository: UserRepository

  @MockK
  lateinit var emailService: EmailService

  @InjectMockKs
  lateinit var service: UserService

}

Missing Stubbing

At this point, we know that we don’t use real objects, but mocks.

Let’s try to run our test without defining any behavior:

@Test
fun `should throw IllegalArgumentException when user with given e-mail already exists`() {
    val email = "contact@codersee.com"
    val password = "pwd"

    assertThrows<IllegalArgumentException> {
        service.createUser(email, password)
    }

    verifyAll { userRepository.findUserByEmail(email) }
}

In the console log, we should see the following:

Unexpected exception type thrown, expected: <java.lang.IllegalArgumentException> but was: <io.mockk.MockKException>

Expected :class java.lang.IllegalArgumentException

Actual :class io.mockk.MockKException

Well, the issue is that when we do not specify a stubbing for a function that was invoked, MockK throws an exception.

But our test logic looks already for exception, so that’s why we got a message that this is simply an unexpected one.

Without the assertThrows , the message would be more obvious:

no answer found for UserRepository(#1).findUserByEmail(contact@codersee.com) among the configured answers: (UserRepository(#1).saveUser(eq(contact@codersee.com), eq(pwd))))

io.mockk.MockKException: no answer found for UserRepository(#1).findUserByEmail(contact@codersee.com) among the configured answers: (UserRepository(#1).saveUser(eq(contact@codersee.com), eq(pwd))))

So, lesson one: whenever we see a similar message, it means that our mock function was invoked, but we haven’t defined any stubbing.

Stubbing in MockK

And we already saw how we can define a stubbing, but let’s take a look once again:

val foundUser = User(UUID.randomUUID(), email, password)
every { userRepository.findUserByEmail(email) } returns foundUser

We can read the above function as “return foundUser every time the findUserByEmail function is invoked with this, specific email value”.

When we run the test now, everything is working fine. Because in our logic, if the findUserByEmail returns a not null value, an exception is thrown. So, no more functions are invoked. In other words, no more interactions with our mock object😉 Also, our email value matches.

And most of the time, this is how I would suggest defining stubbing. This way, we also make sure that the exact value of email is passed.

When it comes to the answer part, returns foundUser, we can also use alternatives, like:

• answers { code } – to define a block of code to run (and/or return a value)
• throws ex – to throw exception
• and many, many more (I will put a link to the docs at the end of this article)

MockK Matchers

The above stubbing expects that the email value will be equal to what we define.

Technically, it is the equivalent of using the eq function:

 every { userRepository.findUserByEmail(eq(email)) } returns foundUser

And eq uses the deepEquals function to compare the values.

But sometimes, we do not want to, or we cannot define the exact value to match.

Let’s imagine that some function is invoked 20 times with various values. Technically, we could define all 20 matches.

But instead, we use one of the many matchers available in MockK, like any :

 every { userRepository.findUserByEmail(any()) } returns foundUser

And whereas eq is the most concrete one, any is the most generic one. The foundUser is returned if findUserByEmail is invoked with anything.

And MockK comes with plenty of other matchers, like:

• any(Class) – to match only if an instance of a given Class is passed
• isNull / isNull(inverse=true) – for null check
• cmpEq(value) , more(value) , less(value) – for the compareTo comparisons
• and many more that you can find in the documentation

For example, let’s take a look at the match example:

every {
  userRepository.findUserByEmail(
    match { it.contains("@") }
  )
} returns foundUser

As we can see, this way the foundUser will be returned only if the passed value contains @ sign.

Unit Functions

At this point, we know how to deal with matchers and the returns .

But what if the function does not return anything? We saw that previously, so let’s take a look once again:

every { emailService.sendEmail(any(), any(), any()) } just runs

Matchers are irrelevant right now, so I replaced them with any() .

The important thing here is that just runs is one of the approaches.

Alternatively, we can achieve the same:

every { emailService.sendEmail(any(), any(), any()) } returns Unit
every { emailService.sendEmail(any(), any(), any()) } answers { }
justRun { emailService.sendEmail(any(), any(), any()) } 

The choice here is totally up to you.

Summary

And that’s all for our first lesson dedicated to MockK and Kotlin.

As I mentioned above, right here you can find the MockK documentation. And although I strongly encourage you to visit it, I also would suggest doing it after my series- when we cover the most important concepts:

• Getting Started with MockK in Kotlin [1/5]
• Verification in MockK [2/5]
• MockK: Objects, Top-Level, and Extension Functions [3/5]
• MockK: Spies, Relaxed Mocks, and Partial Mocking [4/5]
• MockK with Coroutines [5/5]

The post Getting Started with MockK in Kotlin [1/5] appeared first on Codersee blog- Kotlin on the backend.

I can guarantee that you will benefit from this tutorial regardless of whether you saw previous articles about S3Client or S3Template, or not. But, I definitely encourage you to take a look at them, too:

• #1 Spring Boot with AWS S3, S3Client, and Kotlin
• #2 Spring Boot with Kotlin, AWS S3, and S3Template
• #3 (This article)

Video Tutorial

If you prefer video content, then check out my video that covers all three articles:

If you find this content useful, please leave a subscription 🙂

Prerequisites

Before heading to the guide, I just wanted to emphasize that today we will be working with Testcontainers. And this means that we must have a supported Docker environment.

So, if you do not have Docker configured on your local and want to follow this article, please check out their documentation.

Of course, you must have Java, IDE, and Spring Boot project too, but I believe this is quite obvious 😉

Testcontainers and LocalStack

Lastly, I would like to say a few words about the Testcontainers and LocalStack, which in my opinion are a great way to test Spring Boot S3 integration (and other AWS integrations, too).

Testcontainers

Testcontainers is a library for providing throwaway, lightweight instances of Docker containers. They are an excellent approach whenever need to test behavior dependent on external services, like AWS, or some external databases.

Long story short, instead of mocking, or manual set up of some test environment, we define test dependencies as code. Then, we can run our test code and disposable containers will be started and deleted after they finish.

Let’s take a look at the example from Spring Boot docs:

@Testcontainers
@SpringBootTest
class MyIntegrationTests {

  @Test
  fun myTest() {
    // ...
  }

  companion object {
    @Container
    @JvmStatic
    val neo4j = Neo4jContainer("neo4j:5");
  }
}

The above code runs a Neo4j docker container before the tests. Of course, this is just an example, so most of the time, we will need to add some more config.

Nevertheless, we can clearly see that this Testcontainers JUnit integration allows us to achieve our goal in an easy and neat manner.

Localstack

Localstack, on the other hand, is a cloud service emulator that runs in a single container. In other words, we can run AWS applications or Lambdas without connecting to the remote cloud provider.

And thanks to the Testcontainers module for LocalStack, we can test various AWS integrations with just a few lines of code.

Again, let’s take a look at the example, but this time from the LocalStack documentation:

DockerImageName localstackImage = DockerImageName.parse("localstack/localstack:3.5.0");

@Rule
public LocalStackContainer localstack = new LocalStackContainer(localstackImage)
        .withServices(S3);

You will find links to both documentation at the end of this article. But for now, let’s not distract ourselves and focus on what we came here for 😉

Configure Project

If you are following my S3 series, or you already have a Spring Boot project, then those are the necessary dependencies for us today:

testImplementation("org.springframework.boot:spring-boot-starter-webflux")
testImplementation("org.testcontainers:localstack")
testImplementation("org.springframework.boot:spring-boot-testcontainers")

As we can see, apart from LocalStack and TestContainers, we must provide the Spring Boot Starter WebFlux.

But why?

Well, this is necessary to work with WebTestClient- a client we will use to test our web servers (REST endpoints).

On the other hand, if you would like to set up a project from scratch, then please navigate to the Spring Initializr and select the following:

However, please keep in mind that LocalStack is not provided out of the box in Spring, so we must add it manually.

Moreover, as we have chosen the Spring Web, the WebFlux dependency is not present, too:

testImplementation("org.springframework.boot:spring-boot-starter-webflux")
testImplementation("org.testcontainers:localstack")

Testcontainers Singleton Approach

With all of that being done, let’s head to the practice part.

When working with Testcontainers, we can configure them in various ways:

• we can use the JUnit extension (Jupiter integration)- which allows us to use @Testcontainers and @Container annotations and makes JUnit responsible for the automatic startup and stop of containers in our tests.
• we can configure them manually in every test case,
• or, alternatively, we can use the singleton approach– in which we control containers’ lifecycle manually. But, thanks to that we can easily reuse them across multiple test classes.

Of course, these are not all approaches, and based on your needs you may want to configure Testcontainers differently. Nevertheless, in this tutorial, we will focus on the manual, reusable approach.

Introduce Base Class

Firstly, let’s introduce the LocalStackIntegrationTest:

@SpringBootTest(webEnvironment = RANDOM_PORT)
class LocalStackIntegrationTest { }

As we can see, we mark our class with @SpringBootTest – annotation necessary to run our integration tests and inject the instance of WebTestClient later in our subclasses.

Add Testcontainer

Following, let’s take a look at how to instantiate a LocalStack container:

companion object {
  val localStack: LocalStackContainer = LocalStackContainer(
    DockerImageName.parse("localstack/localstack:3.7.2")
  )
}

Right here, we create an instance of LocalStackContainer and we pass the name of a Docker image – localstack/localstack:3.7.2– to its constructor. Alternatively, if we are working only with AWS S3 Buckets service, then we can use a dedicated image- localstack:s3-latest. But personally, I am not a big fan of the latest tag, which can easily break our code.

Additionally, we put the LocalStackContainer instance in the companion object. Why? Because in the next steps, we will reference it in a function annotated with @DynamicPropertySource– and it must be static.

Note related to JUnit extension:

This is not the case here, as we want to take care of the container lifecycle manually, but, when using the Jupiter integration, containers declared as static fields will be shared between test methods. They will be started only once before any test method is executed and stopped after the last test method has executed. So, if in your case you pick the JUnit extension and don’t want that to happen, then you must not put the localstack in the companion object.

Control Testcontainer lifecycle

As we already know, with this approach we are responsible for the container lifecycle control. And although this may sound complicated, it basically means that without the extension we must start the container manually.

So the companion object after the update will look, as follows:

companion object {
  val localStack: LocalStackContainer = LocalStackContainer(
    DockerImageName.parse("localstack/localstack:3.7.2")
  ).apply {
    start()
  }
}

Basically, we use the Kotlin scope function (you can learn more about it in my Kotlin course) to invoke the start() function on the localStack instance. And as the name suggests, this function will start the container (and pull the image, if necessary).

And basically, that is all we need to do here. With the above code, the container will be started when the base class is loaded and shared across all inheriting test classes.

Of course, there is also the stop() function that we can invoke to kill and remove the container.

Nevertheless, we do not have to do it. Why? Let’s figure out.

Ryuk

Ryuk is a kind of “garbage collector” in Testcontainers.

Whenever we run integration tests, Testcontianers core starts one more container:

Long story short, this container is responsible for removing containers/networks/volumes created by our test cases. So, even if we do not clean the environment ourselves- for example with the stop() function- the Ryuk container will take care of that.

Test Properties With DynamicPropertySource

With that done, we need to update our environment configuration.

If we try to run our Spring Boot application at this point, our logic responsible for communication with Amazon S3 will try to reach the actual AWS instance. It will use the defaults, or make use of the things we configured in the application.yaml.

And this is not what we want, right? Instead, we would like to connect to the Testcontainer LocalStack instance.

In some examples, you might have seen the usage of application properties files. Nevertheless, if we want to be more flexible and make use of containers started on random ports, then the @DynamicPropertySource is our best friend here:

companion object {
  val localStack: LocalStackContainer = LocalStackContainer(
    DockerImageName.parse("localstack/localstack:3.7.2")
  ).apply {
    start()
  }

  @JvmStatic
  @DynamicPropertySource
  fun overrideProperties(registry: DynamicPropertyRegistry) {
    registry.add("spring.cloud.aws.region.static") { localStack.region }
    registry.add("spring.cloud.aws.credentials.access-key") { localStack.accessKey }
    registry.add("spring.cloud.aws.credentials.secret-key") { localStack.secretKey }
    registry.add("spring.cloud.aws.s3.endpoint") { localStack.getEndpointOverride(S3).toString() }
  }

}

Thanks to that annotation, we can dynamically provide values to our test environment based on the LocalStack instance.

Of course, we must remember that methods annotated with @DynamicPropertySource must be static! And that’s why we use it with the @JvmStatic annotation.

Utilize LocalStack AWS CLI

At this point, we have our base class ready, but before we head to the tests, I would like to show you the LocalStack AWS CLI and why and how to use it.

As the first step, let’s create the util package and add the LocalStackUtil.kt file:

import org.testcontainers.containers.localstack.LocalStackContainer

fun LocalStackContainer.createBucket(bucketName: String) {
  this.execInContainer("awslocal", "s3api", "create-bucket", "--bucket", bucketName)
}

fun LocalStackContainer.deleteBucket(bucketName: String) {
  this.execInContainer("awslocal", "s3api", "delete-bucket", "--bucket", bucketName)
}

fun LocalStackContainer.deleteObject(bucketName: String, objectName: String) {
  this.execInContainer("awslocal", "s3api", "delete-object", "--bucket", bucketName, "--key", objectName)
}

As we can see, we introduced 3 helper extension functions that we will later use to create and delete buckets and objects. This way, we can easily clean up between the tests (we use the shared approach, right?). Moreover, it will simplify the setup process for each test case.

The above code combines the execInContainer – which will run the passed command in our running LocalStack container, just like with the docker exec, and the awslocal– a LocalStack wrapper around the AWS CLI. So, if you’ve ever been working with the AWS command line interface, then you will see that this is 1:1.

Unfortunately, we must provide the command as a separate String value, because otherwise, we will end up with:

OCI runtime exec failed: exec failed: container_linux.go:380: starting container process caused: exec: “awslocal s3api create-bucket –bucket bucket-1”: executable file not found in $PATH: unknown

Write Integration Test Cases

With all of that LocalStack preparation done (I know, quite a bunch of things to learn, but once you learn this, it will be a simple copy-paste), we can finally write some integration tests for our Spring Boot S3 integration.

Firstly, let’s create the controller package and put the BucketControllerIntegrationTest class:

class BucketControllerIntegrationTest(
  @Autowired private val webTestClient: WebTestClient
) : LocalStackIntegrationTest() { }

As we can see, no annotations are required. We simply extend the LocalStackIntegrationTest class and inject the WebTestClient.

Test No Buckets Exist

Nextly, let’s introduce our first test case. If we do not do anything, we expect that no buckets exist in our S3 instance:

@Test
fun `Given no existing buckets When getting list of buckets Then return an empty array`() {
  val buckets = webTestClient
    .get().uri("/buckets")
    .exchange()
    .expectStatus().isOk()
    .expectBody(object : ParameterizedTypeReference<List<String>>() {})
    .returnResult()
    .responseBody

  assertNotNull(buckets)
  assertTrue(buckets.isEmpty())
}

As mentioned before, we use the WebTestClient to make a GET HTTP request to the /buckets endpoint. Then, we use a small hack with ParameterizedTypeReference– because the endpoint returns a list of Strings and we use Kotlin- and we obtain the response body.

Lastly, we have plain assertions. We verify that the response body is not null and that our S3 bucket list is empty.

Verify S3 Bucket Exists In LocalStack

Following, let’s see our helper functions in action:

@Test
fun `Given one existing bucket When getting list of buckets Then return an array with expected bucket name`() {
  val bucketName = "bucket-1"
  localStack.createBucket(bucketName)

  val expectedJson = """
    [ "Bucket #1: $bucketName" ]
  """

  webTestClient
    .get().uri("/buckets")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expectedJson)

  localStack.deleteBucket(bucketName)
}

This time, we utilize the createBucket and make sure that the /buckets endpoint returns the expected JSON. Please note that this is another way to assert the response body.

After all, we delete the existing bucket, so it won’t affect other test cases.

Assert Bucket Created Successfully

As the next step, let’s take a look at how we can check if our endpoint responsible for creating new S3 buckets works. And I see two paths we can go here.

The first one, using the execInContainer:

@Test
fun `Given no existing buckets When creating bucket Then create bucket successfully`() {
  val bucketName = "bucket-2"
  
  webTestClient
    .post().uri("/buckets")
    .bodyValue(BucketRequest(bucketName = bucketName))
    .exchange()
    .expectStatus().isOk()
  
  val execResult = localStack.execInContainer("awslocal", "s3api", "list-buckets").stdout
  
  assertTrue(execResult.contains(bucketName))  
  localStack.deleteBucket(bucketName)
}

The important thing to mention here is that the execInContainer returns the ExecResult. And thanks to that, we can read additional info, like stdout, stderr, or exitCode.

And thanks to the stdout, we can get this JSON to verify it contains particular bucket name (or even we could parse that to an object):

{
  "Buckets": [
    {
      "Name": "bucket-2",
      "CreationDate": "2024-09-19T05:28:42.000Z"
    }
  ],
  "Owner": {
    "DisplayName": "webfile",
    "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
  }
}

Alternatively, we can use the /buckets endpoint once again, too:

@Test
fun `Given no existing buckets When creating bucket Then create bucket successfully`() {
  val bucketName = "bucket-2"

  webTestClient
    .post().uri("/buckets")
    .bodyValue(BucketRequest(bucketName = bucketName))
    .exchange()
    .expectStatus().isOk()

  val expectedJson = """
    [ "Bucket #1: $bucketName" ]
  """
  webTestClient
    .get().uri("/buckets")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expectedJson)

  localStack.deleteBucket(bucketName)
}

Test Remaining Cases

The remaining cases of our integration test use a more or less similar approach, so I will simply copy-paste them here so that you can analyze them.

At this point, I am pretty sure you understand the general idea behind what I understand by testing of Spring Boot S3 integration with LocalStack, so I don’t see the need for explaining them one- by one:

@Test
fun `Given no objects existing in the bucket When getting objects of a bucket Then return an empty array`() {
  val bucketName = "bucket-3"
  localStack.createBucket(bucketName)

  val objects = webTestClient
    .get().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()
    .expectBody(object : ParameterizedTypeReference<List<String>>() {})
    .returnResult()
    .responseBody

  assertNotNull(objects)
  assertTrue(objects.isEmpty())

  localStack.deleteBucket(bucketName)
}

@Test
fun `Given no objects When creating example object Then return created object`() {
  val bucketName = "bucket-4"
  val objectName = "example.json"
  localStack.createBucket(bucketName)

  val expectedJson = """
    {
      "id": "123",
      "name": "Some name"
    }
  """

  webTestClient
    .post().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expectedJson)

  localStack.deleteObject(bucketName, objectName)
  localStack.deleteBucket(bucketName)
}

@Test
fun `Given created object When getting list of objects Then return array with one object`() {
  val bucketName = "bucket-5"
  val objectName = "example.json"
  localStack.createBucket(bucketName)

  val expectedJson = """
    [ $objectName ]
  """

  webTestClient
    .post().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()

  webTestClient
    .get().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expectedJson)

  localStack.deleteObject(bucketName, objectName)
  localStack.deleteBucket(bucketName)
}

@Test
fun `Given existing object When getting object by key Then return object content`() {
  val bucketName = "bucket-6"
  val objectName = "example.json"
  localStack.createBucket(bucketName)

  val expected = """
    {
      "id": "123",
      "name": "Some name"
    }
  """

  webTestClient
    .post().uri("/buckets/$bucketName/objects")
    .exchange()

  webTestClient
    .get().uri("/buckets/$bucketName/objects/$objectName")
    .exchange()
    .expectStatus().isOk()
    .expectBody()
    .json(expected)

  localStack.deleteObject(bucketName, objectName)
  localStack.deleteBucket(bucketName)
}

@Test
fun `Given existing bucket with object When deleting bucket Then bucket is removed`() {
  val bucketName = "bucket-7"
  localStack.createBucket(bucketName)

  webTestClient
    .post().uri("/buckets/$bucketName/objects")
    .exchange()
    .expectStatus().isOk()

  webTestClient
    .delete().uri("/buckets/$bucketName")
    .exchange()
    .expectStatus().isOk()

  val buckets = webTestClient
    .get().uri("/buckets")
    .exchange()
    .expectStatus().isOk()
    .expectBody(object : ParameterizedTypeReference<List<String>>() {})
    .returnResult()
    .responseBody

  assertNotNull(buckets)
  assertTrue(buckets.isEmpty())
}

Summary

And that is all for this tutorial, in which we learned how to implement integration tests for Spring Boot AWS S3 integration with LocalStack and Testcontainers.

I hope you enjoyed it and for the source code, please visit this GitHub repository.

Have a great day and see you in the next articles! 🙂

The post Test Spring Boot AWS S3 with Localstack and Testcontainers appeared first on Codersee blog- Kotlin on the backend.

As an example, we will implement a simple logic responsible for querying the GitHub API using coroutines. Nevertheless, I am pretty sure you will be able to easily adjust this article to your needs. (of course, if you are here only for the WireMock part, then I recommend skipping to the “WebClient Integration Testing With WireMock” chapter).

Lastly, I just wanted to add that you can use this testing approach regardless of whether you are using WebClient, Retrofit, Ktor Client, or any other HTTP client.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription 🙂

Which WebClient Testing Strategy Is The Best?

But before we head to the practice part, let’s try to answer the above question.

Quick answer- there is no such thing as the best testing strategy.

And for the longer answer, let’s take a look at the visualization of the testing pyramid first:

The tests are ordered based on their scope and execution time. The closer we are to the top, the longer the tests take, but they also give us more confidence.

• unit tests form the base, as they are quick to run and pinpoint specific code issues,
• integration tests come next, validating the interactions between units,
• E2E tests, with a broader scope, are placed at the top.

So long story short, although the e2e tests give us the most confidence, we cannot rely only on them, because the feedback loop would take way too long. And this would affect the development process.

So usually, we make concessions and introduce more integration and unit tests.

But which of these two should we pick for the WebClient?

In my opinion- integration tests.

Whenever we are talking about logic responsible for communicating with external API, we must make sure that:

• we query the appropriate URL,
• we pass the necessary headers with appropriate values,
• request/response bodies are properly serialized/deserialized,
• and many, many more.

With unit testing, the amount of mocking here would be so significant that I would question whether we need such a test at all.

Moreover, in Spring we can write integration tests for WebClient with WireMock at almost no effort.

Set Up GitHub API Key

With that said, let’s set up the API key we will use to query the GitHub API.

Note: technically, the endpoint we will use does not require any token. However, for the learning purposes I want to show you how to deal with passing bearer tokens, too 🙂

As the first step, let’s navigate to the tokens tab in GitHub settings and click the “Generate new token (classic)”:

On the next page, let’s specify the name, expiration, and desired scopes:

If you don’t know what scopes you will need, please follow the principle of lowest privilege. At the end of the day, we can generate a new token at some point in the future when the requirements change.

When we are ready, let’s hit the generate button copy the token value, and store it securely. We will not see it again!

Query The Api With WebClient

Before we implement the WireMock tests, let’s prepare a simple project responsible for querying the external API with WebClient. So, even if you are here only for the WireMock part, I encourage you to briefly check this paragraph to be on the same page 😉

Long story short, we will implement WebClient with coroutines that will query the “List repositories for a user” endpoint. For more details about it, check out the GitHub API documentation, please.

Generate New Project

As the first step, let’s navigate to the https://start.spring.io/ page and generate a fresh Spring Boot project:

In general, the most important thing is that we will use Kotlin and Spring Reactive Web this time. Versions and metadata are totally up to you.

Of course, let’s click the “Generate” button, download the ZIP file, and import that to our IDE. Personally, I am using IntelliJ IDEA and if you would like to learn more about its setup, then check out my video on how to install IntelliJ for Kotlin development.

Update Application Properties

As the next step, let’s navigate to the resources package and update the application.yaml file:

api:
  github:
    key: ${GITHUB_API_TOKEN:123}
    url: ${GITHUB_API_BASE_URL:http://localhost:8090}
    version: ${GITHUB_API_VERSION:2022-11-28}

Above we can see our custom properties.

We will source values for our GitHub key, URL, and version from environment variables.

Not only is this approach secure (hardcoding the key with token value would be the worst thing you could do), but also flexible (we can pass different values depending on the environment we are running our app in).

WebClient Configuration

Following, let’s configure a WebClient bean that we will use whenever we want to call the GitHub API.

Firstly, let’s add the config package and put the GitHubApiProperties data class in there:

@ConfigurationProperties("api.github")
data class GitHubApiProperties(
    val url: String,
    val key: String,
    val version: String,
)

In my opinion, the @ConfigurationProperties annotation is the cleanest way to inject values from properties. As we can see above, the prefix and field names simply reflect the structure from the previous step.

With that done, let’s add the GitHubApiConfig in the same package:

@Configuration
@EnableConfigurationProperties(GitHubApiProperties::class)
class GitHubApiConfig(
    private val gitHubApiProperties: GitHubApiProperties,
) {
    @Bean
    fun webClient(builder: WebClient.Builder): WebClient =
        builder
            .baseUrl(gitHubApiProperties.url)
            .defaultHeader("Authorization", "Bearer ${gitHubApiProperties.key}")
            .defaultHeader("X-GitHub-Api-Version", gitHubApiProperties.version)
            .defaultHeader("Accept", "application/vnd.github+json")
            .build()
}

Quite a few things are happening here, so let’s dive into each one.

Firstly, we annotate the class with @Configuration and @EnableConfigurationproperties. The second annotation is necessary to for the previous steps to work.

Then, we inject the GitHubApiProperties instance and use its values to configure a new WebClient bean. This configuration is quite straightforward. We set the base URL and a bunch of headers that will be sent with every request: the authorization token, GH API version, and the accept header (those two are specific to the GitHub API, so let’s focus on that too much).

Prepare Model Classes

With that done, let’s prepare a bunch of data classes that we will need to deserialize JSON responses from the API (+ one exception class). If you would like to add other fields, please check out the documentation link I shared with you before.

As the first step, let’s add the model package and the PageableGitHubResponse:

data class PageableGitHubResponse<T>(
    val items: List<T>,
    val hasMoreItems: Boolean,
)

The API endpoints allow us to get only a chunk of data using the page and per_page parameters. And this class can be reused whenever we’re using a paginated endpoint.

As the next step, let’s implement the GitHubRepoResponse along with GitHubOwnerResponse:

data class GitHubRepoResponse(
    val fork: Boolean,
    val name: String,
    val owner: GitHubOwnerResponse,
)

data class GitHubOwnerResponse(
    val login: String,
)

As I mentioned at the beginning of this paragraph, we need those two in order to deserialize the actual JSON response payload.

Lastly, let’s add the UpstreamApiException:

import org.springframework.http.HttpStatusCode

data class UpstreamApiException(
    val msg: String,
    val statusCode: HttpStatusCode,
) : RuntimeException(msg)

This way, we will be able to throw custom exceptions. Such an exception could be handled later, for example with @RestControllerAdvice.

Make Use Of WebClient

Finally, let’s combine all of that together.

So, let’s add the api package and implement the GitHubApi class:

@Component
class GitHubApi(
  private val webClient: WebClient,
) {

  suspend fun listRepositoriesByUsername(
    username: String,
    page: Int,
    perPage: Int,
  ): PageableGitHubResponse<GitHubRepoResponse>? =
    webClient.get()
      .uri("/users/$username/repos?page=$page&per_page=$perPage")
      .awaitExchangeOrNull(::mapToPageableResponse)
}

Don’t worry about the mapToPageableResponse, we will add it in a moment.

But before that, let’s analyze the above code.

Firstly, we annotate the class as the @Component to make it a Spring bean and inject the WebClient instance we configured earlier. We don’t have other WebClient instances, so there is no need to use @Qualifier or anything like that.

Following, we add the listRepositoriesByUsername function that lets us pass the username along with page and perPage. This way, we make this function reusable and allow the invoker to decide how to tackle the pagination.

Additionally, we mark it as a suspend function because the awaitExchangeOrNull is a suspend function. However, if you are interested in this topic, then I refer you to my other article about WebClient with coroutines.

Lastly, let’s add the missing code:

private suspend inline fun <reified T> mapToPageableResponse(clientResponse: ClientResponse): PageableGitHubResponse<T>? {
  val hasNext = checkIfMorePagesToFetch(clientResponse)

  return when (val statusCode = clientResponse.statusCode()) {
    HttpStatus.OK ->
      PageableGitHubResponse(
        items = clientResponse.awaitBody<List<T>>(),
        hasMoreItems = hasNext,
      )

    HttpStatus.NOT_FOUND -> null

    else -> throw UpstreamApiException(
      msg = "GitHub API request failed.",
      statusCode = statusCode,
    )
  }
}

fun checkIfMorePagesToFetch(clientResponse: ClientResponse) =
  clientResponse.headers()
    .header("link")
    .firstOrNull()
    ?.contains("next")
    ?: false

Long story short, the above code works as follows:

1. Firstly, we take the response and check if there are more pages. How? Well, without going into details, GitHub API returns the link header. And if its value contains the rel="next", it means that there are more pages to fetch.
2. Finally, we check the status code. If it is 200 OK, we simply read the JSON value. When we get 404 Not Found, we return null (we can expect this status code when we pass a non-existing username, and in my opinion, this case is not exceptional). And whenever we receive another status code, we simply throw the UpstreamApiException.

WebClient Integration Testing With WireMock

Excellent, at this point we have (almost) everything we need to test our WebClient implementation with WireMock.

We will see only a few example test cases that you will be able to easily adapt according to your needs:

• 200 OK response with an empty list, 200 OK with items, and more pages, and 200 OK with items and no more pages to fetch
• 404 Not Found,
• 401 Unauthorized

When you will be implementing your own integration tests, this is the moment when you should do the homework and analyze the API you are working with. What are the possible happy paths? How should your code behave in case of any error status code? What if we add some latency? And many, many more 🙂

Additional Dependencies

At this point, we defined our test cases, so we are ready to get our hands dirty.

So, let’s start by adding the necessary dependencies:

testImplementation("org.springframework.cloud:spring-cloud-contract-wiremock:4.1.1")
testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")

As we can see, the first one- the Spring Cloud Contract WireMock module- allows us to use WireMock in our app, whereas the kotlinx-coroutines-test is necessary due to our coroutines WebClient implementation.

Add Expected JSON Files

So, if we know what test cases we would like to test, we should prepare the example JSON API responses.

Personally, whenever working with WireMock I am a big fan of externalizing the expected JSON files. We put them inside the /test/resources directory and refer to them later in the tests. This way, we can improve the readability of the test classes. Of course, unless we want to prepare JSON responses dynamically.

In our case, we could simply invoke the GitHub API and persist responses for different cases. This way, we prepare the following files and put them inside the /test/resources/responses/external/github:

• list_github_repositories_200_OK_empty_list.json
• list_github_repositories_200_OK_page_1.json
• list_github_repositories_401_UNAUTHORIZED.json
• list_github_repositories_404_NOT_FOUND.json

You can find all of these files in my GH repo here.

The example for 401 Unauthorized looks as follows:

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}

Prepare Util Function

As the last thing before we implement our test class, let’s add the util function inside the util package (of course, in tests).

This function will be responsible for reading JSON files inside the test resources as String values:

import org.springframework.core.io.ClassPathResource

fun getResponseBodyAsString(path: String): String =
    ClassPathResource(path).getContentAsString(
        Charsets.UTF_8,
    )

Implement GitHubApiTest Class

Finally, let’s start implementing the GitHubApiTest class:

private const val TEST_KEY = "TEST_KEY"
private const val TEST_PORT = 8082
private const val TEST_VERSION = "2022-11-28"

@AutoConfigureWireMock(port = TEST_PORT)
@TestPropertySource(
  properties = [
    "api.github.url=http://localhost:${TEST_PORT}",
    "api.github.key=$TEST_KEY",
    "api.github.version=$TEST_VERSION",
  ],
)
@SpringBootTest(
  webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
)
class GitHubApiTest {
  @Autowired
  private lateinit var wireMockServer: WireMockServer

  @Autowired
  private lateinit var gitHubApi: GitHubApi

  private val page = 1
  private val perPage = 2
  private val username = UUID.randomUUID().toString()

}

Conceptually, everything starts with the @SpringBootTest and @AutoConfigureWireMock annotations.

We use the @SpringBootTest annotation in Spring Boot integration tests. This way a new ApplicationContext will be created. In our case, we set the webEnvironment with RANDOM_PORT value, so that a reactive context listening on the random port is created.

Additionally, we combine that together with @AutoConfigureWireMock and fixed test port. This way a WireMock server will be started as a part of Application Context.

Lastly, we do 3 things:

1. We use the @TestPropertySource to pass values for properties.
2. We inject the WireMockServer and GitHubApi instances that we will work with later. Please note that we can do that just like we would do with a standard, non-test, Spring component.
3. We prepare some dummy data for page, perPage, and username values we will need for testing.

As a note of comment from my side- this “skeleton” is useful whenever working with WebClient and WireMock.

Test 404 Not Found API Response Case

Wonderful!

As the first test, let’s start with the 404 Not Found case. Usually, we will start with happy path cases, but for learning purposes, this one is the shortest case 😉

@Test
fun `Given 404 NOT FOUND response When fetching repository by username Then should return null`() = runTest {
  // Given
  wireMockServer.stubFor(
    WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
      .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
      .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
      .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
      .willReturn(
        WireMock.aResponse()
          .withStatus(HttpStatus.NOT_FOUND.value())
          .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
          .withBody(
            getResponseBodyAsString("/responses/external/github/list_github_repositories_404_NOT_FOUND.json"),
          ),
      ),
  )

  // When
  val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

  // Then
  Assertions.assertNull(result)
}

We mark our test with the @Test (JUnit 5), specify the meaningful name for the test (with awesome Kotlin backticks), and wrap our test with runTest. The last one is necessary as we are working with coroutines and invoke the suspended function. Long story short, in JVM it will behave just like runBlocking (but it will skip delays).

Next comes the WireMock part. And to be even more specific- stubbing.

Stubbing is nothing else than “the ability to return canned HTTP responses for requests matching criteria” (from docs). Simply said, whenever an outgoing request that matches our criteria is made, a mocked response configured in willReturn is returned.

So, as we can see, the above logic will work only when:

• the GET request is made,
• URL matches,
• Headers sent have appropriate values

And this part already tests our logic. Pretty neat, isn’t it? 🙂

Lastly, we simply invoke the function and assert that null is returned. Which confirms that everything is working fine.

Test 401 Unauthorized

As we already started with error cases, let’s verify that whenever the endpoint returns 401 Unauthorized, the UpstreamApiException is thrown:

@Test
fun `Given 401 UAUTHORIZED response When fetching repository by username Then should throw UpstreamApiException`() = runTest {
  // Given
  wireMockServer.stubFor(
    WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
      .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
      .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
      .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
      .willReturn(
        WireMock.aResponse()
          .withStatus(HttpStatus.UNAUTHORIZED.value())
          .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
          .withBody(
            getResponseBodyAsString("/responses/external/github/list_github_repositories_401_UNAUTHORIZED.json"),
          ),
      ),
  )

  // When
  val exception = assertThrows<UpstreamApiException> {
    gitHubApi.listRepositoriesByUsername(username, page, perPage)
  }

  // Then
  assertNotNull(exception)

  assertEquals("GitHub API request failed.", exception.msg)
  assertEquals(HttpStatus.UNAUTHORIZED, exception.statusCode)
}

As we can see, the logic responsible for stubbing only slightly changed.

The interesting part here is the assertThrows, which not only makes sure that the exception of an appropriate type is thrown but also returns it. This way we can make additional assertions.

Verify 200 OK With Empty List

Following, let’s cover the empty list case:

@Test
fun `Given 200 OK response with empty list When fetching repository by username Then should return repository with correct properties and has next false`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="prev","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_empty_list.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items = emptyList<GitHubRepoResponse>(),
        hasMoreItems = false,
      )

    assertEquals(expected, result)
  }

This time, we assign the returned value to the result and compare that with the expected.

Check 200 OK With Has Next True

Last before least, let’s make sure that we got the expected objects in a list and that the logic responsible for the link header check returns true:

@Test
fun `Given 200 OK response with payload When fetching repository by username Then should return repository with correct properties and has next true`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="next","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_page_1.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items =
        listOf(
          GitHubRepoResponse(
            fork = false,
            name = "controlleradvice-vs-restcontrolleradvice",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
          GitHubRepoResponse(
            fork = false,
            name = "freecodecamp-spring-boot-kotlin-excel",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
        ),
        hasMoreItems = true,
      )

    assertEquals(expected, result)
  }

Test 200 OK With Has Next False

And finally, let’s double-check the flag logic:

@Test
fun `Given 200 OK response with payload When fetching repository by username Then should return repository with correct properties and has next false`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="prev","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_page_1.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items =
        listOf(
          GitHubRepoResponse(
            fork = false,
            name = "controlleradvice-vs-restcontrolleradvice",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
          GitHubRepoResponse(
            fork = false,
            name = "freecodecamp-spring-boot-kotlin-excel",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
        ),
        hasMoreItems = false,
      )

    assertEquals(expected, result)
  }

Integration Tests With WireMock And WebClient Summary

And basically, that’s all for this tutorial on how to perform integration testing for Spring WebClient that invokes external REST APIs with WireMock and JUnit 5.

I hope you enjoyed this one and I recommend you check out my other articles related to Spring Framework.

The post Integration Tests for WebClient with WireMock appeared first on Codersee blog- Kotlin on the backend.

To be even more specific- we will work with an application that exposes a REST API and connects to MongoDB. If you would like to learn how to do that step-by-step, then you can check out my other article. (But don’t worry, we will see its code snippets in this tutorial, too).

For testing, we’re going to use JUnit 5, MockK, REST Assured, as well as the @MicronautTest and Micronaut Test Resources.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

Micronaut Project Overview

Let’s start everything by checking the project we will test today. Of course, we will focus on the most important parts, and for the full source code, I invite you to this GitHub repository.

Application Properties

In our project, we introduce 3 application properties files:

// application.properties
micronaut.application.name=micronaut-testing

// application-mongo.properties
mongodb.uri=mongodb://localhost:27017/example

// application-test.properties
mongodb.package-names=com.codersee.model

The application name is the default property inserted when generating a new project.

Nevertheless, the two remaining are created on purpose. With their names- *mongo, *test– we instruct Micronaut that it should consider them only when mongo and test profiles are active.

But why this way? Well, to avoid two issues.

MongoDB Connection Issues with Micronaut Test Resources

So, let’s start everything by explaining why we don’t put the Mongo URI inside the main properties.

Well, when we use the Micronaut Test Resources, MongoDB support will start a MongoDB container and provide the value of the mongodb.uri property.

Nevertheless, this won’t happen when we explicitly set the URI in the application properties. And that’s why we want to make this setting available only when we set the environment to mongo.

CodecCacheKey Issue

Additionally, if we don’t specify explicitly the package name, where our model classes live, we’re going to end up with the following issue when running our Micronaut tests:

[io-executor-thread-1] ERROR i.m.http.server.RouteExecutor - Unexpected error occurred: Can't find a codec for CodecCacheKey{clazz=class com.codersee.model.AppUser, types=null}.
org.bson.codecs.configuration.CodecConfigurationException: Can't find a codec for CodecCacheKey{clazz=class com.codersee.model.AppUser, types=null}.
  at org.bson.internal.ProvidersCodecRegistry.lambda$get$0(ProvidersCodecRegistry.java:87)
  at java.base/java.util.Optional.orElseGet(Optional.java:364)
  at org.bson.internal.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:80)
  at org.bson.internal.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:50)
  at com.mongodb.internal.operation.Operations.createFindOperation(Operations.java:188)
...

To me, looks like a bug. But thankfully, we can easily avoid that by putting that in the application-test.properties (which is used in tests by default).

Models

Following, we introduce a bunch of models:

// Address.kt: 

import io.micronaut.serde.annotation.Serdeable

@Serdeable.Serializable
@Serdeable.Deserializable
data class Address(
  val street: String,
  val city: String,
  val code: Int
)

// AppUser.kt:

import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity

@MappedEntity
data class AppUser(
  @field:Id
  @field:GeneratedValue
  val id: String? = null,
  val firstName: String,
  val lastName: String,
  val email: String,
  val address: Address
)

// AppUserRequest.kt: 

import io.micronaut.serde.annotation.Serdeable

@Serdeable.Deserializable
data class AppUserRequest(
  val firstName: String,
  val lastName: String,
  val email: String,
  val street: String,
  val city: String,
  val code: Int
)

// SearchRequest.kt:

import io.micronaut.serde.annotation.Serdeable

@Serdeable.Deserializable
data class SearchRequest(val name: String)

Those classes are either used to persist/retrieve data from MongoDB or when deserializing JSON payloads into the objects.

Repository

Following, we have a repository layer responsible for communicating with our storage:

// AppUserRepository.kt: 

import com.codersee.model.AppUser
import io.micronaut.data.mongodb.annotation.MongoFindQuery
import io.micronaut.data.mongodb.annotation.MongoRepository
import io.micronaut.data.repository.CrudRepository

@MongoRepository
interface AppUserRepository : CrudRepository<AppUser, String> {

  fun findByFirstNameEquals(firstName: String): List<AppUser>

  @MongoFindQuery("{ firstName: { \$regex: :name}}")
  fun findByFirstNameLike(name: String): List<AppUser>
}

Service

Nextly, the service layer, where we inject the repository and encapsulate its methods:

// AppUserService.kt:

import com.codersee.model.Address
import com.codersee.model.AppUser
import com.codersee.model.AppUserRequest
import com.codersee.repository.AppUserRepository
import io.micronaut.http.HttpStatus
import io.micronaut.http.exceptions.HttpStatusException
import jakarta.inject.Singleton

@Singleton
class AppUserService(
  private val appUserRepository: AppUserRepository
) {

  fun create(userRequest: AppUserRequest): AppUser =
    appUserRepository.save(
      userRequest.toAppUserEntity()
    )

  fun findAll(): List<AppUser> =
    appUserRepository
      .findAll()
      .toList()

  fun findById(id: String): AppUser =
    appUserRepository.findById(id)
      .orElseThrow { HttpStatusException(HttpStatus.NOT_FOUND, "User with id: $id was not found.") }

  fun update(id: String, updateRequest: AppUserRequest): AppUser {
    val foundUser = findById(id)

    val updatedEntity =
      updateRequest
        .toAppUserEntity()
        .copy(id = foundUser.id)

    return appUserRepository.update(updatedEntity)
  }

  fun deleteById(id: String) {
    val foundUser = findById(id)

    appUserRepository.delete(foundUser)
  }

  fun findByNameLike(name: String): List<AppUser> =
    appUserRepository
      .findByFirstNameLike(name)

  private fun AppUserRequest.toAppUserEntity(): AppUser {
    val address = Address(
      street = this.street,
      city = this.city,
      code = this.code
    )

    return AppUser(
      id = null,
      firstName = this.firstName,
      lastName = this.lastName,
      email = this.email,
      address = address
    )
  }
}

Controller

And lastly, the place where we expose our REST endpoints:

// AppUserController.kt: 

import com.codersee.model.AppUserRequest
import com.codersee.service.AppUserService
import com.codersee.model.SearchRequest
import com.codersee.model.AppUser
import io.micronaut.http.HttpStatus
import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

@Controller("/users")
@ExecuteOn(TaskExecutors.IO)
class AppUserController(
  private val appUserService: AppUserService
) {

  @Get
  fun findAllUsers(): List<AppUser> =
    appUserService.findAll()

  @Get("/{id}")
  fun findById(@PathVariable id: String): AppUser =
    appUserService.findById(id)

  @Post
  @Status(HttpStatus.CREATED)
  fun createUser(@Body request: AppUserRequest): AppUser =
    appUserService.create(request)

  @Post("/search")
  fun searchUsers(@Body searchRequest: SearchRequest): List<AppUser> =
    appUserService.findByNameLike(
      name = searchRequest.name
    )

  @Put("/{id}")
  fun updateById(
    @PathVariable id: String,
    @Body request: AppUserRequest
  ): AppUser =
    appUserService.update(id, request)

  @Delete("/{id}")
  @Status(HttpStatus.NO_CONTENT)
  fun deleteById(@PathVariable id: String) =
    appUserService.deleteById(id)
}

Simple Kotlin Testing in Micronaut

Excellent. At this point, we know what exactly we are going to test.

And as the first approach we’re going to see will be a plain, old unit test.

Why?

Because at the end of the day, that’s what we will be dealing with most of the time.

So with that said, let’s take a look at the example test:

  import com.codersee.repository.AppUserRepository
import io.mockk.every
import io.mockk.mockk
import io.mockk.verify
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test

class AppUserServiceTest {

  private val appUserRepository = mockk<AppUserRepository>()

  private val appUserService = AppUserService(appUserRepository)

  @Test
  fun `should return empty user list`() {
    every {
      appUserRepository.findAll()
    } returns emptyList()

    val result = appUserService.findAll()

    assertTrue(result.isEmpty())

    verify(exactly = 1) { appUserRepository.findAll() }
  }
}

As we can see above, we simply mock (with MockK) the AppUserRepository and inject it into the AppUserService instance.

Then, we specify that all invocations of the findAll method must return the empty list (with every).

Lastly, we assert that the findAll method from our service returns an empty list (assertTrue) and that the findAll method from the repository was invoked only once (verify).

Nevertheless, we’re not going to spend too much here right now as this tutorial focuses on Micronaut testing in Kotlin. If you are interested in learning more about these tools, then let me know in the comments section 🙂

Integration Testing with @MicronautTest

With all of that done, let’s see how the Micronaut framework helps us with testing and a few interesting cases that will help us in real life.

What is a @MicronautTest?

Let’s start everything by explaining what exactly is the @MicronautTest.

In simple words, it’s an annotation that we can put on the test class to mark it a Micronaut test (no sh… Sherlock 🙂 :

import io.micronaut.test.extensions.junit5.annotation.MicronautTest

@MicronautTest
class SomeTest {
  // tests
}

In practice, it means that when we run a test with that annotation, it will run a real application. It will use internal Micronaut features with no mocking. So at this point, we can clearly see that this will be the right solution for integration testing.

Moreover, this annotation can be used not only with JUnit 5, but also with Spock, Kotest, and Kotest 5.

@MicronautTest Configuration Options

The @MicronautTest allows us to configure a few properties, like the environments we want to run our test with, the packages to scan, or whether the automatic transaction wrapping should be enabled, or not:

import io.micronaut.test.extensions.junit5.annotation.MicronautTest

@MicronautTest(
  environments = ["env-1, env-2"],
  packages = ["com.codersee.somepackage"],
  transactional = false
)
class SomeTest {
  // tests
}

For the full list of options, I highly encourage you to check out the docs (we can do that for instance in IntelliJ IDEA by clicking on the annotation with the left mouse button when we keep the left ctrl pressed).

What Are Micronaut Test Resources?

At the beginning of this tutorial, I mentioned the Micronaut Test Resources and I would like to make sure that we are on the same page with them.

So basically, Micronaute Test Resources integrates seamlessly with Testcontainers to provide throwaway containers for testing. But, we need to remember that Testcontainers require Docker-API compatible container runtime (in simple words- either Docker installed locally, or the Testcontainers Cloud).

In our case, we would like to do integration tests that require MongoDB. We could make use of the real database (which sometimes may be the case for you), provide some H2 database (not the best approach), or integrate Testcontainers. Thankfully, we don’t need to do that and the only thing we need is the appropriate import in our project:

plugins {
    id("io.micronaut.test-resources") version "4.2.1"
}

As a reminder, I want to emphasize that test resources will be used only when the datasources.default.url is missing. (and that’s why we removed the URI for MongoDB from tests).

Integration Tests With REST Assured

With all of that said, let’s combine everything together and test our Kotlin Micronaut application with JUnit 5 and REST Assured.

To do so, we must remember to add the necessary import:

testImplementation("io.micronaut.test:micronaut-test-rest-assured")

Verify Status Codes and Headers

Let’s start with a simple request to the GET /users endpoint:

@MicronautTest
class AppUserControllerTestWithoutMocking {

  @Test
  fun `should return 200 OK on GET users`(spec: RequestSpecification) {
    spec
      .`when`()
      .get("/users")
      .then()
      .statusCode(200)
      .header("Content-Type", "application/json")
  }

}

As I mentioned previously- by default, with @MicronautTest the real application is started. Moreover, nothing here is mocked, so the Mongo test container delivered by the Micronaut Test Resources is used.

Thanks to the dedicated module we added, we can inject the RequestSpecification into our tests and easily validate our endpoint.

In this case, we perform a GET request and verify that the response status code is 200 OK and the response Content-Type header value is application/json.

Verify 404 Not Found

Similarly, we can verify that no entry is present in the database:

@Test
fun `should return 404 Not Found on GET user by ID`(spec: RequestSpecification) {
  spec
    .`when`()
    .get("/users/123123123123123123121231")
    .then()
    .statusCode(404)
}

This test will be also good proof that entries inserted to MongoDB in other tests do not affect other tests.

Extract and JSON Array in REST Assured

Nextly, let’s take a look at the more complicated example:

@Test
fun `should create a user`(spec: RequestSpecification) {
  val request = AppUserRequest(
    firstName = "Piotr",
    lastName = "Wolak",
    email = "contact@codersee.com",
    street = "Street",
    city = "City",
    code = 123,
  )

  spec
    .`when`()
    .contentType(ContentType.JSON)
    .body(request)
    .post("/users")
    .then()
    .statusCode(201)

  val list = spec
    .`when`()
    .get("/users")
    .then()
    .statusCode(200)
    .body("size()", `is`(1))
    .extract()
    .`as`(object : TypeRef<List<AppUser>>() {})

  assertEquals(1, list.size)

  val createdUser = list.first()

  assertEquals(request.firstName, createdUser.firstName)
  assertEquals(request.street, createdUser.address.street)
}

This time, we do a bunch of more interesting things.

Firstly, we make the POST request with a request body and verify that 201 Creates is returned.

After that, we call the GET /users endpoint to get a list of users. When we get the response, we verify that the JSON array size is equal to 1 (with the .body("size()", is(1)) call). Lastly, we make use of the extract().`as` to convert the payload into the List of AppUser instances. Thanks to that we can easily perform assertions with JUnit 5 functions.

Add Kotlin Utils For REST Assured

As you probably know, when and as are keywords in Kotlin and that’s why we had to use backticks (“).

And to make our lives easier, let’s add the util package in test and create the TestUtil.kt:

import io.restassured.common.mapper.TypeRef
import io.restassured.response.ValidatableResponse
import io.restassured.specification.RequestSpecification


fun RequestSpecification.whenever(): RequestSpecification {
  return this.`when`()
}

fun <T> ValidatableResponse.extractAs(clazz: Class<T>) =
  this.extract()
    .`as`(clazz)

fun <T> ValidatableResponse.extractAs(typeRef: TypeRef<T>) =
  this.extract()
    .`as`(typeRef)

As a result, from now on we can simply use the whenever() instead of `when`() and extractAs() instead of extract().`as`().

Reference The Server / Context

As the next step, let’s take a look at how to reference the server or current application context:

@MicronautTest
class InjectingExample{

  @Inject
  private lateinit var context: ApplicationContext

  @Inject
  private lateinit var server: EmbeddedServer

  // tests
}

Sometimes it can be useful, and as we can see, we can simply inject them using the @Inject annotation.

Conditionally Run Tests

After that, let’s see how we can skip tests execution.

Why would we need that?

Well, integration tests sometimes can take a lot of time, and the bigger our project becomes, the bigger the chance they become annoying. And because of that, generally, it’s a good approach to somehow separate them from the faster unit tests.

When testing in Micronaut, we can easily achieve that using the @Requires annotation:

import io.micronaut.context.annotation.Requires
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test

@MicronautTest
@Requires(env = ["integration-test"])
class SomeIntegrationTest {

  @Test
  fun `should perform integration test`() {
    assertTrue(false)
  }

}

The @MicronautTest annotation turns tests into beans. And that’s why we can use the @Requires, just like we would do with a “standard” bean.

As a result, tests inside the SomeIntegrationTest will run only, when the integration-test the environment is active. (And we can set that for example by setting the environment variable- MICRONAUT_ENVIRONMENTS=integration-test).

Testing Micronaut With MockK Mocks

As the last thing in our tutorial about testing Micronaut with Kotlin, let’s take a look at how we can mock things using the MockK.

Could we use Mockito? Yes. However, I find MockK better for Kotlin (DSLs <3 ).

In order to mock a bean in Micronaut, the only thing we need to do is annotate the method/inner class with the @MockBean annotation:

@MicronautTest
class AppUserControllerTestWithMocking {

  private val repo: AppUserRepository = mockk<AppUserRepository>()

  @MockBean(AppUserRepository::class)
  fun appUserRepository(): AppUserRepository = repo
}

As we can see, we introduce the AppUserRepository mock as the repo property, so that later, we will be able to refer to it easily in our test cases. Additionally, we add the function annotated with @MockBean, thus informing Micronaut that the AppUserRepository is the type we want to replace with our mock.

Moreover, thanks to this approach this mock will be limited only to tests defined in this class. So we can “rest assured” (hue hue) it won’t interfere with other classes.

As a result, our tests will look, as follows:

@MicronautTest
class AppUserControllerTestWithMocking {

  private val repo: AppUserRepository = mockk<AppUserRepository>()

  @Test
  fun `should return 200 OK on GET users`(spec: RequestSpecification) {
    every {
      repo.findAll()
    } returns emptyList()

    spec
      .whenever()
      .get("/users")
      .then()
      .statusCode(200)
      .header("Content-Type", "application/json")
  }

  @Test
  fun `should return user by ID`(spec: RequestSpecification) {
    val foundUser = AppUser(
      id = "123",
      firstName = "Piotr",
      lastName = "Wolak",
      email = "contact@codersee.com",
      address = Address(
        street = "street",
        city = "city",
        code = 123
      )
    )

    every {
      repo.findById("123")
    } returns Optional.of(foundUser)

    spec
      .whenever()
      .get("/users/123")
      .then()
      .statusCode(200)
      .body("id", equalTo("123"))
      .body("firstName", equalTo("Piotr"))
      .body("address.street", equalTo("street"))
      .body("address.code", equalTo(123))
  }

  @Test
  fun `should return user by ID and verify with extract`(spec: RequestSpecification) {
    val foundUser = AppUser(
      id = "123",
      firstName = "Piotr",
      lastName = "Wolak",
      email = "contact@codersee.com",
      address = Address(
        street = "street",
        city = "city",
        code = 123
      )
    )

    every {
      repo.findById("123")
    } returns Optional.of(foundUser)

    val extracted = spec
      .whenever()
      .get("/users/123")
      .then()
      .statusCode(200)
      .extractAs(AppUser::class.java)

    assertEquals(foundUser, extracted)
  }

  @Test
  fun `should create a user`(spec: RequestSpecification) {
    val request = AppUserRequest(
      firstName = "Piotr",
      lastName = "Wolak",
      email = "contact@codersee.com",
      street = "Street",
      city = "City",
      code = 123,
    )

    val createdUser = AppUser(
      id = "123",
      firstName = "Piotr",
      lastName = "Wolak",
      email = "contact@codersee.com",
      address = Address(
        street = "street",
        city = "city",
        code = 123
      )
    )

    every {
      repo.save(any())
    } returns createdUser

    val extracted = spec
      .whenever()
      .contentType(ContentType.JSON)
      .body(request)
      .post("/users")
      .then()
      .statusCode(201)
      .extractAs(AppUser::class.java)

    assertEquals(createdUser, extracted)
  }

  @MockBean(AppUserRepository::class)
  fun appUserRepository(): AppUserRepository = repo
}

Summary

And that’s all for this tutorial on how to perform testing in Micronaut with Kotlin.

Together, we’ve discovered a bunch of interesting things that I hope will be useful in your projects.

If you would like to see the codebase for this tutorial, then check out this GitHub repository. Or, if you are interested in learning more about Micronaut, then check out my other posts.

Let me know your thoughts in the comments section below! 🙂

The post Testing Micronaut Application in Kotlin appeared first on Codersee blog- Kotlin on the backend.

In this short article, I will show you how to fix this issue based on the example project.

Trigger The CodecCacheKey in Micronaut Test

Before I show you how to fix this issue, let me quickly introduce you to how I trigger the CodecCacheKey issue when writing tests in Micronaut. (If you are interested in the whole project, check this article about Micronaut with MongoDB).

So firstly, I created a simple AppUser data class:

import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity

@MappedEntity
data class AppUser(
  @field:Id
  @field:GeneratedValue
  val id: String? = null,
  val firstName: String,
  val lastName: String,
  val email: String,
  val address: Address
)

Nothing spectacular. Just a simple class with a few annotations necessary to work with MongoDB and generate identifiers automatically.

As the next step, I added the repository, which looked, as follows:

@MongoRepository
interface AppUserRepository : CrudRepository<AppUser, String> {
 
  // few methods 
}

And all of that together with other classes that are not important in this tutorial, created a structure, like this:

So, lastly, I added a simple test with @MicronautTest, JUnit 5, and REST Assured to test whether my REST endpoint returns users from the Mongo database:

@MicronautTest
class AppUserControllerTestWithoutMocking {

  @Test
  fun `should return 200 OK on GET users`(spec: RequestSpecification) {
    spec
      .`when`()
      .get("/users")
      .then()
      .statusCode(200)
      .header("Content-Type", "application/json")
  }
}

As a result, instead of the beautiful, green icon indicating that everything is fine, I got the following:

[io-executor-thread-1] ERROR i.m.http.server.RouteExecutor - Unexpected error occurred: Can't find a codec for CodecCacheKey{clazz=class com.codersee.model.AppUser, types=null}.
org.bson.codecs.configuration.CodecConfigurationException: Can't find a codec for CodecCacheKey{clazz=class com.codersee.model.AppUser, types=null}.
	at org.bson.internal.ProvidersCodecRegistry.lambda$get$0(ProvidersCodecRegistry.java:87)
	at java.base/java.util.Optional.orElseGet(Optional.java:364)
	at org.bson.internal.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:80)
	at org.bson.internal.ProvidersCodecRegistry.get(ProvidersCodecRegistry.java:50)
	at com.mongodb.internal.operation.Operations.createFindOperation(Operations.java:188)
...

Moreover, when I ran the application manually and tested using a real MongoDB instance, everything worked fine.

How To Fix CodecCacheKey Issue?

In order to fix the issue, I created a new file- called application-test.properties in the resources directory and put the following:

mongodb.package-names=com.codersee.model

But what exactly does it do?

Well, firstly, the application-test name of the file instructs the Micronaut framework to use this property file only when running tests.

Secondly, with the mongodb.package-names, I set package names to allow for POJOs. And that’s why I put the com.codersee.model only.

And voila, that’s all 🙂

Summary

And basically, that’s all for this short tutorial on how to fix the issue with CodecCacheKey in Micronaut.

Thank you for being here, and if you would like to learn more about the framework, then check out other posts from the Micronaut category.

If you would like to see the codebase for this tutorial, please refer to my GitHub repository.

The post Fix “Can’t find a codec for CodecCacheKey” in Micronaut appeared first on Codersee blog- Kotlin on the backend.