Introduction to Testing Micronaut With JUnit 5

1. Overview

Micronaut provides first-class support for testing frameworks, including JUnit 5 and Spock. JUnit 5 is widely used in the Java ecosystem, and Micronaut integrates with it through dedicated testing modules that simplify writing both unit and integration tests.

In this tutorial, we’ll explore how to set up JUnit 5 testing in a Micronaut application. Also, we’ll write a sample test to demonstrate how Micronaut makes testing application components seamless.

2. Maven Dependencies

To write a unit test for a Macronaut application, let’s add the micronaut-test-junit5 and junit-jupiter-engine dependencies to our pom.xml:

<dependency>
    <groupId>io.micronaut.test</groupId>
    <artifactId>micronaut-test-junit5</artifactId>
    <version>4.10.2</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>6.0.1</version>
    <scope>test</scope>
</dependency>

The micronaut-test-junit5 dependency provides integration between Micronaut and JUnit 5, enabling features such as application context management and dependency injection. The junit-jupiter-engine dependency includes the test engine responsible for running JUnit tests.

Also, let’s add the junit-jupiter-api and mockito-core dependencies to the pom.xml:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>6.0.1</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.20.0</version>
    <scope>test</scope>
</dependency>

The junit-jupiter-api provides the core JUnit 5 annotations and assertion utilities, such as @Test and Assertions. The mockito-core dependency allows us to create mock objects, allowing us to isolate the unit under test by replacing real dependencies with controlled, test-specific behavior.

3. Core Testing Concepts

To write a unit test in Micronaut, we need to annotate the test class with the @MicronautTest annotation. This annotation boots the ApplicationContext, making all beans available for injection. When needed, such as when testing HTTP controllers, Micronaut starts an EmbeddedServer automatically.

Also, @MicronautTest manages the application lifecycle for us. It starts the context before the test and shuts it down afterward. This eliminates the need for manual setup. Because of this, running a test with @MicronautTest executes a real Micronaut application context.

3.1. Testing Services With Dependency Injection

Micronaut supports dependency injection in tests through the @Inject annotation. This allows us to inject any bean into the test class.

Let’s see a demonstration by bootstrapping a simple Micronaut project. First, let’s write an interface named AdditionService:

public interface AdditionService {

    Integer sum(int a, int b);

}

Here, the interface defines a simple addition contract. Using an interface also makes the service easy to mock during testing.

Next, let’s implement the interface:

@Singleton
public class AdditionServiceImpl implements AdditionService {

    @Override
    public Integer sum(int a, int b) {
        return a + b;
    }
}

Here, we define a custom implementation for the sum() method. The @Singleton annotation registers this implementation as a bean in the Micronaut application context.

Next, let’s write a simple test to test the service class:

@MicronautTest(startApplication = false)
class AdditionServiceUnitTest {

    @Inject
    AdditionService additionService;

    @Test
    void givenAdditionService_whenAddingTwoIntegers_thenReturnSum() {
        assertEquals(4,additionService.sum(2,2));
    }
}

In the code above, we inject the AdditionService into the test class, call the sum() method, and assert the result. Also, we instruct Micronaut not to start up the server with the startApplication=false option. This is great for non-HTTP tests.

3.2. Mocking a Bean

Furthermore, Micronaut allows us to mock beans using the @MockBean annotation. This is useful when we want to isolate logic or replace real implementation with test doubles.

Let’s rewrite the previous example using a mocked service. First, let’s create a new test class:

@MicronautTest
class AdditionServiceMockingUnitTest {

    @Inject
    AdditionService additionService;

    @MockBean(AdditionService.class)
    AdditionService additionService() {
        return mock(AdditionService.class);
    }
}

Here, we use the @MockBean annotation to replace the original AdditionService bean with a Mockito mock for the duration of the test.

Next, let’s write a test method to stub the behavior:

@Test
void givenAdditionService_whenAddingTwoIntegers_thenReturnSum() {
    when(additionService.sum(2, 2)).thenReturn(4);
    assertEquals(4, additionService.sum(2, 2));
}

Here, we define the expected behavior of the mocked method and verify that our code interacts correctly with it.

4. Testing HTTP Controllers

Moving on, let’s extend our example by adding a controller class:

@Controller
public class AdditionController {

    private final AdditionService additionService;

    public AdditionController(AdditionService additionService) {
        this.additionService = additionService;
    }

    @Get(uri = "/sum", produces = MediaType.TEXT_PLAIN)
    public Integer sum(@QueryValue("firstNumber") int firstNumber, 
      @QueryValue("secondNumber") int secondNumber) {
        return additionService.sum(firstNumber, secondNumber);
    }
}

In the code above, we expose a /sum endpoint that accepts two integers as query parameters and delegates the calculation to the AdditionService.

Next, let’s test the sum endpoint. First, let’s inject an HttpClient instance into our test class:

@Inject
@Client("/")
HttpClient client;

When a test class is annotated with @MicronautTest and uses @Client(“/”), Micronaut automatically starts EmbeddedServer so that HTTP requests can be executed against the application.

Next, let’s write a test for the /sum endpoint:

@Test
void givenSumUrl_whenPassingTwoIntegersAsQuery_thenReturnSum() {
    when(additionService.sum(20, 25)).thenReturn(45);
    Integer result = client.toBlocking()
      .retrieve(HttpRequest.GET("/sum?firstNumber=20&secondNumber=25"), Integer.class);

   assertEquals(45, result);
}

Here, we mock the AdditionService using @MockBean, allowing the controller to be tested in isolation. The test sends a real HTTP request to the embedded server through HttpClient, retrieves the response, and asserts that it matches the expected value.

Notably, we’re mocking the AdditionService, and the controller uses the mocked collaborator instead of the real implementation.

5. Conclusion

In this article, we learned how to set up and write JUnit tests in a Micronaut application. We discussed the core testing concepts, including using the @MicronautTest annotation, injecting beans into test classes, and mocking dependencies with @MockBean. Also, we saw how to test an HTTP controller by sending real HTTP requests through Micronaut’s embedded server.

As always, the full source code for the examples is available over on GitHub.