Getting started with micronaut

Table of Content

In this tutorial I will explain step-by-step how to get started with your first Hello World micronaut project with hot-reload and JUnit 5 tests.

What you need:

  • a JDK; we use OpenJDK-11
  • micronaut in your PATH (for the mn-command; version 1.2.5)
  • a Text-Editor or a source-code-editor like Visual Studio Code
  • a terminal in which you can enter your commands (Visual Studio Code already ships with terminal)

Recommended VSCode-extensions for Java:

  • Debugger for Java (Microsoft)
  • Gradle Tasks (Richard Willis)
  • Java Dependency Viewer (Microsoft)
  • Java Extension Pack (Microsoft)
  • Java Test Runner (Microsoft)
  • Language Support for Java(TM) by Red Hat (Red Hat)

Step 1: Create micronaut project

To create a micronaut project, we have to execute the mn command.
This command will generate a project-folder in the folder you are executing it.
Open up your prompt and navigate to the folder in which you want to generate the project and execute:

$ mn create-app com.example.getting-started-with-micronaut --features file-watch
$ cd getting-started-with-micronaut

This command creates a project-folder with the name getting-started-with-micronaut and uses com.example as the default package for our application.
Additionally, we are adding the file-watch-feature which will be needed for hot-reload. It will watch for file-changes in the src/main-folder and stop our app (how to automatically restart we will see later).

Step 2: Create the Hello World!-Controller and running it

Create a file with the name in the folder src/main/java/com/example and insert the content below.

package com.example;

import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Produces;

public class HelloController {

    public String helloWorld() {
        return "Hello World!";


Run the micronaut-app with

$ gradlew run

and open up your browser to http://localhost:8080/hello. You should see a Hello World!-message.
After this terminate the process (ctrl+c).

Step 3: Running with hot-reload and fixing the second-time-execution bug

To run with hot-reload we need to execute the command with the continuous-flag.

$ gradlew run --continuous

Now change the our Hello World!-message in your to something different like Hello Universe!.
As soon as you save the file, the server will be stopped and the run-command will be executed again.

This causes an exception in our execution. In fact, every second time we change something in our source-files (even without the continuous-flag), the run task fails with Not a valid class name: com.example.
To avoid this, we have to edit our build.gradle.

Open your build.gradle and look for task.withType(JavaCompile)-section (usually at the bottom of the file) and add the increment-parameter (to false). After that it should look like that:

    options.encoding = "UTF-8"
    options.incremental = false

Run again:

$ gradlew run --continuous

Now hot-reload works as expected. Test it by changing the return string of our helloWorld() in the HelloController.

Step 4: Testing with JUnit 5 (Gradle and VSCode Java Task Runner)

Testing it with hot-reload is nice, but we can automate this with JUnit-Test-cases.
With JUnit we can test our whole micronaut-app, without the need of starting our app with gradlew run.

For this we need to create a new file named in our src/test/java/com/example-folder.
The file looks like this:

package com.example;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;

import javax.inject.Inject;

import org.junit.jupiter.api.Test;

import io.micronaut.http.client.RxHttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.annotation.MicronautTest;

public class HelloControllerTest {

    RxHttpClient client;

    public void testHello() {
        String body = client.toBlocking().retrieve("/hello");

        assertEquals("Hello World!", body);

Don’t forget to change our HelloController to return Hello World!.
We can now execute the test.

  • with Gradle
    To execute the tests with gradle, simply run gradlew test in our project-folder.
    It tells you which tests succeeded (or failed) and creates a html-file with a detailed report: build/reports/tests/test/index.html
  • with VSCode
    For running tests with VSCode, we need the Java Test Runner-Extension. You can find it in the VSCode-Marketplace.
    After installing it you will see "Run Test" | "Debug Test" badges in HelloControllerTest for the class and for every of its test-methods. Additionally, a Test-icon will appear on the left side of VSCode, with which you can execute all or only one test if you wish. After the execution a Results-tab will open (only if we have min. 1 fail) reporting you all test-results.
    If you run it now, all tests will fail, because our project isn’t prepared for an IDE or a source-code-editor like VSCode by default.
    To add compatibility we simple have to execute:

    $ gradlew eclipse

    This command will prepare our project for VSCode (and of course eclipse too). You can now execute the tests.

By using JUnit for your tests you can use the whole power of testing and features like e.g. Parameterized-tests, etc.

If testing fails, because of an error like e.g. Page Not Found, make sure to run gradlew eclipse and start the test again, before blaming yourself. Run this command (gradlew eclipse) especially after changing gradle-dependencies (in build.gradle).

That’s it.

Best Page Builder Plugin
Best Digital Asset Library
Find amazing stock images
Feel free to leave a comment
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x