Eventually, we will get the below user table:

But before we start, just a short disclaimer: although the main focus for this tutorial is the htmx / Kotlin / Ktor combination, I decided to bring Tailwind CSS to the project with the help of Material Tailwind components. This way, I wanted to showcase the code that is closer to real-life scenarios. Not a next, plain HTML example.

So, although I tried my best, please keep in mind that the HTML part may need some more love when adapting 🫡

Note: if you enjoy this content and would like to learn Ktor step-by-step, then check out my Ktor Server Pro course.

Video Tutorial

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

What is htmx?

If you are here, then there is a high chance you’ve been looking for a Kotlin & htmx combination, so you already know what it is.

Nevertheless, so we are all on on the same page:

It is a library that allows you to access modern browser features directly from HTML, rather than using javascript.

And we could add plenty of other things here, like the fact that it is small, dependency-free, and allows us to use AJAX, CSS Transitions, WebSockets, and so on.

But, IMO, the most important thing from the practical standpoint is that we can use attributes in HTML, and the library will do the “magic” for us:

<td>
  <button hx-delete="/users/7a9079f0-c5a2-45d0-b4ae-e304b6908787" hx-swap="outerHTML" hx-target="closest tr">
... the rest
   

The above following snippet means that when we click the button:

• the DELETE /users/7a9079f0-c5a2-45d0-b4ae-e304b6908787 request is made
• the closest tr element is replaced with the HTML response we receive

And I believe this is all we need to know for now.

Again, a short note from my end: the htmx documentation is a great resource, and I will refer a lot to it throughout this course to not reinvent the wheel. But at the same time, I want to deliver you a fully-contained article so that you don’t need to jump between pages 😉

Generate Ktor Project

As the first step, let’s quickly generate a new Ktor project using https://start.ktor.io/:

As we can see, the only plugin we need to select is the Kotlin HTML DSL (this way, the Routing plugin is added, too).

Regarding the config, we are going to use Ktor 3.1.1 with Netty, YAML config, and without a version catalog. But, of course, feel free to adjust it here according to your needs.

With that done, let’s download the project and import it to our IDE.

Create User Repository

Following, let’s add the repository package and introduce a simple, in-memory user repository:

data class User(
    val id: String = UUID.randomUUID().toString(),
    val firstName: String,
    val lastName: String,
    val enabled: Boolean,
    val createdAt: LocalDateTime = LocalDateTime.now(),
)
class UserRepository {
    private val users = mutableListOf(
        User(firstName = "Jane", lastName = "Doe", enabled = true),
        User(firstName = "John", lastName = "Smith", enabled = true),
        User(firstName = "Alice", lastName = "Johnson", enabled = false),
        User(firstName = "Bob", lastName = "Williams", enabled = true),
    )
    fun create(firstName: String, lastName: String, enabled: Boolean): User =
        User(firstName = firstName, lastName = lastName, enabled = enabled)
            .also(users::add)
    fun findAll(): List<User> = users
    fun delete(id: String): Boolean = users.removeIf { it.id == id }
}

As we can see, nothing spectacular. Just 3 functions responsible for creating, searching, and deleting users.

Return HTML Response in Ktor

Following, let’s add the routing package and Routing.kt:

fun Application.configureRouting(userRepository: UserRepository) {
    routing {
        get("/") {
            call.respondHtml {
                renderIndex(userRepository)
            }
        }
    }
}

And update the main Application.kt to incorporate those changes:

fun Application.module() {
    val userRepository = UserRepository()
    configureRouting(userRepository)
}

In a moment, we will add the renderIndex function, but for now, let’s focus on the above.

Long story short, the above code instructs the Ktor server to respond with the HTML response whenever it reaches the root path. By default, the localhost:8080.

Generate HTML page with Kotlin DSL

With that done, we have everything we need to start returning HTML responses. So in this section, we will prepare the baseline for htmx.

Note: if you feel that continuous server restarting is painful, please check out how to enable auto-reload in Ktor?

Render Homepage

As the first step, let’s add the html package and the renderIndex function in Index.kt:

import com.codersee.repository.UserRepository
import kotlinx.html.*
fun HTML.renderIndex(userRepository: UserRepository) {
    body {
        div {
            insertHeader()
        }
    }
}
private fun FlowContent.insertHeader() {
    h5 {
        +"Users list"
    }
}

At this point, such a structure is overengineering. Nevertheless, our codebase is about to grow quickly in this tutorial, so we rely on Kotlin extension functions from the very beginning.

And as we can see, we use the HTML that represents the root element of an HTML document. Inside it, we can define the structure in a type-safe manner, thanks to the Kotlin DSL feature. For the inner tags, we can use the FlowContent that is the marker interface for plenty of classes representing HTML tags, like div, headers, or the body.

And before we rerun the application, we must add the necessary import in Routing.kt:

import com.codersee.repository.html.renderIndex

With that done, let’s rerun the application and verify that everything is working.

Insert HTML Form

Following, let’s use the HTML DSL to define the user form.

As the first step, let’s add the Form.kt to inside the html package:

import kotlinx.html.*
fun FlowContent.insertUserForm() {
    div {
        form {
            div {
                div {
                    label {
                        htmlFor = "first-name"
                        +"First Name"
                    }
                    input {
                        type = InputType.text
                        name = "first-name"
                        id = "first-name"
                        placeholder = "First Name"
                    }
                }
                div {
                    label {
                        htmlFor = "last-name"
                        +"Last Name"
                    }
                    input {
                        type = InputType.text
                        name = "last-name"
                        id = "last-name"
                        placeholder = "Last Name"
                    }
                }
                div {
                    label {
                        +"Account enabled"
                    }
                    div {
                        div {
                            input {
                                type = InputType.radio
                                name = "enabled-radio"
                                id = "radio-button-1"
                                value = "true"
                            }
                            label {
                                htmlFor = "radio-button-1"
                                +"Yes"
                            }
                        }
                        div {
                            input {
                                type = InputType.radio
                                name = "enabled-radio"
                                id = "radio-button-2"
                                value = "false"
                                checked = true
                            }
                            label {
                                htmlFor = "radio-button-2"
                                +"No"
                            }
                        }
                    }
                }
                div {
                    button {
                        +"Add user"
                    }
                }
            }
        }
    }
}

As we can see, the Kotlin DSL allows us to define everything in a neat, structured manner. And although I had a chance to use it in various places, with HTML, it feels so…natural. We write the code pretty similar to HTML.

Of course, before heading to the next part, let’s make use of our function:

fun HTML.renderIndex(userRepository: UserRepository) {
    body {
        div {
            insertHeader()
            insertUserForm()
        }
    }
}

We can clearly see that the extraction was a good idea 😉

Create User Table

As the next step, let’s add the UserTable.kt:

