Micronaut testing with mock beans and clients

In real-world testing, you often need to isolate your code from external dependencies:

External APIs
Databases
Message brokers
Remote services

✅ This is where mocking becomes very important.
✅ Micronaut testing with mock beans and clients makes it easy to isolate and verify application logic without relying on external systems.

In our last post we saw Writing Integration Tests with Embedded Server

In this post, we’ll cover:

Why mocking is important
Mocking services
Mocking HTTP clients
Mocking beans for integration tests
Best practices

Micronaut testing with mock beans and clients

🏗 Why Mock in Tests?

Problem	Solution
Slow external calls	Mock responses
Unstable remote services	Isolate tests
Complex DB setup	Fake repositories
Testing edge cases	Custom mock behavior

🚀 Project Setup

Assume you have a basic Micronaut project already set up.

You need these dependencies in your Maven pom.xml:

<groupId>io.micronaut.test</groupId>

<artifactId>micronaut-test-junit5</artifactId>

</dependency>

<groupId>org.mockito</groupId>

<artifactId>mockito-core</artifactId>

</dependency>

🏫 Sample Use Case

Let’s say we have a WeatherService that calls an external weather API:

package com.kscodes.micronaut.services;

import jakarta.inject.Singleton;

@Singleton

public class WeatherService {

public String getWeather(String city) {

// Calls external API in real implementation

return "Sunny in " + city;

}

We want to mock this service while testing a controller that uses it.

🧪 Mocking Beans in Micronaut

Micronaut provides @MockBean annotation to replace real beans during tests.

✅ Example Controller

package com.kscodes.micronaut.controllers;

import com.kscodes.micronaut.services.WeatherService;

import io.micronaut.http.annotation.*;

@Controller("/weather")

public class WeatherController {

private final WeatherService weatherService;

public WeatherController(WeatherService weatherService) {

this.weatherService = weatherService;

}

@Get("/{city}")

public String getWeather(String city) {

return weatherService.getWeather(city);

}

✅ Integration Test with Mocked Bean

package com.kscodes.micronaut;

import com.kscodes.micronaut.services.WeatherService;

import io.micronaut.http.client.HttpClient;

import io.micronaut.http.client.annotation.Client;

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;

import jakarta.inject.Inject;

import org.junit.jupiter.api.Test;

import org.mockito.Mockito;

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

@MicronautTest

class WeatherControllerTest {

@Inject

@Client("/")

HttpClient httpClient;

@Inject

WeatherService weatherService;

@Test

void testWeatherWithMock() {

Mockito.when(weatherService.getWeather("Mumbai")).thenReturn("Mocked Sunny in Mumbai");

String response = httpClient.toBlocking().retrieve("/weather/Mumbai");

assertEquals("Mocked Sunny in Mumbai", response);

}

✅ Registering the MockBean

You must tell Micronaut to replace the original bean with a mock:

package com.kscodes.micronaut;

import com.kscodes.micronaut.services.WeatherService;

import io.micronaut.context.annotation.Factory;

import io.micronaut.test.annotation.MockBean;

import org.mockito.Mockito;

@Factory

public class MockFactory {

@MockBean(WeatherService.class)

WeatherService weatherService() {

return Mockito.mock(WeatherService.class);

}

✅ This ensures:

Micronaut replaces original WeatherService with mock.
The mock participates in dependency injection.
You can inject it directly and configure its behavior.

🔬 Mocking HTTP Clients (`@Client`)

Micronaut also allows you to mock HTTP clients used for external API calls.

✅ Sample Client

package com.kscodes.micronaut.clients;

import io.micronaut.http.annotation.Get;

import io.micronaut.http.client.annotation.Client;

@Client("https://api.weather.com")

public interface WeatherApiClient {

@Get("/current?city={city}")

String getWeather(String city);

}

✅ Service that uses the client

package com.kscodes.micronaut.services;

import com.kscodes.micronaut.clients.WeatherApiClient;

import jakarta.inject.Singleton;

@Singleton

public class WeatherService {

private final WeatherApiClient weatherApiClient;

public WeatherService(WeatherApiClient weatherApiClient) {

this.weatherApiClient = weatherApiClient;

}

public String getWeather(String city) {

return weatherApiClient.getWeather(city);

}

✅ Test with Mocked HTTP Client

package com.kscodes.micronaut;

import com.kscodes.micronaut.clients.WeatherApiClient;

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;

import jakarta.inject.Inject;

import org.junit.jupiter.api.Test;

import org.mockito.Mockito;

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

@MicronautTest

class WeatherApiClientTest {

@Inject

WeatherApiClient weatherApiClient;

@Test

void testClientMock() {

Mockito.when(weatherApiClient.getWeather("Pune")).thenReturn("Mocked Rainy in Pune");

String response = weatherApiClient.getWeather("Pune");

assertEquals("Mocked Rainy in Pune", response);

}

✅ Register MockBean for HTTP Client

package com.kscodes.micronaut;

import com.kscodes.micronaut.clients.WeatherApiClient;

import io.micronaut.context.annotation.Factory;

import io.micronaut.test.annotation.MockBean;

import org.mockito.Mockito;

@Factory

public class ClientMockFactory {

@MockBean(WeatherApiClient.class)

WeatherApiClient weatherApiClient() {

return Mockito.mock(WeatherApiClient.class);

}

⚠ Common Mistakes

Problem	Cause	Solution
Real bean still used	MockBean not registered	Use `@MockBean` properly
`NullPointerException` on injection	Incorrect bean scope	Ensure proper injection
Mockito error	Mixing static methods	Use Mockito for interface or class mocks

🧰 Best Practices for Micronaut testing with mock beans and clients

✅ Always separate unit tests and integration tests.
✅ Mock external systems — not your own service logic.
✅ Use Micronaut’s @MockBean instead of Mockito’s standalone @Mock.
✅ Avoid over-mocking — sometimes better to test full stack.
✅ Use application-test.yml for isolated config.

Micronaut testing with mock beans and clients

🏗 Why Mock in Tests?

🚀 Project Setup

🏫 Sample Use Case

🧪 Mocking Beans in Micronaut

✅ Example Controller

✅ Integration Test with Mocked Bean

✅ Registering the MockBean

🔬 Mocking HTTP Clients (@Client)

⚠ Common Mistakes

🧰 Best Practices for Micronaut testing with mock beans and clients

🌐 External References

🔬 Mocking HTTP Clients (`@Client`)