Introducing wiremock-micronaut
WireMock for your Micronaut 5 tests
On this page
WireMock and Micronaut are two things I really like, so it was only a matter of time before the two came together :)
Say hello to wiremock-micronaut, a small library that makes testing HTTP clients in Micronaut 5 apps a whole lot nicer.
The problem
Testing an HTTP client properly means standing up a WireMock server, getting its URL into your Micronaut config before the beans that need it are created, and then getting hold of the server in your test so you can stub things. None of that is hard on its own, but it is the same plumbing every time, and it is easy to get the ordering wrong.
I wanted that bit to just go away. WireMock has an official Spring Boot integration that does all of this for you, and I wanted the same for Micronaut, including the most recent versions.
What it does
wiremock-micronaut takes care of the plumbing for you:
- It starts WireMock servers per test class
- It binds their URLs into your Micronaut configuration before any beans are created
- It injects the servers into your tests so you can stub away
The annotations and attributes deliberately mirror wiremock-spring-boot, so if you have used that one it should feel very familiar.
Already using the nahuel92 library?
If you’re coming from io.github.nahuel92:wiremock-micronaut, moving over is mostly a find and replace:
| Before | After |
|---|---|
@MicronautWireMockTest(...) |
@MicronautTest + @EnableWireMock(...) |
@ConfigureWireMock(properties = "x") |
@ConfigureWireMock(baseUrlProperties = "x") |
portProperty = "x" |
portProperties = "x" |
package io.github.nahuel92.wiremock.micronaut |
com.leeturner.wiremock.micronaut |
gRPC (WireMockGrpcService) |
Not supported |
If you need gRPC support you should definitely stick with io.github.nahuel92:wiremock-micronaut for now, until I look at adding gRPC support.
Getting started
You will need Java 25 and Micronaut 5.2.1 or later (5.x) with micronaut-test-junit5. Then add the dependency (at the time of writing, the latest release is 0.2.0):
testImplementation("io.github.leeturner:wiremock-micronaut:0.2.0")
The library brings wiremock-standalone (a shaded jar) with it, so WireMock’s own dependencies never clash with Micronaut’s.
A quick example
Annotate your test with @EnableWireMock, inject the server with @InjectWireMock, and you are good to go. Here is the Java version:
@MicronautTest
@EnableWireMock(@ConfigureWireMock(name = "users", baseUrlProperties = "users.url"))
class UsersClientTest {
@Inject UsersClient client; // @Client("${users.url}")
@InjectWireMock("users") WireMockServer users;
@Test
void fetchesAUser() {
users.stubFor(get("/users/1").willReturn(ok("alice")));
assertThat(client.user("1")).isEqualTo("alice");
}
}
And for the Kotlin folks (the test body is the same as the Java one):
@MicronautTest
@EnableWireMock(ConfigureWireMock(name = "users", baseUrlProperties = ["users.url"]))
class UsersClientTest {
@Inject lateinit var client: UsersClient
@InjectWireMock("users") lateinit var users: WireMockServer
@Test
fun fetchesAUser() {
users.stubFor(get("/users/1").willReturn(ok("alice")))
assertThat(client.user("1")).isEqualTo("alice")
}
}
No manual server lifecycle, no fiddling with property ordering, just stubs and assertions. Servers are reset before each test and stopped after the test class.
There’s more
Once the basics were in place I added a few more things:
- Multiple servers, for when your app talks to more than one service. Give each server its own property names.
- SSE and message stubs, using WireMock’s message stubs and Server-Sent Events support, with no extra configuration.
- Pyronaut support: Pyronaut apps are Micronaut apps written in Python, and the extension works in their JUnit 5 tests, whether those are written in Java or as Python test modules. pytest tests don’t run through JUnit, so it does nothing there.
The README has examples for all of these.
Good to know
One limitation up front:
@EnableWireMockand@ConfigureWireMockbelong on the top-level test class, not on@Nestedclasses
It is also versioned as 0.x while WireMock 4 is in beta, with 1.0.0 to follow WireMock 4 GA, so expect things to settle as WireMock 4 does.
Give it a try
If you give it a go, I would love to know how it goes. Bug reports and ideas are very welcome in the issues on GitHub, and there is more on the project page.
Comments