import com.codersee.repository.User
import kotlinx.html.*
import java.time.format.DateTimeFormatter
fun FlowContent.insertUserTable(users: List<User>) {
    div {
        table {
            thead {
                tr {
                    th {
                        +"User"
                    }
                    th {
                        +"Status"
                    }
                    th {
                        +"Created At"
                    }
                    th {}
                }
            }
            tbody {
                id = "users-table"
                users.forEach { user ->
                    tr {
                        insertUserRowCells(user)
                    }
                }
            }
        }
    }
}
fun TR.insertUserRowCells(user: User) {
    td {
        div {
            p {
                +"${user.firstName} ${user.lastName}"
            }
        }
    }
    td {
        div {
            div {
                val enabledLabel = if (user.enabled) "Enabled" else "Disabled"
                val labelColor = if (user.enabled) "green" else "red"
                span { +enabledLabel }
            }
        }
    }
    td {
        p {
            +user.createdAt.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
        }
    }
    td {
        button {
            + "Delete"
        }
    }
}

As we can see this time, the Kotlin HTML DSL allows us to easily generate dynamic HTML tags. We use the passed user list to create a row for every user we “persisted”. We even make the decision about the label and future color based on the list.

Again, let’s get back to Routing.kt and invoke our function:

fun HTML.renderIndex(userRepository: UserRepository) {
    body {
        div {
            insertHeader()
            insertUserForm()
            insertUserTable(userRepository.findAll())
        }
    }
}

And although I am pretty sure it won’t become the eighth wonder of the World, our application starts looking similar to what we want to achieve:

htmx and Kotlin

With all of that done, we have everything prepared to start actually working with htmx and Kotlin.

Again, you will see a lot of references taken from the docs (which I encourage you to visit after this tutorial).

Import

As the first step, let’s import htmx.

Again, it is nothing else than the JavaScript library, so the only thing we need is to add it inside the script block of our HTML.

And the easiest way is to simply fetch it from their CDN and put it inside the Kotlin script DSL block:

fun HTML.renderIndex(userRepository: UserRepository) {
    head {
        script {
            src = "https://unpkg.com/htmx.org@2.0.4"
        }
    }
    body {
        div {
            insertHeader()
            insertUserForm()
            insertUserTable(userRepository.findAll())
        }
    }
}

AJAX Requests – Create User

As we saw in the very beginning, htmx allows us to define requests with attributes.

To be more specific, we can use the following attributes:

• hx-get
• hx-post
• hx-put
• hx-patch
• hx-delete

And, long story short, when the element is triggered, an AJAX request is made to the specified URL.

So, let’s update our form then:

