Long story short, we will see:

• how to prepare a GraphQL schema,
• what imports are necessary to utilize suspended functions,
• how to expose queries, mutations, and map schema with annotated controllers,
• exception handling with GraphQlExceptionHandler

Create Project

As the first step, let’s prepare a brand new project.

To do so, let’s navigate to the Spring Initializr page and select the following imports:

The project metadata are totally up to you, but when it comes to the dependencies, we must select the Spring Reactive Web and Spring for GraphQL.

Thanks to the first one, Spring Boot configures a reactive web stack based on Project Reactor and Netty instead of Tomcat. And given we want to work with GraphQL and Kotlin coroutines, then this is a must-have for us.

The second provides support for Spring applications built on GraphQL Java. Moreover, it is the successor of the GraphQL Java Spring project from the GraphQL Java team.

Lastly, let’s download the zip package, extract and import it to our IDE.

Define GraphQL Schema

What is GraphQL Schema?

If you have ever worked with GraphQL before, then you know that compared to the REST, everything starts with schema definition.

If you haven’t, then GraphQL schema is a file typically written with Schema Definition Language (SDL) that describes how our API clients can interact with our server. To be more specific, inside it, we define the structure of returned data, as well as how consumers can fetch or send us the payloads.

And even though it may sound like a GraphQL substitute for OpenAPI specs, it is something more. In REST, OpenAPI docs are a nice addition to our project. In GraphQL, our services continuously utilize the schema definition to validate and execute requests against it.

And if you would like to learn more about GraphQL schema, then check out the official documentation later. But for now, let’s focus on the Spring / GraphQL / Kotlin combination 😉

schema.graphql in Spring

As the first step, let’s head to the resources > graphql directory in our project, and let’s insert the schema.graphql file:

type Query {
  article(id: ID!): Article
  articles: [Article!]!
}

type Mutation {
  createArticle(input: CreateArticleInput!): Article!
  addComment(articleId: ID!, input: AddCommentInput!): Comment
}

input CreateArticleInput {
  title: String!
  content: String!
  userId: ID!
}

input AddCommentInput {
  userId: String!
  content: String!
}

type User {
  id: ID!
  name: String!
}

type Article {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
  createdAt: String!
}

type Comment {
  id: ID!
  content: String!
  author: User
}

In Spring Boot, this file is registered automatically as our schema definition.

And as we can see, we defined 5 things:

• queries– how a client reads data. Every GraphQL schema must support them,
• mutations– how a client modifies data,
• inputs– used to pass structured arguments to our mutations and queries,
• types– establishing the structure of data we return,
• scalars– like String, or ID (but also Int, Float, Boolean), describing returned fields.

Moreover, we can see the exclamation mark- !. In contrast to Kotlin, in GraphQL, we must explicitly define non-nullable types. Meaning, that [Comment] describes a nullable array of nullable Comment type (Array<Comment?>?), whereas [Comment!]! is a not null array with not null items.

Spring GraphQL Schema Inspection

Following, let’s rerun our application.

As a result, we should get the following in logs:

o.s.b.a.g.GraphQlAutoConfiguration: GraphQL schema inspection:
Unmapped fields: {Query=[article, articles], Mutation=[createArticle, addComment]}
Unmapped registrations: {}
Unmapped arguments: {}
Skipped types: []

As we can see, Spring Boot verifies the schema we defined every time we start the application. And the above message simply says that we do not have handler methods for our definition.

Let’s fix that then 😉

Create Models

As the next step, let’s add Kotlin data classes to our Spring Boot project. They will be later used to serialize and deserialize data defined in our GraphQL schema.

To do so, let’s add the Models.kt:

data class User(
    val id: String,
    val name: String,
)
data class Article(
    val id: String,
    val title: String,
    val content: String,
    val authorId: String,
    val createdAt: String,
)
data class Comment(
    val id: String,
    val content: String,
    val articleId: String,
    val userId: String,
)
data class CreateArticleInput(
    val title: String,
    val content: String,
    val userId: String,
)
data class AddCommentInput(
    val content: String,
    val userId: String,
)

As we can see, nothing spectacular here. The only interesting fact is that the ID is serialized in the same way as a String.

QueryMapping as suspend fun

Following, let’s learn how the Spring for GraphQL works with Kotlin coroutines.

According to the documentation:

Kotlin coroutine and Flow are adapted to Mono and Flux.

Which means that whenever we use the Spring WebFlux, Spring automatically converts our suspended functions Mono and functions that return Flow to Flux .

Implement Article Service

Before we head to the GraphQL part, let’s make some small preparations.

Let’s insert the ArticleService:

@Component
object ArticleService {
    private val articles = mutableListOf(
        Article(
            id = "article-id-1",
            title = "article-title-1",
            content = "article-content-1",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-2",
            title = "article-title-2",
            content = "article-content-2",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-3",
            title = "article-title-3",
            content = "article-content-3",
            authorId = "user-id-3",
            createdAt = LocalDateTime.now().toString()
        ),
    )
    suspend fun findArticleById(id: String): Article? {
        delay(100)
        return articles.firstOrNull { it.id == id }
    }
}

