How to Mock Beans in Quarkus Tests With InjectMock
Replace a bean with a Mockito mock in a Quarkus test using @InjectMock, understand scope rules, Mockito.when stubs and when to use alternatives or a CDI mock.

A @QuarkusTest boots the real application once and runs many tests against it, so you cannot swap a bean by constructing the class yourself, the way you would in a plain unit test. Quarkus solves this with the proxy it already puts in front of normal scoped beans: @InjectMock replaces the instance behind that proxy for the length of one test. The result feels like Spring's @MockitoBean, which is covered in the Spring counterpart, with one rule about scopes that decides whether it works at all. This post uses Quarkus 3 and Mockito 5 on JDK 25.
Setup
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-junit5-mockito</artifactId>
<scope>test</scope>
</dependency>Without that dependency the annotation does not resolve, and the compile error mentions a missing class and not a missing dependency, which sends people looking at their imports. If the project already has plain mockito-core on the test classpath, the Quarkus module still needs to be there, because it carries the integration with the container.
Using @InjectMock
@QuarkusTest
class CheckoutResourceTest {
@InjectMock PaymentGateway gateway;
@Test
void declinedPaymentReturns402() {
Mockito.when(gateway.charge(any(), any()))
.thenReturn(PaymentResult.declined("card_declined"));
given().contentType("application/json")
.body("{\"orderId\":42,\"amount\":19.90}")
.when().post("/checkout")
.then().statusCode(402);
}
}The real PaymentGateway bean is replaced, so CheckoutResource receives the mock when the request arrives. Stubbing and verification use the normal Mockito API, and Quarkus resets the mock after the test, which means a stub in one test cannot leak into the next. Argument matching and captors work as usual, see Mockito matchers and captors. Note that the HTTP call goes through a real server on a real port, so this test exercises routing, serialization and the exception mapper, and only the gateway is fake. That is the point: it is an integration test with one boundary cut out.
The scope rule
@InjectMock needs a bean that Quarkus reaches through a client proxy. That includes @ApplicationScoped and @RequestScoped. A @Singleton has no proxy, because the container injects the instance itself, so there is nothing to redirect. Trying to mock one fails at startup with a message saying the bean is not a normal scoped bean. You have three ways out:
| Option | When |
|---|---|
Change the bean to @ApplicationScoped | You own the class and a proxy is acceptable |
@InjectMock @MockitoConfig(convertScopes = true) | You want the production scope untouched and a converted one in tests |
An @Alternative bean with @Priority in src/test | A hand written fake that every test should get |
@ApplicationScoped is the one we pick for new code. The proxy cost is a method call, and the lazy creation is usually a feature. Reaching for @Singleton is mostly a habit from Spring, where singleton is the default. Check the Quarkus testing guide for the release you run, since the options around scope conversion have moved between 3.x versions.
An alternative bean looks like this:
@Alternative @Priority(1) @ApplicationScoped
class FakePaymentGateway implements PaymentGateway {
public PaymentResult charge(Money m, Card c) { return PaymentResult.approved(); }
}Putting it in the test source set replaces the real bean for every test in the module. That suits a default fake that most tests want, with @InjectMock used in the few tests that need a different answer. The choice between fakes and mocks is argued in test doubles. One caution: an alternative with a priority also applies to tests in other classes that you forgot about, so a test that expects the real gateway can pass for the wrong reason. Name fakes Fake... and keep them in one package so they are easy to find.
Mocking REST clients
A REST Client interface needs both annotations on the field:
@InjectMock @RestClient PriceClient prices;The @RestClient qualifier has to be present, or the injection point does not match the bean and Quarkus reports an unsatisfied dependency. The client itself is covered in the REST Client post. For a client you mock on every test, consider a WireMock server instead: it checks that your code builds the request correctly, which a Mockito stub on the interface never does.
Mocks with no container: when not to use any of this
A class with constructor injection and a collaborator interface needs no container at all. Construct it with Mockito.mock(PaymentGateway.class) in a plain JUnit test, which runs in milliseconds. A @QuarkusTest pays for application startup once per module run, and every test in it after that is cheap, but a project with hundreds of them adds up. We reserve @QuarkusTest for tests that need the container: REST endpoints, transactions, configuration, interceptors.
Strict stubbing and stale stubs
The Mockito JUnit extension reports unnecessary stubbings, but @InjectMock mocks are created by Quarkus and not by that extension, so strictness is not enabled by default. A stub that is never called passes silently. Where a missing interaction would hide a bug, verify it explicitly with Mockito.verify(gateway).charge(any(), any()), and use verifyNoMoreInteractions sparingly, because it makes tests fail on harmless refactoring.
Another quirk is worth knowing. The mock is installed before each test method and reset after it, which means stubbing inside a @BeforeAll method does not work: the reset wipes it before the first test runs. Put shared stubbing in @BeforeEach.
What to mock
Mock the edges of the system: payment providers, email senders, remote services you do not control. Do not mock the database when Dev Services gives you a real one in a container, because a mocked repository proves only that you called a method with the arguments you expected, and says nothing about the SQL. A test that mocks the repository and the gateway and the clock is a test of your stubs. The balance is argued in mocking in Java without leaving tests unreal.
A realistic failure and how it reads
The most common failure in a new project is a mock that appears to do nothing. The test stubs gateway.charge(...), the request returns the real gateway's answer, and the stub is never hit. Nine times in ten the cause is a field of the wrong type: the test injects the implementation class, StripeGateway, while the resource depends on the PaymentGateway interface, so the mock replaces a bean nobody asked for. Inject by the type that the code under test uses, and when two beans implement the interface, qualify the mock the same way the real injection point is qualified.
The second cause is a bean created before the test starts. A class annotated @Startup or an eagerly initialized observer can call the real gateway during application boot, before @InjectMock installs anything. Move that call out of startup, or give the startup path its own seam, such as a configuration flag that tests turn off in application.properties under the %test profile.
Where this does not apply
For pure unit tests with no container, skip Quarkus and mock directly. For native-image tests marked @QuarkusIntegrationTest, @InjectMock is not available at all, because the application runs in a separate process from the test. There you configure behavior through test resources and external fakes. The mocking guide is at Quarkus testing with mocks, and Mockito's own documentation covers the stubbing API.