fun FlowContent.insertUserForm() {
    div {
        form {
            attributes["hx-post"] = "/users"
... the rest

This way, our html now contains:

<form hx-post="/users">

And when we hit the Add user button, we can see that the request is triggered (but, it results in 404 response given we have no handler).

So, let’s add the endpoint responsible for user creation:

fun Application.configureRouting(userRepository: UserRepository) {
    routing {
        get("/") {
            call.respondHtml {
                renderIndex(userRepository)
            }
        }
        route("/users") {
            post {
                val formParams = call.receiveParameters()
                val firstName = formParams["first-name"]!!
                val lastName = formParams["last-name"]!!
                val enabled = formParams["enabled-radio"]!!.toBoolean()
                val createdItem = userRepository.create(firstName, lastName, enabled)
                val todoItemHtml = createHTML().tr { insertUserRowCells(createdItem) }
                call.respondText(
                    todoItemHtml,
                    contentType = ContentType.Text.Html,
                )
            }
        }
    }
}

At this point, it should not be a surprise, but we can see that in Ktor, we can do that quite easily.

Our code snippet will read the form parameters sent from the browser, “create” a new user, and return a 200 OK response with:

<tr>
  <td>
    <div>
      <p>Admiral Jahas</p>
    </div>
  </td>
  <td>
    <div>
      <div><span>Disabled</span></div>
    </div>
  </td>
  <td>
    <p>2025-03-29 08:16:40</p>
  </td>
  <td><button>Delete</button></td>
</tr>

The important thing to mention here is that respondHtml requires us to respond with whole body! So, to bypass that, we use the respondText function and set the content type as HTML.

However, when we open up the browser, we can see this:

And I am pretty sure that is not what we wanted 😀

htmx Target

Lesson one: if we want to instruct htmx to load the response into a different element than the one that made the request, we must use the hx-target attribute that takes the CSS selector, or:

• this keyword- to refer to the element with hx-target attribute
• closest, next, previous <CSS selector> (like closest div)- to target the closest ancestor element or itself
• find <CSS selector – to target the first child descendant element that matches the given CSS selector

As a proof, let’s take a look at what happened previously:

As we can see, the table row was inserted inside the form. And that does not make sense, at all.

So, to fix that, let’s target the table tbody instead:

fun FlowContent.insertUserForm() {
    div {
        form {
            attributes["hx-post"] = "/users"
            attributes["hx-target"] = "#users-table"

As a result, all the other rows are deleted, but it seems to be closer to what we want:

Swapping in htmx

Next lesson: by default, htmx replaces the innerHTML of the target element.

So, in our case, the user was added successfully. We can even refresh the page and see that the array contains all created users. However, we have not defined the hx-swap so the tbody inner HTML was deleted, and our returned one was inserted instead.

So, we must add the hx-swap with one of the following values:

• innerHTML– puts the content inside the target element
• outerHTML– replaces the entire target element with the returned content
• afterbegin– prepends the content before the first child inside the target
• beforebegin– prepends the content before the target in the target’s parent element
• beforeend– appends the content after the last child inside the target
• afterend– appends the content after the target in the target’s parent element
• delete– deletes the target element regardless of the response
• none– does not append content from response (Out of Band Swaps and Response Headers will still be processed)

And in our case, the beforeend is the one we should pick to append the created user at the end of the list:

fun FlowContent.insertUserForm() {
    div {
        form {
            attributes["hx-post"] = "/users"
            attributes["hx-target"] = "#users-table"
            attributes["hx-swap"] = "beforeend"

When we restart the app, everything works fine! 🙂

Dynamic htmx Tags in Kotlin

At this point, we know how to display and add new users with htmx. So, let’s learn how to delete them.

As the first step, let’s prepare a Ktor handler inside the route("/users") for the DELETE request:

delete("/{id}") {
    val id = call.parameters["id"]!!
    userRepository.delete(id)
    call.respond(HttpStatusCode.OK)
}

With that code, whenever a DELETE /users/{some-id} is made, we remove the user from our list and return 200 OK.

Important lesson here: for simplicity, we return 200 OK (and not 204 No Content), because by default, htmx ignores successful responses other than 200.

Following, let’s update our button:

td {
        button {
            attributes["hx-delete"] = "/users/${user.id}"
            attributes["hx-swap"] = "outerHTML"
            attributes["hx-target"] = "closest tr"

So, firstly, whenever we generate our button, we use Kotlin string interpolation to put the user identifier in the hx-delete attribute value. A neat and easy way to achieve that with Kotlin.

When it comes to swapping, we want to find the closest tr parent and swap the entire element with the response. And as the response contains nothing, it will be simply removed😉

After we rerun the application, we will see everything working perfectly fine!

Error Handling with Ktor and htmx

Following, let’s learn how we can handle any Ktor error response in htmx.

For that purpose, let’s update the POST handler in Ktor:

post {
    val formParams = call.receiveParameters()
    val firstName = formParams["first-name"]!!
    val lastName = formParams["last-name"]!!
    val enabled = formParams["enabled-radio"]!!.toBoolean()
    if (firstName.isBlank() || lastName.isBlank())
        return@post call.respond(HttpStatusCode.BadRequest)
... the rest of the code

With that validation, whenever first-name or last-name form parameter is blank, the API client receives 400 Bad Request.

After we restart the server and try to make a request without passing first or last name, we see that nothing is happening. No pop-ups, alerts, nothing. The only indication that the request is actually made is thenetwork tab of our browser.

Well, unfortunately (or fortunately?), htmx does not provide any handling out-of-the-box.

But, it throws two events:

• htmx:responseError– in the event of an error response from the server, like 400 Bad Request
• htmx:sendError– in case of connection error

So, let’s add a tiny bit of JS in Kotlin, then:

private fun BODY.insertErrorHandlingScripts() {
    script {
        +"""
            document.body.addEventListener('htmx:responseError', function(evt) {
              alert('An error occurred! HTTP status:' + evt.detail.xhr.status);
            });
            
            document.body.addEventListener('htmx:sendError', function(evt) {
              alert('Server unavailable!');
            });
        """.trimIndent()
    }
}

And let’s add this script at the end of the body when rendering the homepage:

fun HTML.renderIndex(userRepository: UserRepository) {
    head {
        script {
            src = "https://unpkg.com/htmx.org@2.0.4"
        }
    }
    body {
        div {
            insertHeader()
            insertUserForm()
            insertUserTable(userRepository.findAll())
        }
        insertErrorHandlingScripts()
    }
}

Excellent! From now on, whenever the API client receives an error response, the alert is displayed. Moreover, if we turn off our server, we will see the error response, too.

And basically, that is all for the htmx part with Kotlin. From now on, we are going to work on the styling of our application😉

Returning Images in Ktor

Before we head to the Tailwind CSS part, let’s learn one more thing in Ktor: static responses handling.

So, let’s put the below image in the resources -> img directory:

And let’s add this image as a placeholder to each row in our table:

fun TR.insertUserRowCells(user: User) {
    td {
        div {
            img {
                src = "/img/placeholder.png"
            }

When we rerun the application, we can see that it does not work.

Well, to fix that, we must instruct Ktor to serve our resources as static content:

fun Application.configureRouting(userRepository: UserRepository) {
    routing {
        staticResources("/img", "img")

This time, when we restart the application, we see that placeholders are working fine.

And we will style them in a moment 😉

Styling With Tailwind CSS

At this point, we have a fully working Kotlin and htmx integration.

So, if we already did something else than the JSON response, let’s make it nice😄

Import Tailwind

Just like with htmx, let’s use the CDN to import Tailwind to the project:

fun HTML.renderIndex(userRepository: UserRepository) {
    head {
        script {
            src = "https://unpkg.com/htmx.org@2.0.4"
        }
        script {
            src = "https://unpkg.com/@tailwindcss/browser@4"
        }
    }

Update Index

Then, let’s navigate to the Index.kt and add adjustments:

fun HTML.renderIndex(userRepository: UserRepository) {
    head {
        script {
            src = "https://unpkg.com/htmx.org@2.0.4"
        }
        script {
            src = "https://unpkg.com/@tailwindcss/browser@4"
        }
    }
    body {
        div {
            classes = setOf("m-auto max-w-5xl w-full overflow-hidden")
            insertHeader()
            insertUserForm()
            insertUserTable(userRepository.findAll())
        }
        insertErrorHandlingScripts()
    }
}
private fun FlowContent.insertHeader() {
    h5 {
        classes =
            setOf("py-8 block font-sans text-xl antialiased font-semibold leading-snug tracking-normal text-blue-gray-900")
        +"Users list"
    }
}
private fun BODY.insertErrorHandlingScripts() {
    script {
        +"""
            document.body.addEventListener('htmx:responseError', function(evt) {
              alert('An error occurred! HTTP status:' + evt.detail.xhr.status);
            });
            
            document.body.addEventListener('htmx:sendError', function(evt) {
              alert('Server unavailable!');
            });
        """.trimIndent()
    }
}

As we can see, we can use the classes in Kotlin HTML DSL to prive classes names as a Set of String values:

classes = setOf(“m-auto max-w-5xl w-full overflow-hidden”)

In my case, I prefer simply copy-pasting those values instead of separating them with colons.

Refactor Form

Then, let’s update the Form.kt:

fun FlowContent.insertUserForm() {
    div {
        classes = setOf("mx-auto w-full")
        form {
            attributes["hx-post"] = "/users"
            attributes["hx-target"] = "#users-table"
            attributes["hx-swap"] = "beforeend"
            div {
                classes = setOf("-mx-3 flex flex-wrap")
                div {
                    classes = setOf("w-full px-3 sm:w-1/4")
                    label {
                        classes = setOf("mb-3 block text-base font-medium text-[#07074D]")
                        htmlFor = "first-name"
                        +"First Name"
                    }
                    input {
                        classes =
                            setOf("w-full rounded-md border border-[#e0e0e0] bg-white py-3 px-6 text-base font-medium text-[#6B7280] outline-none focus:border-[#6A64F1] focus:shadow-md")
                        type = InputType.text
                        name = "first-name"
                        id = "first-name"
                        placeholder = "First Name"
                    }
                }
                div {
                    classes = setOf("w-full px-3 sm:w-1/4")
                    label {
                        classes = setOf("mb-3 block text-base font-medium text-[#07074D]")
                        htmlFor = "last-name"
                        +"Last Name"
                    }
                    input {
                        classes =
                            setOf("w-full rounded-md border border-[#e0e0e0] bg-white py-3 px-6 text-base font-medium text-[#6B7280] outline-none focus:border-[#6A64F1] focus:shadow-md")
                        type = InputType.text
                        name = "last-name"
                        id = "last-name"
                        placeholder = "Last Name"
                    }
                }
                div {
                    classes = setOf("w-full px-3 sm:w-1/4")
                    label {
                        classes = setOf("mb-3 block text-base font-medium text-[#07074D]")
                        +"Account enabled"
                    }
                    div {
                        classes = setOf("flex items-center space-x-6 pt-3")
                        div {
                            classes = setOf("flex items-center")
                            input {
                                classes = setOf("h-5 w-5")
                                type = InputType.radio
                                name = "enabled-radio"
                                id = "radio-button-1"
                                value = "true"
                            }
                            label {
                                classes = setOf("pl-3 text-base font-medium text-[#07074D]")
                                htmlFor = "radio-button-1"
                                +"Yes"
                            }
                        }
                        div {
                            classes = setOf("flex items-center")
                            input {
                                classes = setOf("h-5 w-5")
                                type = InputType.radio
                                name = "enabled-radio"
                                id = "radio-button-2"
                                value = "false"
                                checked = true
                            }
                            label {
                                classes = setOf("pl-3 text-base font-medium text-[#07074D]")
                                htmlFor = "radio-button-2"
                                +"No"
                            }
                        }
                    }
                }
                div {
                    classes = setOf("w-full px-3 sm:w-1/4 pt-8")
                    button {
                        classes =
                            setOf("cursor-pointer rounded-md bg-slate-800 py-3 px-8 text-center text-base font-semibold text-white outline-none")
                        +"Add user"
                    }
                }
            }
        }
    }
}

Similarly, we don’t change anything in here apart from adding a bunch of classes. A whooooole bunch of classes 🙂

Modify User Table

As the last step, let’ apply changes to our user table:

fun FlowContent.insertUserTable(users: List<User>) {
    div {
        classes = setOf("px-0 overflow-scroll")
        table {
            classes = setOf("w-full mt-4 text-left table-auto min-w-max")
            thead {
                tr {
                    th {
                        classes = setOf("p-4 border-y border-blue-gray-100 bg-blue-gray-50/50")
                        +"User"
                    }
                    th {
                        classes = setOf("p-4 border-y border-blue-gray-100 bg-blue-gray-50/50")
                        +"Status"
                    }
                    th {
                        classes = setOf("p-4 border-y border-blue-gray-100 bg-blue-gray-50/50")
                        +"Created At"
                    }
                    th {
                        classes = setOf("p-4 border-y border-blue-gray-100 bg-blue-gray-50/50")
                    }
                }
            }
            tbody {
                id = "users-table"
                users.forEach { user ->
                    tr {
                        insertUserRowCells(user)
                    }
                }
            }
        }
    }
}
fun TR.insertUserRowCells(user: User) {
    td {
        classes = setOf("p-4 border-b border-blue-gray-50")
        div {
            classes = setOf("flex items-center gap-3")
            img {
                classes = setOf("relative inline-block h-9 w-9 !rounded-full object-cover object-center")
                src = "/img/placeholder.png"
            }
            p {
                classes = setOf("block font-sans text-sm antialiased font-normal leading-normal text-blue-gray-900")
                +"${user.firstName} ${user.lastName}"
            }
        }
    }
    td {
        classes = setOf("p-4 border-b border-blue-gray-50")
        div {
            classes = setOf("w-max")
            div {
                val enabledLabel = if (user.enabled) "Enabled" else "Disabled"
                val labelColor = if (user.enabled) "green" else "red"
                classes =
                    setOf("relative grid items-center px-2 py-1 font-sans text-xs font-bold text-black-900 uppercase rounded-md select-none whitespace-nowrap bg-$labelColor-500/20")
                span { +enabledLabel }
            }
        }
    }
    td {
        classes = setOf("p-4 border-b border-blue-gray-50")
        p {
            classes = setOf("block font-sans text-sm antialiased font-normal leading-normal text-blue-gray-900")
            +user.createdAt.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
        }
    }
    td {
        classes = setOf("p-4 border-b border-blue-gray-50")
        button {
            classes =
                setOf("cursor-pointer relative h-10 max-h-[40px] w-10 max-w-[40px] select-none rounded-lg text-center align-middle font-sans text-xs font-medium uppercase text-gray-900 transition-all hover:bg-gray-900/10 active:bg-gray-900/20 disabled:pointer-events-none disabled:opacity-50 disabled:shadow-none")
            attributes["hx-delete"] = "/users/${user.id}"
            attributes["hx-swap"] = "outerHTML"
            attributes["hx-target"] = "closest tr"
            unsafe {
                +"""
                    <span class="absolute transform -translate-x-1/2 -translate-y-1/2 top-1/2 left-1/2">
                        <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
                             stroke-width="2" stroke="currentColor" class="w-6 h-6">
                            <path stroke-linecap="round" stroke-linejoin="round"
                                  d="M6 18L18 6M6 6l12 12"/>
                        </svg>
                    </span>
                """.trimIndent()
            }
        }
    }
}

And here, apart from the CSS classes, we also added the X icon with the unsafe function from Kotlin HTML DSL:

unsafe {
    +"""
        <span class="absolute transform -translate-x-1/2 -translate-y-1/2 top-1/2 left-1/2">
            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
                 stroke-width="2" stroke="currentColor" class="w-6 h-6">
                <path stroke-linecap="round" stroke-linejoin="round"
                      d="M6 18L18 6M6 6l12 12"/>
            </svg>
        </span>
    """.trimIndent()
}

And voila! When we run the application now, we should see a pretty decent-looking UI😉

Summary

That’s all for this tutorial on how to work with htmx and Kotlin HTML DSL in Ktor.

Again, if you are tired of wasting your time looking for good Ktor resources, then check out my Ktor Server Pro course:

▶️ Over 15 hours of video content divided into over 130 lessons

🛠️ Hands-on approach: together, we implement 4 actual services

✅ top technologies: you will learn not only Ktor, but also how to integrate it with modern stack including JWT, PostgreSQL, MySQL, MongoDB, Redis, and Testcontainers.

Lastly, you can find the source code for this lesson in this GitHub repository.

The post A Quick Guide to htmx in Kotlin 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:

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.

In some future articles, we will put that knowledge into action on the example of the Ktor project, emphasizing the Reactive approach. So don’t forget to follow me on LinkedIn to not miss out 🙂

Reactive Programming

If you try to search for what Reactive Programming is, you will sooner or later find The Reactive Manifesto, which is cited by almost everyone.

And in most articles, there will be something like the following diagram:

For the beginner, all of these definitions and explanations are vague and unclear. It is absolutely possible to learn it and speak about it, for example, in an interview with zero understanding whatsoever. Instead, let’s connect it to concepts that are present in software development, and don’t worry if you are not familiar with them.

Let’s take a look at another diagram that represents the concepts:

The key concepts in the Observer Pattern are “subjects” and “observers“. When a subject’s state changes, it notifies all its observers, allowing them to react accordingly.

The Iterator Pattern introduces a way to access elements of some object, most likely a collection, sequentially without exposing its internal implementation.

And as a cherry on top, Reactive Programming is tight with Functional Programming so, in essence, let’s define what Reactive Programming is in these terms. Reactive Programming leverages the Observer’s one-to-many notification and the Iterator’s sequential access, but extends them to handle continuous data flows and asynchronous interactions without defining “what” to do with data but “how” to iterate.

Streams

All mentioned before leads us to another core concept: Streams. If you are familiar with the Flows, it is basically them, if not we’ll cover them later anyway. So, a Stream is a sequence of data objects that can be consumed and processed asynchronously. What is more, you can also merge, filter, combine, and transform them to handle data successfully.

Now let’s check what Kotlin can offer in terms of the Reactive Approach. We will start with asynchronicity, and the best solution for this is Coroutines and especially Flows. But before that, let’s discuss types of streams.

“Cold” and “Hot” Streams

In terms of emitting data, we have two types of streams. On the one hand, “cold” streams are streams that can only emit data when there is someone who could consume it, in other words, if there is any observer attached. This basically means that no data would be missed and the whole chain of the items consumed.

On the other hand, we have “hot” streams. They are not dependent on any observable attached and start emitting items as soon as they are created. And here is the key difference, you could “miss” values using “hot” streams if they are not handled carefully.

Kotlin Coroutines

Quick dive into Coroutines basics, and then we will, Coroutines allow us to create an asynchronous code execution just like threads, but they are not bound to any particular thread and without callbacks.

Now for the real part, the Reactive Programming Coroutines library can offer 3 options:

• Channels
• StateFlow
• SharedFlow

Both StateFlow and SharedFlow are evolutions of the Flow which is generally a Stream I’ve mentioned before. Flow represents a sequence of values that can be computed asynchronously. But firstly, let’s start from Channels.

Channels

The first notable object is Chanel. As documentation states, Chanel provides communication between coroutines. But in terms of our topic, Chanel is a “hot” Stream in which each individual value could consume only one observer.

Nevertheless, it can have more the one observer, but the values would be delivered to the first awaited. If there are many observers that wait for the value to be delivered, some collectors will get suspended. Now let’s check a simple code example:

import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.delay
import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

suspend fun fetchStockPrice(): Double {
    delay(1000) // Simulate API call delay
    return Math.random() * 100
}

fun main() = runBlocking {
    // Create a Chanel to hold stock prices
    val stockPrices = Channel<Double>()

    // Launch a coroutine to fetch prices every second
    launch {
        while (isActive) {
            val price = fetchStockPrice()
            stockPrices.send(price)
            delay(1000)
        }
    }

    // Launch a coroutine to consume and display prices
    launch {
        for (price in stockPrices) {
            println("Current Stock Price: $$price")
        }
    }

    delay(Long.MAX_VALUE)
}

This example simulates a stock price ticker application that fetches prices from an API in real time and displays them to the user.

We used Channel to handle the asynchronous data flow and transfer data from one Coroutine to another!

SharedFlow

The SharedFlow is a Stream in all of its glory.

It is a hot stream, that can have multiple numbers of observers. We can check it out with the following code example:

import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.filter
import kotlinx.coroutines.flow.launchIn
import kotlinx.coroutines.flow.onEach
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

data class Item(val name: String, val price: Double)

fun main() = runBlocking {
    // SharedFlow to hold the cart items
    val cartItems = MutableSharedFlow<List<Item>>()

    // Launch a coroutine to print the cart on SharedFlow
    launch {
        cartItems.collect { items ->
            println("Cart Updated: $items")
        }
    }

    // Launch another coroutine to trigger order confirmation when the cart is full
    launch {
        cartItems.filter { it.size >= 3 } // Filter for 3 or more items
            .onEach { println("Order Confirmation triggered!") }
            .launchIn(this)
    }

    // Launch a coroutine to simulate adding items to the cart
    launch {
        var updatedItems = listOf(Item("Apple", 1.50))
        cartItems.emit(updatedItems)
        delay(1000)
        updatedItems = updatedItems + Item("Milk", 2.00)
        cartItems.emit(updatedItems)
        delay(1000)
        updatedItems = updatedItems + Item("Bread", 3.00)
        cartItems.emit(updatedItems)
    }

    delay(Long.MAX_VALUE)
}

In the example above, we created a shopping cart application where multiple components need to react to changes in the cart items.

SharedFlow provides a centralized way to share updates efficiently. And we can witness multiple observers at the same time.

StateFlow

The StateFlow is similar to SharedFlow. However, it is a somewhat cold stream because it requires some initial value on creation, and it always holds a value.

This basically means that it always has a value to observe. Here’s a good example:

import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

enum class PlayerState {
    Playing,
    Paused,
    Stopped
}

fun main() = runBlocking {
    // StateFlow to hold the current player state
    val playerState = MutableStateFlow(PlayerState.Stopped)

    // Launch a coroutine to print state based on StateFlow
    launch {
        playerState.collect { state ->
            println("Player State: $state")
        }
    }

    // Launch a coroutine to simulate user actions
    launch {
        // Play/pause/stop actions update the state
        playerState.emit(PlayerState.Playing)
        delay(2000)
        playerState.emit(PlayerState.Paused)
        delay(1000)
        playerState.emit(PlayerState.Stopped)
    }

    delay(Long.MAX_VALUE)
}

For this example, we use a music player application where the current playing state needs to be tracked. StateFlow provides a single source of truth for this state, with an initial value.

Other Reactive options available

The most popular alternatives are ReactiveX libraries. The main competitor is RxJava for Java basically and it’s widely used especially in Android Development. Unfortunately, RxKotlin has almost zero popularity these days due to its extensive RxJava presence.

RxJava provides extensive tools for Reactive programming, but due to its limited integration with Kotlin Coroutines, I recommend using Coroutines but keep in mind that this powerful tool is also available.

There are also lots of libraries tightly connected to Spring Boot. There are Spring WebFlux, and Project Reactor. They are provided tools in applications for building reactive systems in JVM Backend Development, but not that popular in Kotlin.

Summary

And that’s all for this article about Reactive Programming in Kotlin with Coroutines and Flows.

In the upcoming articles, we will get back to this topic and learn how to apply this knowledge with Ktor, so don’t forget to join the free newsletter to not miss it!

Lastly, if you would like to learn more about Flows, then you can find lots of useful information on the official documentation of Kotlin.

The post Reactive Programming in Kotlin: A Step-by-Step Guide appeared first on Codersee blog- Kotlin on the backend.

If you haven’t heard about it, then Kotlin Serialization is a cross-platform and multi-format framework built for this specific needs. It can be used with practically any Kotlin-based project, such as Android applications, Ktor applications, and Multiplatform (Common, JS, Native). 

Setting Up

To set up kotlinx.serialization in our project, we must add the following lines in your build.gradle.kts.

plugins {

    kotlin("jvm") version "1.9.20" // or kotlin("multiplatform")

    kotlin("plugin.serialization") version "1.9.20"

}

This will add the plugin.

Following, let’s add the implementation of the library itself:

repositories {

    mavenCentral()

}

dependencies {

    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.1")

}

Now we’re ready to go!

Basic Serialization

Simple Objects

You may not used this library yourself but you might have seen a @Serializable annotation before.

This is practically all we’re going to need to set up a serialization for a particular class, like this: 

@Serializable
data class User(
  val userId: Int,
  val userName: String
)

Now, to manually serialize it, we only need to use a Json.encodeToString().

For example:

val data = User(userId = 1, userName = "Alice")
println(
  Json.encodeToString(data)
)

The output would be the following:

{"userId":1,"userName":"Alice"}

On the other hand, to deserialize something, we’ll use Json.decodeFromString():

val data = """  
  {
    "userId": 1,
    "userName":"Alice"
  }
"""  

println(
  Json.decodeFromString(
    User.serializer(), 
    data
  )
)

The output:

User(userId=1, userName=Alice)

kotlinx.serialization has also some useful functions to work with InputStream rather than with String. However, they are experimental at the moment and require using @OptIn(ExperimentalSerializationApi::class).

What am I talking about here? The Json.encodeFromStream() and Json.decodeFromStream(), which come in handy when we are dealing with Files.

Let’s take a look at how we can get data from the file without reading it and converting it to String. It saves lots of computation time, particularly on a big scale:

@OptIn(ExperimentalSerializationApi::class)
fun deserializeFile(file: File): User {
  return Json.decodeFromStream(
    User.serializer(),
    file.inputStream()
  )
}

Similarly, to encode it to a file we will use the encodeToStream: 

@OptIn(ExperimentalSerializationApi::class)
fun serializeFile(user: User, file: File) {
  Json.encodeToStream(
    User.serializer(),
    user,
    file.outputStream()
  )
}

Nested(Referenced) Objects

As the next step, let’s talk about nested serialization.

Highly likely, that some of your classes have a property that is another class.

In such a case, there is practically no difference from the previous section, just all of our classes have to have a @Serializable annotation:

@Serializable
data class Profile(
  val id: Int,
  val user: User
)

@Serializable
data class User(
  val userId: Int,
  val userName: String
)

Let’s check it out like this:

val originalProfile = Profile(
  id = 123, 
  user = User(userId = 1, userName = "Alice")
)
  
println( 
  Json.encodeToString(
    Profile.serializer(), 
    originalProfile
  )
)  

val jsonString = """  
  {
    "id":123,
    "user": {
      "userId": 1,
      "userName":"Alice"
    }
  }
"""  

val deserializedProfile = Json.decodeFromString(
  Profile.serializer(), 
  jsonString
)
  
println(deserializedProfile)

The output:

{"id":123,"user":{"userId":1,"userName":"Alice"}}
Profile(id=123, user=User(userId=1, userName=Alice))

Lists

To serialize the whole List, we can use the ListSerializer constructor to create a serializer for any type of list, as long as we provide a serializer for the element type.

For example:

val originalUsers = listOf(
  User(userId = 1, userName = "Alice"),
  User(userId = 2, userName = "Bob")
)  

println(
  Json.encodeToString(
    ListSerializer(User.serializer()), 
    originalUsers
  )
)  

val jsonString = """ 
  [
    {"userId":1,"userName":"Alice"},
    {"userId":2,"userName":"Bob"}
  ] 
"""  

val deserializedUsers = Json.decodeFromString(
  ListSerializer(User.serializer()), 
  jsonString
)  

println(deserializedUsers)

That code will give us:

[{"userId":1,"userName":"Alice"},{"userId":2,"userName":"Bob"}]
[User(userId=1, userName=Alice), User(userId=2, userName=Bob)]

Generics

Basically, generics serialization works the same as nested objects.

The kotlinx.serialization has type-polymorphic behavior, which means that JSON relies on the actual type parameter. It will be compiled successfully if the actual generic type is a serializable class.

To check that, let’s modify our classes:

@Serializable
data class Profile<T>(
  val id: T,
  val user: Wrapper<T>
)

@Serializable
data class Wrapper<T>(val contents: T)

Now we can check how it will work with different T for user fields:

val profile1 = Profile(
  1, 
  Wrapper(
    User(userId = 1, userName = "Alice")
  )
)  
val profile2 = Profile(
  2, 
  Wrapper(42)
)  
  
val jsonProfile1 = Json.encodeToString(profile1)  
val jsonProfile2 = Json.encodeToString(profile2)  
  
println(jsonProfile1)  
println(jsonProfile2)  
  
val jsonString1 = """ 
  {
    "id": 1,
    "user": {
      "contents": {
        "userId": 1,
        "userName": "Alice"
      }
    }
  } 
"""  
val jsonString2 = """ 
  {
    "id": 2,
    "user": {
      "contents": 42
    }
  } 
"""  
  
val deserializedProfile1 = Json.decodeFromString(
  Profile.serializer(
    User.serializer()
  ),
  jsonString1
)  
val deserializedProfile2 = Json.decodeFromString(
  Profile.serializer(
    Int.serializer()
  ), 
  jsonString2
)  
  
println(deserializedProfile1)  
println(deserializedProfile2)

There will be the following output: 

{"id":1,"user":{"contents":{"userId":1,"userName":"Alice"}}}
{"id":2,"user":{"contents":42}}
Profile(id=1, user=Wrapper(contents=User(userId=1, userName=Alice)))
Profile(id=2, user=Wrapper(contents=42))

Customizing serialization and deserialization

In this paragraph, we are gonna talk about making your objects a little bit appealing with variable behavior to adjust our specific needs.

Custom names

As you have noticed, the basic name of a field is taken by default.

To create a custom name, the only thing we need is a @SerialName annotation:

@Serializable
data class User(
  @SerialName("id") val userId: Int,
  @SerialName("login") val userName: String
)

Now let’s use it as we used in the example at the beginning:

val data = User(userId = 1, userName = "Alice")
println(
  Json.encodeToString(data)
)

We’ll get:

{"id":1,"login":"Alice"}

But we must be careful- this works both ways.

After the change, we must make sure that the incoming JSON contains the names that we mentioned in the @SerialName:

val data = """{"id":1,"login":"Alice"}"""         //correct
val data = """{"userId":1,"userName":"Alice"}"""  //wrong

Default values

Now things get a little bit trickier. Default values are not encoded by default.

So, if we want them to, we need the @EncodeDefault annotation:

@Serializable
data class User(
  val userId: Int,
  @EncodeDefault val userName: String = "user"
)

This way, we could omit a userName and the serialization library will use the default value:

val data = User(userId = 1)
println(
  Json.encodeToString(data)
)

Let’s see:

{"userId":1,"userName":"user"}

Excellent, works as expected!

But here is a different situation. What if we want to deserialize a JSON with some optional fields?

For it to compile properly, we must provide a default value for these fields:

@Serializable
data class User(
  val userId: Int,
  val userName: String = "user"
)

Now we can deserialize an object like this: 

val data = """
  {
    "userId": 1
  }
"""
  
println(
  Json.decodeFromString(
    User.serializer(),
    data
  )
)

Output: 

User(userId=1, userName=user)

On the other hand, if we want an optional field to be present in JSON, we may use a @Required annotation:

@Serializable
data class User(
  val userId: Int,
  @Required val userName: String = "user"
)

If we use this class with the code before, we will get an error, which can be useful in some scenarios:

Exception in thread “main” kotlinx.serialization.MissingFieldException: Field ‘userName’ is required for type with serial name ‘com.example.User’, but it was missing

Nulls

Kotlin’s language is known for its type safety. The kotlinx.serialization knows it as well.

We cannot decode a null value into a non-nullable property or we get an exception. For example, for this class:

@Serializable
data class User(
  val userId: Int,
  val userName: String
)

We cannot expect to serialize this object below:

val data = """
  {
    "userId": 1,
     "userName": null
  }
"""
  
println(
  Json.decodeFromString(
    User.serializer(),
    data
  )
)

It will result in an error.

To avoid it, we should do this instead:

@Serializable
data class User(
  val userId: Int,
  val userName: String?
)

This time, our result will be: 

User(userId=1, userName=null)

As we can see, default values are not encoded by default.

So to get a missing property from JSON not as an optional but as a null value, we have to use @EncodeDefault:

@Serializable
data class User(
  val userId: Int,
  @EncodeDefault val userName: String? = null
)

That is what we’ll see for our class:

{"userId":1,"userName":null}

However, if we forget the annotation, this is what we will get:

{"userId":1}

Advanced Serialization

This section is probably what you are looking for if you have a complex project.

These are the most sophisticated tricks of kotlinx.serialization, but the most useful, though. And now we are going to understand how they work.

From now on everything becomes more complex. So we have to establish ground rules and basic terms.

What Exactly Is a Polymorphism?

Polymorphism in Kotlin is the ability of an object or a function to have different forms or behaviors depending on the context. A polymorphic object can belong to different classes and respond to the same method call in different ways.

There are two types of polymorphism in Kotlin: compile-time and run-time:

• Compile-time polymorphism, also known as static polymorphism, is achieved through function overloading. It allows the name of functions, i.e., the signature, to be the same but return type or parameter lists to be different.
• Run-time polymorphism, or dynamic polymorphism, is achieved through function overriding and inheritance. In the run-time polymorphism, the compiler resolves a call to overload methods at the runtime.

But there is more. For serialization, we are going to talk about different approaches. To serialize an object, we should know what that object is in the first place and can its behavior can be changed. So there are 2 more types of polymorphism:

• Closed polymorphism means that the behavior of an object is fixed and cannot be changed by subclasses or external factors.
• Open polymorphism means that the behavior of an object can be modified or extended by subclasses or external factors.
  This is how the library sees polymorphism for the most part.

The Practice Part

First things first, let’s talk about closed polymorphism in kotlinx.serialization.

The first and the most obvious thing to do is to make all of our classes serializable:

@Serializable
open class User(
  val userId: Int,
  val userName: String?
)

@Serializable
@SerialName("admin")
class Admin(
  val adminId: Int,
  val adminName: String?,
  val adminRole: String
) : User(adminId, adminName)

Let’s check it out: 

fun serializeAdmin() {
  val admin: User = Admin(
    adminId = 1,
    adminName = "Alice",
    adminRole = "Boss"
  )

  println(
    Json.encodeToString(admin)
  )
}

Everything works as expected, our Admin is indeed a user: 

{"userId":1,"userName":"Alice"}

But what will happen if we try to serialize an Admin object:

fun serializeAdmin() {
  val admin = Admin(
    adminId = 1,
    adminName = "Alice",
    adminRole = "Boss"
  )

  println(
    Json.encodeToString(admin)
  )
}

Let’s find out:

{"userId":1,"userName":"Alice","adminId":1,"adminName":"Alice","adminRole":"Boss"}

So you have to keep that in mind. This may be a bit odd.
Following this, I want to cover sealed classes as well. Not because I’m a huge fan of it, which I am, but because of its natural behavior (we know all of its children at the runtime) that helps our process:

@Serializable
sealed class User {
  abstract val userId: Int
  abstract val userName: String?
}

@Serializable
@SerialName("admin")
class Admin(
  override val userId: Int,
  override val userName: String?,
  val adminRole: String
) : User()

We are going to check our first scenario: 

fun serializeAdmin() {
  val admin: User = Admin(
    userId = 1,
    userName = "Alice",
    adminRole = "Boss"
  )

  println(
    Json.encodeToString(admin)
  )
}

As expected, now we know the type of our user beforehand: 

{"type":"admin","userId":1,"userName":"Alice","adminRole":"Boss"}

For a closed polymorphism, things get different. Now we have to create a SerializersModule and provide explicit subclasses that are to be serialized.

Let’s create an additional class to show this in action:

@Serializable
abstract class User {
  abstract val userId: Int
  abstract val userName: String?
}

@Serializable
@SerialName("admin")
class Admin(
  override val userId: Int,
  override val userName: String?,
  val adminRole: String
) : User()

@Serializable
@SerialName("guest")
class Guest(
  override val userId: Int,
  override val userName: String?,
  val guestEmail: String?
) : User()

Now comes the module:

val module = SerializersModule {
  polymorphic(User::class) {
    subclass(Admin::class, Admin.serializer())
    subclass(Guest::class, Guest.serializer())
  }
}

We’ve used a Json instance for our needs before. Now we have to create a specific instance with our module:

val format = Json { serializersModule = module }

With that done, let’s check it:

fun serializeAdmin() {
  val admin: User = Admin(
    userId = 1,
    userName = "Alice",
    adminRole = "Boss"
  )
  val guest: User = Guest(
    userId = 1,
    userName = "Alice",
    guestEmail = "guest@email.com"
  )

  println(format.encodeToString(admin))
  println(format.encodeToString(guest))
}

And this time, we get the following results: 

{"type":"admin","userId":1,"userName":"Alice","adminRole":"Boss"}
{"type":"guest","userId":1,"userName":"Alice","guestEmail":"guest@email.com"}

We can serialize classes as long as we provide corresponding subclasses.

Of course, there is a lot to cover, for example, multiple superclasses or interfaces. But let’s stop here, maybe I’ll cover it explicitly in the other article. (Let me know if you are interested in this 🙂 )

Custom serializers

For some classes, happens that the default serialization method does not fulfill our needs. Or we want to create one that reflects a unique class utilization approach. For this purpose, custom serializers are our best friends. The most common examples are Date and Color. I’m gonna focus on Date.

Basically, there are 3 main parts of our custom serializer. Let’s check how the serializer for Date might look like:

object DateSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("Date", PrimitiveKind.STRING)

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

We can already see all the necessary parts.

• The serialize function is used to turn an object into a sequence of simple values. It takes an Encoder and a value as inputs. It calls the encodeXxx functions of the Encoder to make the sequence. There is a different encodeXxx function for each simple type.
• The deserialize function is used to turn a sequence of simple values back into an object. It takes a Decoder as input and returns a value. It calls the decodeXxx functions of the Decoder to get the sequence. These functions match the encodeXxx functions of the Encoder.
• The descriptor property is used to tell how the encodeXxx and decodeXxx functions work. This helps the format to know what methods to use. Some formats can also use it to make a schema for the data.

For our purposes, we can simplify the class. If there is no particular need in the descriptor, we can use a @Serializer(forClass = …):

@Serializer(forClass = Date::class)
object DateSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

To implement our custom serializer we should use a @Serializable(with = …) annotation for the corresponding property:

@Serializable
data class Event(
  val name: String,
  @Serializable(with = DateSerializer::class)
  val date: Date
)

Let’s see that in action: 

val event = Event("Birthday Party", Date())  

val json = Json.encodeToString(event)  

println(json)

With the result: 

{"name":"Birthday Party","date":"2023-11-23 T 17:12:36.069+0300"}

As we can see, it has successfully been serialized to the desired date format.

Contextual serialization

Sometimes we need to change how we write objects as JSON at run-time, not just at compile-time, as we spoke before. This is called contextual serialization.

We can use the @Contextual annotation on a class or a property to tell Kotlin to use the ContextualSerializer class. This class will choose the right serializer for the object based on the context. We are going to use the previous serializer:

object DateAsStringSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("Date", PrimitiveKind.STRING)

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

And our class will be looking like this:

@Serializable
data class Event(
  val name: String,
  @Contextual val date: Date
)

Now we need to create a SerializersModule in which we need to specify a serializers should be used for our contextually-serializable classes.

We can simply wrap our serializer in contextual function inside the module:

private val module = SerializersModule {
  contextual<Date>(DateAsStringSerializer)
}  

Now we create a format out of Json with our module:

val format = Json { serializersModule = module }

Using our format of Json earlier, we’ll get our run-time serialization: 

val event = Event("Birthday Party", Date())  

val json = format.encodeToString(event)  

println(json)

With an expected output: 

{"name":"Birthday Party","date":"2023-11-23 T 23:20:03.421+0300"}

kotlinx.serialization Summary

And that’s all for this article about serialization in Kotlin with kotlinx.serialization.

In the upcoming articles, we will get back to this topic and learn how to apply this knowledge with Ktor, so don’t forget to join the free newsletter to not miss it!

Lastly, if you would like to learn more about kotlinx, then you can find lots of useful information on the official documentation of kotlinx. 

The post kotlinx.serialization in Kotlin- All You Need To Know appeared first on Codersee blog- Kotlin on the backend.

Note: this article is based on my Complete Kotlin Course lesson, which I highly encourage you to check out if you are looking for a comprehensive Kotlin guide.

If this is your first meeting with DSLs, then I would recommend you to check out my other article, in which I explain and show how to implement Kotlin DSL step-by-step.

Video Tutorial

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

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

Uncontrolled Scope

But before we dive into the solution with Kotlin @DslMarker, let’s understand what problem it solves first.

So as the first step, let’s prepare a simple DSL with Board, Task, Author, and Comment classes:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  val tasks: MutableList<Task> = mutableListOf()

  fun task(init: Task.() -> Unit) {
    val task = Task().apply(init)
    tasks.add(task)
  }
}

class Task {
  var title: String = ""
  var description: String = ""
  val comments: MutableList<Comment> = mutableListOf()

  fun comment(init: Comment.() -> Unit) {
    val comment = Comment().apply(init)
    comments.add(comment)
  }
}

class Comment {
  var comment: String = ""
  var author: Author = Author()

  fun author(init: Author.() -> Unit) {
    val author = Author().apply(init)
    this.author = author
  }
}

class Author {
  var name: String = ""
}

fun board(init: Board.() -> Unit): Board =
  Board()
    .apply(init)

With the following Kotlin DSL implementation, we would expect that we could introduce different Boards, with Tasks inside them, which would have some Comments written by Authors.

But let’s take a look at the following code:

fun main() {
  val board = board {
    task {
      task {
        task {
          comment {
            task { }
            author {
              task { }
              comment {
                task { }
              }
            }
          }
        }
      }
    }
  }
}

Will it compile? Unfortunately, yes.

We invoke a task within a task, within a task, and so on. Moreover, we can invoke the task, or comment functions inside the author. 

And that’s because, by default, we can call the methods of every available receiver, which can lead to such situations. 

Kotlin @DslMarker To The Rescue

At this point, we already know what the issue is and what we will use to fix it.

But what exactly does the @DslMarker do in Kotlin?

Well, in practice, we use this annotation to introduce our new custom annotations. Then, we make use of them to mark classes and receivers, thus preventing receivers marked with the same annotation from being accessed inside one another.

This way, we won’t be able to access members of the outer receiver (like the task function, which is declared inside the Board class from the Task class instances).

Let’s consider the updated example:

@DslMarker
annotation class BoardDsl

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

@BoardDsl
class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  val tasks: MutableList<Task> = mutableListOf()

  fun task(init: Task.() -> Unit) {
    val task = Task().apply(init)
    tasks.add(task)
  }
}

@BoardDsl
class Task {
  var title: String = ""
  var description: String = ""
  val comments: MutableList<Comment> = mutableListOf()

  fun comment(init: Comment.() -> Unit) {
    val comment = Comment().apply(init)
    comments.add(comment)
  }
}

@BoardDsl
class Comment {
  var comment: String = ""
  var author: Author = Author()

  fun author(init: Author.() -> Unit) {
    val author = Author().apply(init)
    this.author = author
  }
}

@BoardDsl
class Author {
  var name: String = ""
}

fun board(init: Board.() -> Unit): Board =
  Board()
    .apply(init)

fun main() {
  val board = board {
    task {  // OK
      task {  // Does not compile
        task {  // Does not compile
          comment {  // OK
            task { }  // Does not compile
            author {  // OK
              task { }  // Does not compile
              comment {  // Does not compile
                task { }  // Does not compile
              }
            }
          }
        }
      }
    }
  }
}

Firstly, we introduce the @BoardDsl annotation, which uses the @DslMarker.

Following, we must annotate every class in our hierarchy with our new annotation- this way, we make the Kotlin compiler “aware” of the hierarchy in our DSL.

Lastly, we can clearly see that the code will not compile whenever we try to nest the unwanted type inside another.

Scope Control With Kotlin @DslMarker Summary

Basically, that’s all for this tutorial on how to control scope when implementing a Kotlin DSL using the @DslMarker summary.

If you enjoy such a short, practice-focused learning approach then do not forget to check out my course and let me know in the comments section.

If you’d like to learn a bit more about the annotation itself, then the documentation may be useful to you too.

The post Scope Control With @DslMarker Annotation. Kotlin DSLs. appeared first on Codersee blog- Kotlin on the backend.