As we can see, we use my favorite, in-memory database called mutable list (😉) and expose findArticleById – a suspended function.

This function will either find the desired article by ID or return a null value.

Add ArticleController

With that done, let’s add the ArticleController:

@Controller
class ArticleController(
    private val articleService: ArticleService,
) {
    @QueryMapping
    suspend fun article(@Argument id: String): Article? =
        articleService.findArticleById(id)
}

As we can see, thanks to the Spring GraphQL, we can leverage the annotation-based approach.

Firstly, we must annotate our class with the @Controller annotation. Then, all the methods inside it annotated with @SchemaMapping annotation will become handlers.

And @QueryMapping, @MutationMapping, or @SubscriptionMapping are nothing else than meta annotations (annotated with @SchemaMapping). This way, we achieve a more readable code.

Additionally, in Spring, we use the @Argument annotation to bind GraphQL input arguments to our Kotlin instances.

Enable GraphiQL & Test

Nextly, let’s turn on the GraphiQL– the IDE for testing GraphQL APIs (like Postman, Bruno, or Insomnia).

To do so, let’s navigate to the resources directory and change the application.properties into the application.yaml file:

spring:
  application:
    name: graphsandbox
  graphql:
    graphiql:
      enabled: true

Then, let’s open up the browser, go to http://localhost:8080/graphiql, and put the following:

query SomeRandomQuery {
  article(id: "article-id-1") {
    id
    title
  }
}

As we can see, the query name is up to us, but inside it, we must define which of the “exposed” queries we would like to use. As the input parameter, we pass the String value- article-id-1– and lastly, we define what fields we would like to get in response (that’s what the whole GraphQL is a about, right?😉).

So, as the next step, let’s run the query and check out the result:

{
  "errors": [
    {
      "message": "INTERNAL_ERROR for f337f3f3-5",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "article"
      ],
      "extensions": {
        "classification": "INTERNAL_ERROR"
      }
    }
  ],
  "data": {
    "article": null
  }
}

Unfortunately, that is not what we expected.

Moreover, when we check out logs, we should see this:

s.g.e.ExceptionResolversExceptionHandler : Unresolved NoClassDefFoundError for executionId f337f3f3-5
java.lang.NoClassDefFoundError: org/springframework/data/util/KotlinReflectionUtils
	at org.springframework.graphql.data.method.InvocableHandlerMethodSupport.invokeSuspendingFunction(InvocableHandlerMethodSupport.java:141) ~[spring-graphql-1.3.4.jar:1.3.4]
	at org.springframework.graphql.data.method.InvocableHandlerMethodSupport.doInvoke(InvocableHandlerMethodSupport.java:108) ~[spring-graphql-1.3.4.jar:1.3.4]

Fix Spring GraphQL Coroutines Issue

As we could see, the issue is caused by the missing dependency, and we can easily fix that.

To do so, let’s open up the build.gradle.kts and add the following dependency:

implementation("org.springframework.data:spring-data-commons")

Then, let’s sync the gradle project and rerun the application.

After we run the test again, we should see the following:

{
  "data": {
    "article": {
      "id": "article-id-1",
      "title": "article-title-1"
    }
  }
}

Splendid! Everything works perfectly fine😉

Spring GraphQL with Kotlin Flow

With that done, let’s learn how to work with Kotlin Flow and Spring GraphQL.

As the first step, let’s insert a new function to our ArticleService:

fun findAllArticles(): Flow<Article> = articles.asFlow()

This way, we produce a cold flow from our list of articles.

Then, let’s add a new handler:

@QueryMapping
fun articles(): Flow<Article> =
    articleService.findAllArticles()

Nothing new this time. Just like previously, we add a new function marked with @QueryMapping.

When we run the following query in GraphiQL:

query AnotherOne {
  articles {
    id
    title
    createdAt
  }
}

We should see the exact result:

{
  "data": {
    "articles": [
      {
        "id": "article-id-1",
        "title": "article-title-1",
        "createdAt": "2025-04-12T13:06:29.142469200"
      },
      {
        "id": "article-id-2",
        "title": "article-title-2",
        "createdAt": "2025-04-12T13:06:29.142469200"
      },
      {
        "id": "article-id-3",
        "title": "article-title-3",
        "createdAt": "2025-04-12T13:06:29.142469200"
      }
    ]
  }
}

@SchemaMapping

One of the greatest thing in GraphQL is the possibility to return the related data in one, single query. And if you remember our schema definition, our API should allow us to do that.

To be more specific, each article can have the author, multiple comments, and each comment also has its author.

But when we test that functionality right now:

query AnotherOne {
  articles {
    id
    title
    createdAt
    author {
      id
      name
    }
    
    comments {
      id
      content
      author {
        name
      }
    }
  }
}

The only thing we will get in response will be a looooong list of errors:

