Injecting @Mock and @Captor in JUnit 5 Method Parameters

1. Overview

In this tutorial, we’ll see how to inject the @Mock and @Captor annotations in unit test method parameters.

We can use @Mock in our unit tests to create mock objects. On the other hand, we can use @Captor to capture and store arguments passed to mocked methods for later assertions. The introduction of JUnit 5 made it very easy to inject parameters into test methods, making room for this new feature.

2. Example Setup

For this feature to work, we need to use JUnit 5. The latest version of the library can be found in the Maven Central Repository. Let’s add the dependency to our pom.xml:

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

Mockito is a testing framework that allows us to create dynamic mock objects. Mockito Core provides the fundamental features of the framework, offering an expressive API for creating and interacting with mock objects. Let’s use its latest version:

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

Lastly, we need to use the Mockito JUnit Jupiter extension, which is responsible for integrating Mockito with JUnit 5. Let’s also add this dependency to our pom.xml:

<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-junit-jupiter</artifactId>
    <version>5.12.0</version>
    <scope>test</scope>
</dependency>

3. Injecting @Mock Through Method Parameters

First, let’s attach the Mockito extension to our unit test class:

@ExtendWith(MockitoExtension.class)
class MethodParameterInjectionUnitTest {

    // ...

}

Registering the Mockito extension allows the Mockito framework to integrate with the JUnit 5 testing framework. Thus, we can now supply our mock object as a test parameter:

@Test
void whenMockInjectedViaArgumentParameters_thenSetupCorrectly(@Mock Function<String, String> mockFunction) {
    when(mockFunction.apply("bael")).thenReturn("dung");
    assertEquals("dung", mockFunction.apply("bael"));
}

In this example, our mock function returns the String “dung” when we pass “bael” as an input. The assertion demonstrates that the mock behaves as we expect.

Besides, constructors are a kind of method, so it’s also possible to inject @Mock as a parameter of the constructor of the test class:

@ExtendWith(MockitoExtension.class)
class ConstructorInjectionUnitTest {
    
    Function<String, String> function;

    public ConstructorInjectionUnitTest(@Mock Function<String, String> functionr) {
        this.function = function;
    }
    
    @Test
    void whenInjectedViaArgumentParameters_thenSetupCorrectly() {
        when(function.apply("bael")).thenReturn("dung");
        assertEquals("dung", function.apply("bael"));
    }

}

On the whole, mock injection isn’t limited to basic unit tests. For instance, we can also inject mocks into other kinds of testable methods, like repeated tests or parameterized tests:

@ParameterizedTest
@ValueSource(strings = {"", "bael", "dung"})
void whenInjectedInParameterizedTest_thenSetupCorrectly(String input, @Mock Function<String, String> mockFunction) {
    when(mockFunction.apply(input)).thenReturn("baeldung");
    assertEquals("baeldung", mockFunction.apply(input));
}

Lastly, let’s note that the order of the method parameters matters when we inject a mock into a parameterized test. The mockFunction injected mock must come after the input test parameter for the parameter resolver to do its job correctly.

4. Injecting @Captor Through Method Parameters

ArgumentCaptors allow to check the values of objects we can’t access by other means in our tests. We can now inject @Captor through method parameters in a very similar way:

@Test
void whenArgumentCaptorInjectedViaArgumentParameters_thenSetupCorrectly(@Mock Function<String, String> mockFunction, @Captor ArgumentCaptor<String> captor) {
    mockFunction.apply("baeldung");
    verify(mockFunction).apply(captor.capture());
    assertEquals("baeldung", captor.getValue());
}

In this example, we apply our mocked function to the String “baeldung”. Then, we use the ArgumentCaptor to extract the value passed to the function call. In the end, we verify that this value is correct.

All the remarks we made about mock injection are also valid for captors. In particular, let’s see an example of injection in an @RepeatedTest this time:

@RepeatedTest(2)
void whenInjectedInRepeatedTest_thenSetupCorrectly(@Mock Function<String, String> mockFunction, @Captor ArgumentCaptor<String> captor) {
    mockFunction.apply("baeldung");
    verify(mockFunction).apply(captor.capture());
    assertEquals("baeldung", captor.getValue());
}

5. Why Use Method Argument Injection?

We’ll now look at the advantages of this new feature. First, let’s recall how we used to declare our mocks before:

Mock<Function> mock = mock(Mock.class)

In this case, the compiler issues a warning because Mockito.mock() can’t create correctly the generic type of Function. Thanks to method parameter injection, we’re able to preserve the generic type signature, and the compiler stops complaining.

Another great advantage of using method injection is spotting dependencies. Before, we needed to inspect the test code to understand the interactions with other classes. With method parameter injection, the method signature shows how our system under test interacts with other components. Furthermore, the test code is shorter and more focused towards its goal.

6. Conclusion

In this article, we saw how to inject @Mock and @Captor via method arguments. The support for constructor and method dependency injection in JUnit 5 enabled this feature. To conclude, it’s recommended to use this new feature. It may sound only like a nice-to-have at first glance, but it can enhance our code quality and readability.