Creating your first Micronaut Kotlin app

Learn how to create a Micronaut app with Kotlin with a controller and a functional test.

Authors: Sergio del Amo

Micronaut Version: 1.0.0.M1

1 Getting Started

In this guide we are going to create a Micronaut app written in Kotlin.

1.1 What you will need

To complete this guide, you will need the following:

  • Some time on your hands

  • A decent text editor or IDE

  • JDK 1.8 or greater installed with JAVA_HOME configured appropriately

1.2 Solution

We recommend you to follow the instructions in the next sections and create the app step by step. However, you can go right to the completed example.

or

Then, cd into the complete folder which you will find in the root project of the downloaded/cloned project.

2 Writing the App

Create a Kotlin Micronaut app using the Micronaut Command Line Interface.

mn create-app example --features kotlin

Due to the --features kotlin flag, it generates a Kotlin Micronaut app and it uses Gradle build system. However, you could use other build tool such as Maven or other programming languages such as Java or Groovy.

If you are using Java or Kotlin and IntelliJ IDEA make sure you have enabled annotation processing.

annotationprocessorsintellij

3 Controller

In order to create a microservice that responds to "Hello World" you first need a controller.

Create a Controller:

src/main/kotlin/example/micronaut/HelloController.kt
package example.micronaut

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get

@Controller("/hello") (1)
class HelloController {

    @Get("/")  (2)
    fun index(): String {
        return "Hello World"  (3)
    }
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /hello
2 The @Get annotation is used to map the index method to all requests that use an HTTP GET
3 A String "Hello World" is returned as the result

4 Test

Speck is a Kotlin Specification Framework for the JVM.

To use Spek modify build.gradle file as described in the Spek documentation:

build.gradle
buildscript {
    repositories {
      ...
      ..
    }
    dependencies {
      ...
      ..
        classpath 'org.junit.platform:junit-platform-gradle-plugin:1.0.0'
    }
}
...
..
.
apply plugin: 'org.junit.platform.gradle.plugin'

junitPlatform {
    filters {
        engines {
            include 'spek'
        }
    }
}

repositories {
  ...
  ..
    maven { url "http://dl.bintray.com/jetbrains/spek" }
}

dependencies {
...
..
    testCompile 'org.jetbrains.spek:spek-api:1.1.5'
    testRuntime 'org.jetbrains.spek:spek-junit-platform-engine:1.1.5'
}
...
..

test {
    useJUnitPlatform()
}

Create a test which verifies that when you do a GET request to /hello you get Hello World as a response:

src/test/kotlin/example/micronaut/HelloControllerSpec.kt
package example.micronaut

import io.micronaut.context.ApplicationContext
import io.micronaut.http.client.HttpClient
import io.micronaut.runtime.server.EmbeddedServer
import org.jetbrains.spek.api.Spek
import org.jetbrains.spek.api.dsl.describe
import org.jetbrains.spek.api.dsl.on
import org.junit.Assert.assertEquals

class HomeControllerSpec: Spek({
    describe("HelloController") {
        var embeddedServer : EmbeddedServer = ApplicationContext.run(EmbeddedServer::class.java) (1)
        var client : HttpClient  = HttpClient.create(embeddedServer.url) (2)
        on("test /hello responds Hello World") {
            var rsp : String = client.toBlocking().retrieve("/hello")
            assertEquals(rsp, "Hello World")
        }
        afterGroup {
            client.close()
            embeddedServer.close()
        }

    }
})
1 To run the application from a unit test you can use the EmbeddedServer interface
2 Register a RxClient bean in the application context and point it to the embedded server URL. The EmbeddedServer interface provides the URL of the server under test which runs on a random port.

5 Testing the Application

To run the tests:

$ ./gradlew test
$ open build/reports/tests/test/index.html

6 Running the Application

Before running the Application, adapt the in build.gradle the

build.gradle
...
mainClassName = "example.micronaut.Application"
...

To run the application use the ./gradlew run command which will start the application on a random port.