{
  "errors": [
    {
      "message": "The field at path '/articles[0]/author' was declared as a non null type, but the code involved in retrieving data has wrongly returned a null value.  The graphql specification requires that the parent field be set to null, or if that is non nullable that it bubble up null to its parent and so on. The non-nullable type is 'User' within parent type 'Article'",
      "path": [
        "articles",
        0,
        "author"
      ],
      "extensions": {
        "classification": "NullValueInNonNullableField"
      }
    }
... other errors

Of course, with Spring we can easily fix it, but we will need small preparation first.

Update Service

Firstly, let’s get back to our service and update it:

@Component
object ArticleService {
    private val articles = mutableListOf(
        Article(
            id = "article-id-1",
            title = "article-title-1",
            content = "article-content-1",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-2",
            title = "article-title-2",
            content = "article-content-2",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-3",
            title = "article-title-3",
            content = "article-content-3",
            authorId = "user-id-3",
            createdAt = LocalDateTime.now().toString()
        ),
    )
    private val users = mutableListOf(
        User(id = "user-id-1", name = "user-name-1"),
        User(id = "user-id-2", name = "user-name-2"),
        User(id = "user-id-3", name = "user-name-3"),
    )
    private val comments = mutableListOf(
        Comment(id = "comment-id-1", content = "comment-content-1", articleId = "article-id-1", userId = "user-id-3"),
        Comment(id = "comment-id-2", content = "comment-content-2", articleId = "article-id-2", userId = "user-id-3"),
        Comment(id = "comment-id-3", content = "comment-content-3", articleId = "article-id-2", userId = "user-id-2"),
        Comment(id = "comment-id-4", content = "comment-content-4", articleId = "article-id-3", userId = "user-id-3"),
    )
    
    suspend fun findArticleById(id: String): Article? {
        delay(100)
        return articles.firstOrNull { it.id == id }
    }
    fun findAllArticles(): Flow<Article> = articles.asFlow()
    suspend fun findUserById(id: String): User? {
        delay(100)
        return users.firstOrNull { it.id == id }
    }
    fun findCommentsByArticleId(id: String): Flow<Comment> =
        comments.filter { it.articleId == id }.asFlow()
}

As we can see, we added two more “tables” along with simple functions to obtain data from them.

Update @Controller

Then, let’s update our controller class:

@SchemaMapping
suspend fun author(article: Article): User =
    articleService.findUserById(article.authorId)!!
@SchemaMapping
suspend fun author(comment: Comment): User =
    articleService.findUserById(comment.userId)!!
@SchemaMapping
fun comments(article: Article): Flow<Comment> =
    articleService.findCommentsByArticleId(article.id)

As we can see, this time we leverage the @SchemaMapping annotation for our handlers. Pretty similar to what we did already.

The interesting part here is the parameters. Every handler takes the parent type as an argument. Meaning, that for the article -> author parent-child relationship, we define the function that takes the article instance as an argument. And that’s it!

Of course, please the double exclamation (!!) should not land in the real, production-ready code😉

Anyway, when we rerun our test now, we will see the following:

{
  "data": {
    "articles": [
      {
        "id": "article-id-1",
        "title": "article-title-1",
        "createdAt": "2025-04-12T13:21:17.584507600",
        "author": {
          "id": "user-id-2",
          "name": "user-name-2"
        },
        "comments": [
          {
            "id": "comment-id-1",
            "content": "comment-content-1",
            "author": {
              "name": "user-name-3"
            }
          }
        ]
      }
... more thingies 

And that’s what we expected. Awesome!

GraphQL Mutations

When we run the application right now, we see that we still miss two things that we defined- mutations.

So, before we add a new handler, let’s implement the following function in our service:

suspend fun createArticle(input: CreateArticleInput): Article {
    delay(100)
    return Article(
        id = UUID.randomUUID().toString(),
        title = input.title,
        content = input.content,
        authorId = input.userId,
        createdAt = LocalDateTime.now().toString(),
    ).also { articles.add(it) }
}

As can be seen, we take the input, create a new Article instance, and insert that to the list.

With Kotlin also ,we can return at the same time the created instance and achieve a slightly cleaner code. To be even fancier, we could use a reference here: .also(articles::add) 😉

Then, let’s add the appropriate handler to our controller:

@MutationMapping
suspend fun createArticle(@Argument input: CreateArticleInput): Article =
    articleService.createArticle(input)

As we can see, just like with @QueryMapping, this time, we mark the handler with @MutationMapping and our argument with @Argument. Nothing else is necessary to make our mutation work.

So, given that, let’s rerun the app and test our functionality:

mutation someMutation {
  createArticle(
    input: {
      title: "Awesome codersee Kotlin article", 
      content: "Some content", 
      userId: "user-id-3"
    }
  ) {
    id
    title
    content
    author {
      id
      name
    }
  }
}

As a result, we should get the following:

{
  "data": {
    "createArticle": {
      "id": "0e51a902-835b-4e55-9b4a-f2dccd242ea7",
      "title": "Awesome codersee Kotlin article",
      "content": "Some content",
      "author": {
        "id": "user-id-3",
        "name": "user-name-3"
      }
    }
  }
}

Wonderful! We can see that with GraphQL mutations, we can not only create/modify things on our server. With this one query, we can also retrieve the data and the dependent objects😮

Error Handling in Spring GraphQL

As the last step, let’s add one more mutation to learn more about error handling.

First, let’s add the new custom exception ot our codebase in Models.kt:

data class GenericNotFound(val msg: String) : RuntimeException(msg)

Then, let’s implement the following function in ArticleService:

suspend fun addComment(id: String, input: AddCommentInput): Comment {
        delay(100)
        users.firstOrNull { it.id == input.userId }
            ?: throw GenericNotFound("User not found")
        return articles.firstOrNull { it.id == id }
            ?.let {
                Comment(
                    id = UUID.randomUUID().toString(),
                    articleId = id,
                    content = input.content,
                    userId = input.userId,
                ).also { comments.add(it) }
            }
            ?: throw GenericNotFound("Article not found")
    }

This time, we can see a more production-ready code.

If we want to add a comment to the article, we must first check if both the desired author and article exist, right?

If that is not the case, then we throw our custom exception.

Following, let’s add a new mutation handler:

@MutationMapping
suspend fun addComment(
    @Argument id: String,
    @Argument input: AddCommentInput,
): Comment =
    articleService.addComment(id, input)

Now, when we rerun the app and execute the following test:

mutation anotherMutation {
  addComment(
    articleId: "non-existing"
    input: {userId: "user-id-1", content: "My comment"}
  ) {
    id
    content
  }
}

We will see the following error:

{
  "errors": [
    {
      "message": "INTERNAL_ERROR for f62a4c7e-1",
      "locations": [
        {
          "line": 52,
          "column": 3
        }
      ],
      "path": [
        "addComment"
      ],
      "extensions": {
        "classification": "INTERNAL_ERROR"
      }
    }
  ],
  "data": {
    "addComment": null
  }
}

And this is not what we wanted, right?

GraphQlExceptionHandler and ControllerAdvice

One of the solutions we can have in such a situation is a combination of ControllerAdvice and GraphQlExceptionHandler.

If you would like to learn more about ControllerAdvice and RestControllerAdvice, then check out my other article.

So, as the next step, let’s add the GlobalExceptionHandler class to the project:

@ControllerAdvice
class GlobalExceptionHandler {
    @GraphQlExceptionHandler
    fun handleGenericNotFound(ex: GenericNotFound): GraphQLError =
        GraphQLError.newError()
            .errorType(ErrorType.DataFetchingException)
            .message(ex.msg)
            .build()
}

As we can see, inside it, we implement a function that takes the GenericNotFound as an argument. This way, whenever our custom exception is thrown, Spring will return the GraphQLError instance with our config instead.

As a result, when we retest the application, we should get the following JSON:

{
  "errors": [
    {
      "message": "Article not found",
      "locations": [],
      "extensions": {
        "classification": "DataFetchingException"
      }
    }
  ],
  "data": {
    "addComment": null
  }
}

Spring GraphQL with Kotlin Coroutines Summary

And that’s all for this article on how to work with Kotlin coroutines and Flows in the Spring Boot GraphQL project.

As always, you can find the source code in my GitHub repostory.

The post Spring for GraphQL with Kotlin Coroutines appeared first on Codersee blog- Kotlin on the backend.

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.

Video Tutorial

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

Quick Ktor Setup

As the first step, let’s quickly prepare a basic Ktor application responding with HTML.

To do so, let’s navigate to the https://start.ktor.io page and configure the artifact first:

The choice is up to you here. From my end, I will be using the latest Ktor version with the YAML config and without the version catalog.

Then, let’s add the Kotlin HTML DSL plugin necessary for our simple example:

Lastly, let’s download the zip package, extract it, and import it to our IDE.

If you are working in IntelliJ IDEA, then please make sure that you use JDK 23, too.

You can do that in two places:

• Settings -> Build, Execution, Deployment -> Build Tools -> Gradle. Here, please set the Gradle JVM to 23
• Project Structure -> Project Settings -> Project. On this page, please set the SDK to 23 and Language level to “SDK default”

After all, please sync the gradle project and wait for the process to finish.

Expose Endpoint Returning HTML

With all of that done, let’s delete the unwanted files that were generated automatically, like Routing.kt, or Templating.kt and expose the endpoint:

fun Application.module() {

    routing {
        get("/") {
            call.respondHtml {
                body {
                    + "Hello world!"
                }
            }
        }
    }

}

As we can see, whenever we reach the root path (by default, the localhost:8080), we should see the “Hello world!” text.

The Problem

Now, let’s change the text, for example, to contain only a “Hello!” message.

What happens if we refresh the page? Nothing! The page does not reflect our code change until we restart the server manually!

And, especially when dealing with HTML, it may become a pretty tedious task.

Solution- Ktor auto-reload

It won’t be a big surprise if I say that the Ktor auto-reload feature may be a great solution here? 😉

But what is that?

Well, long story short, it its a feature that we can turn on by enabling the development mode in Ktor. And when enabled, it reloads application classes on code changes.

To be more specific, according to the documentation, Ktor listens for the changes to the following files:

/build/classes/kotlin/main/META-INF
/build/classes/kotlin/main/com/your-package-namn
/build/classes/kotlin/main/com
/build/classes/kotlin/main
/build/resources/main

And as we can see, by the code changes, we mean the generated outputs and artifacts. But the good news is that with gradle, we can easily automate the generation, too.

Lastly, I just wanted to mention that application logs are also pretty clear about what we need to do in order to enable auto-reload:

2025-03-25 06:40:49.929 [main] INFO  Application - Autoreload is disabled because the development mode is off.
2025-03-25 06:40:50.072 [main] INFO  Application - Application started in 0.374 seconds.
2025-03-25 06:40:50.363 [DefaultDispatcher-worker-2] INFO  Application - Responding at http://127.0.0.1:8080

Enable development mode

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

As the first step, we must enable the development mode. And we can do that in a few ways, so let me walk you through them.

Hardcoded Approach

When we navigate to the build.gradle.kts file, we should see the following:

application {
    mainClass = "io.ktor.server.netty.EngineMain"

    val isDevelopment: Boolean = project.ext.has("development")
    applicationDefaultJvmArgs = listOf("-Dio.ktor.development=$isDevelopment")
}

So the easy and the dummy approach would be to simply hardcode the value- -Dio.ktor.development=true:

application {
    mainClass = "io.ktor.server.netty.EngineMain"
    applicationDefaultJvmArgs = listOf("-Dio.ktor.development=true")
}

Now, when we run the app with ./gradlew run, we will see that the message disappeared, proving the development mode is enabled:

2025-03-25 07:10:15.883 [main] INFO  Application - Application started in 0.41 seconds.
2025-03-25 07:10:16.142 [main] INFO  Application - Responding at http://127.0.0.1:8080
<==========---> 83% EXECUTING [1m 13s]

But first, this approach does not work if you run the server in IntelliJ by using the green icon because, by default, it does not invoke any gradle command.

Secondly, it is hardcoded, meaning we don’t have too much control over it in various environments.

Program Argument

Another option is to bring back what we already had in the build.gradle.kts:

val isDevelopment: Boolean = project.ext.has("development")
applicationDefaultJvmArgs = listOf("-Dio.ktor.development=$isDevelopment")

And from now on, the only thing we need is the -Pdevelopment flag for the gradlew run command:

./gradlew run -Pdevelopment

It’s clearly better and gives us more flexibility.

VM options

Another option that we have on the table is to directly use the VM option we saw above- -Dio.ktor.development=true.

For that purpose, we can even completely get rid of the previous snippet from application in build.gradle.kts:

application {
    mainClass = "io.ktor.server.netty.EngineMain"
}

And now, whenever invoking the gradlew run command, we will simply put the whole arg:

./gradlew "-Dio.ktor.development=true" run

Moreover, when working with IntelliJ, we can edit our configuration to pass the same option:

So we can see that this option will work with both gradle, as well as the IntelliJ IDEA runs.

Config File

Lastly, we can also set that in the application.yaml:

ktor:
    development: true
    application:
        modules:
            - com.codersee.ApplicationKt.module
    deployment:
        port: 8080

It works exactly the same, and with environment variables can give us a lot of flexibility, too.

Automate Build

Alright, so at this point, our app is up and running with the development mode ON.

However, when we make any code change, nothing still happens!

Well, as I mentioned previously, the Ktor auto-reload feature looks for the output files. Meaning we must build the project to see the changes.

And we can do that by either running the ./gradlew build or by navigating to the Build tab in IntelliJ:

And although this works and we can now see changes without the restart, it is still not too convenient.

Well, the good news we can slightly adjust the gradlew build command and automate that:

./gradlew -t build -x test

With the -t flag (or --continuous), we enable the continuous build mode. Gradle will watch for changes in the source files, and whenever a relevant change is detected, it will automatically rerun the build task.

Additionally, we exclude the test task using the -x flag to speed up the process a little 🙂

If we would like to add that as a run configuration to IntelliJ, then it is really easy, too:

And basically, that’s all! At this point, we can add the necessary HTML changes without restarting the Ktor server.

Narrowing Down Watched Files

As I mentioned above, Ktor listens for the file updates in the following directories:

/build/classes/kotlin/main/META-INF
/build/classes/kotlin/main/com/your-package-namn
/build/classes/kotlin/main/com
/build/classes/kotlin/main
/build/resources/main

If we would like to narrow down the list of watched directories, then we can do that, for example, in the YAML config file:

ktor:
    deployment:
        watch:
            - resources

The only thing we must specify is the part of the watched patch that we want to keep.

Summary

And that’s all for this quick tutorial on how to enable the auto-reload feature in Ktor.

If you found this content useful, then check out my Ktor Server Pro course– the most comprehensive Ktor course on the market.

Thank you for being here, and see you around! 🙂

The post Auto-reload in Ktor 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.

Note: this article was created based on one of the services we implement in my Ktor Server Pro course. If you would like to learn how to expose a fully functional REST API, secure the application, and many many more, then don’t hesitate and secure your spot today😉

Before we start, I just wanted to mention that at the moment of writing KMongo is officially deprecated! Maybe you saw my previous article, maybe you saw some outdated content in some other places. Either way, we should not use that library anymore in favor of the official driver that comes in two flavors:

• MongoDB Kotlin Driver (for applications using coroutines)
• MongoDB Kotlin Sync Driver (for apps that require synchronous processing)

Video Content

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

Create & Verify MongoDB Instance

If you already have a MongoDB instance installed on your machine, feel free to skip this step.

On the other hand, if that is not the case, you can install it using the official manual. Or, if you just like me have a Docker environment, you can run the following command:

docker run --name my_awesome_mongo_name -d -p 27017:27017 mongo:8.0.4

This way, we run the Mongo docker container and expose it’s port 27017 .

And to verify it running, we can run the docker ps :

CONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS          PORTS                      NAMES
9ecd8986ac34   mongo:8.0.4   "docker-entrypoint.s…"   20 seconds ago   Up 19 seconds   0.0.0.0:27017->27017/tcp   my_awesome_mongo_name

As we can see, it was created successfully and we should be able to connect to it at localhost:27017

We can assert that, as well, for example with a free and official tool- MongoDB Compass:

And if we are able to connect, it means that we can head to the next step.

Create a New Ktor Project

Nextly, let’s navigate to the Ktor Project Generator page to create a fresh project from scratch.

If you use the IntelliJ Ultimate Edition, then you can generate it in your IDE

As we can see, we will be using Ktor 3.1.0 with Netty and configuration in the YAML file.

The important thing to mention here is that if we want to work with Kotlin coroutines, we should not select the below MongoDB plugin:

Because as we can see, this adds the MongoDB Kotlin Sync Driver for synchronous processing:

So, in our case, to keep our Ktor application as vanilla as possible, we will not add any additional plugins.

With that done, let’s hit the Download button and let’s import the project to our IDE.

Add MongoDB Async Driver to Ktor

Before adding the necessary import, let’s perform a small cleanup.

Firstly, let’s remove the Routing.kt file- we don’t need it for this tutorial.

Then, let’s navigate to the Application.kt and let’s get rid of routing config, as well. Eventually, we should have something like that:

 package com.codersee

import io.ktor.server.application.*

fun main(args: Array<String>) {
    io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {}

With that done, let’s add the MongoDB Kotlin Driver to work with coroutines.

During the configuration, we decided to use the Gradle version catalog. So now, we must navigate to the libs.versions.toml inside the gradle directory and add the mongodb-version along with mongodb-driver-kotlin:

[versions]
kotlin-version = "2.1.10"
ktor-version = "3.1.0"
logback-version = "1.4.14"
mongodb-version = "5.3.1"

[libraries]
ktor-server-core = { module = "io.ktor:ktor-server-core-jvm", version.ref = "ktor-version" }
ktor-server-netty = { module = "io.ktor:ktor-server-netty", version.ref = "ktor-version" }
logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback-version" }
ktor-server-config-yaml = { module = "io.ktor:ktor-server-config-yaml", version.ref = "ktor-version" }
ktor-server-test-host = { module = "io.ktor:ktor-server-test-host", version.ref = "ktor-version" }
kotlin-test-junit = { module = "org.jetbrains.kotlin:kotlin-test-junit", version.ref = "kotlin-version" }
mongodb-driver-kotlin = { module = "org.mongodb:mongodb-driver-kotlin-coroutine", version.ref = "mongodb-version" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin-version" }
ktor = { id = "io.ktor.plugin", version.ref = "ktor-version" }

With that done, let’s navigate to build.gradle.kts and add the following line:

implementation(libs.mongodb.driver.kotlin)

Lastly, let’s sync the gradle project so that the necessary libraries are fetched.

Introduce Model Classes

Before we can start working with coroutines, we must prepare classes that will be translated into Mongo documents and vice versa.

To do so, let’s create the Product.kt class and put the following:

import org.bson.codecs.pojo.annotations.BsonId
import org.bson.types.ObjectId

data class Product(
    @BsonId
    val id: ObjectId? = null,
    val name: String,
    val description: String,
    val price: Double,
    val category: ProductCategory,
    val tags: List<ProductTag>,
)

enum class ProductCategory {
    VIDEO_GAMES, TOOLS, HOME_AND_KITCHEN, FOOD
}

enum class ProductTag {
    EXCLUSIVE, HANDMADE, ORGANIC, BESTSELLER
}

As we can see, all fields except the id field are plain Kotlin classes. And later, they will be serialized/deserialized 1:1 when saving and retrieving from the database.

When it comes to the id field, we mark it using the @BsonId annotation. Thanks to that, it will be serialized to the _id BSON field that represents a primary key of our document. Moreover, we assign a default null value to it. This way, the value will be generated automatically.

Configure Ktor Connection to MongoDB

As the next step, let’s connect our Ktor application to the Mongo instance.

And for that purpose, let’s navigate to Application.kt and implement the following logic:

fun Application.module() {
    val settings = MongoClientSettings.builder()
        .applyConnectionString(
            ConnectionString("mongodb://localhost:27017")
        )
        .build()

    val client = MongoClient.create(settings)
    val database = client.getDatabase("application")
    val productCollection = database.getCollection<Product>("products")
}

Firstly, we instantiate the MongoClientSettings builder. A builder that allows us to configure the connection string for our database. Additionally, if you are looking for more configuration options, like reads or writes repetition, then you should start in there.

Then, we create a new client and pass our settings to it. If you would like to, then you could use another variant of the create function that takes the connection String as an argument:

public fun create(connectionString: String): MongoClient

But, in my opinion, using the builder approach is a better choice in terms of extensibility.

With that done, we get the instance of our database, by passing its name. Lastly, we obtain the MongoCollection that we will be injecting later into the product repository. Again, we pass the name of our collection, too.

To verify, let’s run our application.

As a result, we should see the following text in the logs indicating that everything is perfectly fine:

[cluster-ClusterId{value='67bd5f4689251d25d5077fb7', description='null'}-localhost:27017] INFO  org.mongodb.driver.cluster - Monitor thread successfully connected to server with description ServerDescription{address=localhost:27017, type=STANDALONE, cryptd=false, state=CONNECTED, ok=true, minWireVersion=0, maxWireVersion=25, maxDocumentSize=16777216, logicalSessionTimeoutMinutes=30, roundTripTimeNanos=26289200, minRoundTripTimeNanos=0}

MongoDB Coroutines CRUD Operations

After we did all of that preparation, we can finally create the ProductRepository class:

class ProductRepository(
    private val productCollection: MongoCollection<Product>,
) { }

And inject the collection in Application.kt :

val productRepository = ProductRepository(productCollection)

The constructor injection is a great way to make our code easier to test in the future.

Anyway, coming back to the topic, let’s learn how we can how we can perform basic CRUD operations with coroutines.

Persits Products

Initially, our products collection is empty, so let’s add the following code to start populating it:

suspend fun save(product: Product): Product? {
    val result = productCollection.insertOne(product)

    return result.insertedId
        ?.let { product.copy(id = it.asObjectId().value) }
}

First of all, we must make our function suspend. Why? Because the insertOne we use is a suspend function, so we must invoke it either from the coroutine or another suspend function.

When it comes to the persisting- the function that we use returns the InsertOneResult that allows us to either get a boolean informing if the write was acknowledged or the generated identifier of the saved product. And in my opinion, reading that and returning a Product instance with the updated field is a quite nice approach.

After that, let’s get back to the Application.kt and test this function:

val saved = runBlocking {
    productRepository.save(
        Product(
            name = "Product 1",
            description = "Description 1",
            price = 19.99,
            category = ProductCategory.TOOLS,
            tags = listOf(ProductTag.EXCLUSIVE, ProductTag.BESTSELLER)
        )
    )
}

println(saved)

I know, the good, old println 🤠

Anyway, if we run our application, we should see the following in the logs:

Product(id=67bd62f974edd96bbd59874a, name=Product 1, description=Description 1, price=19.99, category=TOOLS, tags=[EXCLUSIVE, BESTSELLER])

Additionally, when we hit the refresh button in MongoDB Compass, we should see the following:

And this proves that not only the Product was saved. But also, the application database and products collection was created by our client automatically.

Find By ID

Nextly, let’s implement the function to fetch product by identifier:

suspend fun findById(id: String): Product? {
    val objectId = ObjectId(id)

    return productCollection.find(
        eq("_id", objectId)
    ).firstOrNull()
}

This time, we use the find method. And this function returns the FindFlow which is the Flow implementation for find operations.

This function allows us to pass filters as arguments to it. And to get the particular product, we use the eq filter. One of the many filters that we can find in com.mongodb.client.model.Filters. We must remember that our identifier is of the ObjectId type, so we create a new instance from our String value.

Lastly, we invoke the firstOrNull– the terminal operator that returns the first element emitted by the flow and then cancels flow’s. We leverage the fact that only one element with such an identifier can be found in our database.

So with all of that done, let’s get back to the Application.kt and test this function:

val found = runBlocking {
    productRepository.findById("67bd62f974edd96bbd59874a")
}

val notFound = runBlocking {
    productRepository.findById("67bd62f974edd96bbd59874b")
}

// Logs: 

// Product(id=67bd62f974edd96bbd59874a, name=Product 1, description=Description 1, price=19.99, category=TOOLS, tags=[EXCLUSIVE, BESTSELLER])

// null

As we can see, our test proves that findById not only works but also it simply returns null when nothing was found. No unexpected exceptions, etc.

Updating Products

As the next step, let’s add the function responsible for updating products:

suspend fun update(id: String, product: Product): Product? {
    val objectId = ObjectId(id)

    return productCollection.findOneAndReplace(
        filter = eq("_id", objectId),
        replacement = product,
        options = FindOneAndReplaceOptions().returnDocument(ReturnDocument.AFTER)
    )
}

Again, this function is a suspended function, and again we use the same combination of the eq filter and ObjectId to find the item we are interested in.

The function that we use- findOneAndReplace– allows us to simply replace the existing document by passing a new version. Nevertheless, by default, this function returns the object before the update! And in my opinion, it makes more sense to return the updated versions in this case. And that’s why we specify the additional option.

As a note: if you would like to update just some fields, then the findOneAndUpdate may be a better choice.

With all of that done, let’s test our functionality:

val updated = runBlocking {
    productRepository.update(
        id = "67bd62f974edd96bbd59874a",
        product = Product(
            name = "Updated Product 1",
            description = "Updated Description 1",
            price = 20.11,
            category = ProductCategory.FOOD,
            tags = listOf(ProductTag.BESTSELLER)
        )
    )
}

val notUpdated = runBlocking {
    productRepository.update(
        id = "67bd62f974edd96bbd59874b",
        product = Product(
            name = "Updated Product 2",
            description = "Updated Description 3",
            price = 20.11,
            category = ProductCategory.FOOD,
            tags = listOf(ProductTag.BESTSELLER)
        )
    )
}

// Logs: 

// Product(id=67bd62f974edd96bbd59874a, name=Updated Product 1, description=Updated Description 1, price=20.11, category=FOOD, tags=[BESTSELLER])

// null

As we can see, everything works as expected. Our function returns the updated product. And moreover, it does not throw any exceptions when a product is not found!

Delete Products

Nextly, let’s take a look at how we can remove products from our database:

suspend fun deleteById(id: String): Boolean {
    val objectId = ObjectId(id)

    val deleteResult = productCollection.deleteOne(
        eq("_id", objectId)
    )

    return deleteResult.deletedCount == 1L
}

At this point of our MongoDB coroutines tutorial, I think the code is quite descriptive. We use the same pattern we did previously to find by ID and we utilize the function from DeleteResult to get the count of deleted items.

Of course, given we have only one item with a particular _id, the function returns true only if the count is equal to one.

And again, a small note from my end if you would like to return the deleted product instead, then you can use the findOneAndDelete instead.

I will skip the testing part here, you must trust me 😀

Case-insensitive Search In MongoDB

As the last step, I will show you how to utilize the function that we already know (find) to perform a case-insensitive search in MongoDB:

fun find(
    title: String,
): Flow<Product> {
    return productCollection.find(
        regex(Product::name.name, title, "i")
    )
}

As we can see, this time we make use of the regex function, that will add the… regex filter 😀 And thanks to the “i” option, the whole search will be case-insensitive.

Additionally, we make use of the name field reference. We could use a simple String value- “name”- but thanks to our approach we won’t need to remember to manually update the name in case of the update.

Lastly, I just wanted to mention here that this is one of the approaches to tackle this issue. According to the Mongo docs, we have also two more options:

1. Create a case-insensitive index with a collation strength of 1 or 2, and specify that your query uses the same collation.
2. Set the default collation strength of your collection to 1 or 2 when you create it, and do not specify a different collation in your queries and indexes.

Adding Sorting and Pagination to Search Results

Lastly, let’s make a small adjustment to add pagination and sorting to our logic.

To do so, let’s implement the Order Enum first:

enum class Order {
    ASC, DESC
}

And with that done, let’s get back to our repository:

fun find(
    title: String,
    sortBy: String,
    order: Order,
    limit: Int,
    skip: Int,
): Flow<Product> {
    val sort = when (order) {
        Order.ASC -> ascending(sortBy)
        Order.DESC -> descending(sortBy)
    }

    return productCollection.find(
        regex(Product::name.name, title, "i")
    )
        .sort(sort)
        .limit(limit)
        .skip(skip)
}

As we can see, our function allows us to pass 4 more arguments during the invocation: sortBy, order, limit, and skip.

So from now on, we can not only perform the search but also set the limit of results, ordering, as well as the order of items.

Summary

And that’s all for this tutorial on how to work with MongoDB and Kotlin coroutines in Ktor.

I hope you enjoyed it, and if you would like to learn more Ktor concepts in a fully hands-on manner, then check out my course.

Lastly, if you would like to get the whole codebase, then you can find it in this GitHub repository.

The post MongoDB with Kotlin Coroutines in Ktor appeared first on Codersee blog- Kotlin on the backend.